#!/usr/bin/env node // Installed by the sync-pstack skill. // Usage: a Claude Code PreToolUse hook on Bash, Edit, MultiEdit, Write, // NotebookEdit and the desktop app's sync_with_base_branch tool, // `node .agents/pstack/guard.mjs`. // Denies an agent's `git push` that forces or deletes the branch or the // protected branch that .agents/pstack.json names: --force, -f, a short-flag // cluster holding f or d, --force-with-lease, --mirror, --delete, a `+` // refspec or a `:` refspec. It also denies any other push to the // branch, because land.mjs squashes, checks and signs each landing there, // except a dry run and a push prefixed with PSTACK_RELEASE=1, which only a // project's release skill writes. A push with no refspec, or one whose // destination is HEAD, targets the current branch, and one with --tags and no // refspec targets no branch. A matching `:` refspec and a wildcard refspec // target each branch they match. The guard reads no git config, so a push with // no refspec that `remote..push` or `push.default` sends to the branch // passes. It reads every command in the line, including one after a shell // keyword such as `then`, the bodies of `$(...)` and backticks outside single // quotes and of `<(...)` and `>(...)` outside any quotes, `eval`'s arguments // and a shell's `-c` payload wherever `-c` sits among its options, skips // heredoc bodies, passes every other command, and prints the command for the // owner to run in their own terminal. It judges each command in every directory // the shell may run it in: after `cd &&` in ``, after `cd ||` // in the earlier directory, and after `cd ;` or a newline in both, because // the `cd` may fail. A `cd` before a `|`, inside `( )` or in a list that `&` // sends to the background moves nothing after it, one that ends a pipeline // counts both ways, because zsh runs it in the current shell and bash does not, // and one whose target the guard cannot resolve, such as a variable, keeps the // earlier directory, as does a `git -C` value holding `$`, a backtick, `*`, // `?` or `[`, so such a target that leads into a checkout holding the // companion directory, or into one on the branch, passes there. A push or // companion denial names each `cd` target holding `$` or a backtick and each // `git -C` value the guard cannot resolve. A bare name also counts in the // earlier directory, because CDPATH could send it // elsewhere, and `cd ` counts where zsh swaps the operands, in // ``, where bash 3.2 moves, and in the earlier directory. The owner's // terminal never runs this hook. It denies an agent's `gh pr create` or `gh pr // new` into the branch or with no --base, because land.mjs opens those PRs; // one that names another base, such as a PR stacked on someone's head branch, // passes, and so does one where --help or -h is a flag rather than an option's // value. It denies any line whose text, with quotes and backslashes removed, // holds `actions/runs/` followed later by `/approve` or // `/pending_deployments`, whatever the client or method, so a read of pending // deployments or a commit message that spells such a path is denied too. In a // checkout that holds the config's `companion.dir`, it denies what // would delete or overwrite the files that companion repository tracks there: // `git clean -x` or `-X`, any `git clean` through its git directory, and a // checkout, switch, reset, merge or rebase to a commit without // `companion.list`. It also denies the app's base-branch sync, which refuses // the branch whenever it changes .claude files, and names the rebase to run // instead. On Edit, MultiEdit, Write and NotebookEdit it denies a file inside // the main checkout, its .git folder included, while that checkout is on the // branch or the protected branch, except the plans artifacts directory, which // holds the suggested-task ledger and the run directories; a linked worktree, // even one nested in the main checkout's folder, is its own checkout and // passes. In a checkout of this repository whose change builds a dated plan's // step, it also denies an edit of a file the step budget counts once the change // is past that budget, as status.mjs's stepLines counts it, unless a changed // decision log holds an owner "big step:" row with no later "landed as" row; // that check lets the edit through when git or the check fails. Otherwise it // refuses the edit when git or the guard itself fails, because a hook that exits // with an error lets the edit through. import { spawnSync } from 'node:child_process'; import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs'; import { homedir } from 'node:os'; import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'; import { fileURLToPath } from 'node:url'; const CONFIG = new URL('../pstack.json', import.meta.url); const BASE_SYNC = /(?:^|__)sync_with_base_branch$/u; const EDIT_TOOLS = new Set(['Edit', 'MultiEdit', 'Write', 'NotebookEdit']); const GIT_VALUE_OPTIONS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env']); const PUSH_VALUE_OPTIONS = new Set(['-o', '--push-option', '--repo', '--receive-pack', '--exec']); const PREFIXES = new Set(['sudo', 'env', 'command', 'builtin', 'exec', 'nohup', 'time', 'timeout']); const SHELLS = new Set(['bash', 'sh', 'zsh']); const KEYWORDS = new Set(['!', 'if', 'then', 'elif', 'else', 'while', 'until', 'do']); const OPERATOR = /;|&&|\|[|&]?|&(?!>)|\n|[(){}]/uy; const BARE = /(?:\\.|\$\{[^{}\s$`\\]*\}|[<>]&|&>|[$<>](?!\()|[^\s;&|(){}"'`\\$<>])+/uy; const SUBSTITUTION = /[$<>]\(/uy; function stripHeredocs(text) { const kept = []; let tag = null; for (const line of text.split('\n')) { if (tag) { if (line.trim() === tag) tag = null; continue; } kept.push(line); tag = line.match(/(? { const { words } = result.at(-1); if (joining && words.length > 0) words[words.length - 1] += word; else words.push(word); joining = true; }; let at = 0; while (at < text.length) { OPERATOR.lastIndex = at; BARE.lastIndex = at; SUBSTITUTION.lastIndex = at; if (text[at] === '"' || text[at] === "'") { const end = closingQuote(text, at + 1, text[at]); if (text[at] === '"') result.at(-1).substitutions.push(...substitutionsIn(text.slice(at + 1, end))); add(text.slice(at + 1, end)); at = end + 1; } else if (SUBSTITUTION.test(text) || text[at] === '`') { const end = text[at] === '`' ? closingTick(text, at + 1) : closingParen(text, at + 2); result.at(-1).substitutions.push(text.slice(at + (text[at] === '`' ? 1 : 2), end)); add(text.slice(at, end + 1)); at = end + 1; } else if (OPERATOR.test(text)) { result.at(-1).operator = text.slice(at, OPERATOR.lastIndex); result.push({ words: [], operator: null, substitutions: [] }); joining = false; at = OPERATOR.lastIndex; } else if (BARE.test(text)) { add(text.slice(at, BARE.lastIndex).replace(/\\(.)/gu, '$1')); at = BARE.lastIndex; } else { joining = false; at += 1; } } return result; } const unresolved = new Set(); function shellPath(word, dir) { if (/[$`*?[]/u.test(word)) return null; return word === '~' || word.startsWith('~/') ? join(homedir(), word.slice(2)) : resolve(dir, word); } function cdTargets(args, dir) { const targets = args.filter((arg) => arg !== '--' && !/^-[LPeqs@]+$/u.test(arg)); if (targets.length === 0) return [homedir()]; if (targets.length === 2) { const swapped = dir.replace(targets[0], targets[1]); return [...(swapped !== dir && existsSync(swapped) ? [swapped] : []), ...cdTargets(targets.slice(0, 1), dir), dir]; } const path = targets.length === 1 && targets[0] !== '-' ? shellPath(targets[0], dir) : null; if (!path || !existsSync(path)) return [dir]; return /^(?:\/|~(?:\/|$)|\.\.?(?:\/|$))/u.test(targets[0]) ? [path] : [path, dir]; } const GROUPS = new Set(['(', ')', '{', '}']); const STAYS = new Set([...KEYWORDS, 'builtin', 'command', 'time']); const union = (...sets) => new Set(sets.flatMap((set) => [...set])); const level = (dirs, group = null) => ({ group, start: dirs, dirs, ifOk: null, ifFailed: null, join: null, pipeline: null, closedGroup: null }); function eachCommand(command, visit, cwds, depth = 0) { const levels = [level(cwds)]; for (const { words, operator, substitutions } of segments(command)) { const here = levels.at(-1); const entry = here.pipeline ?? here.closedGroup?.start ?? (here.join === '&&' ? here.ifOk : here.join === '||' ? here.ifFailed : here.dirs); let ifOk = here.closedGroup?.after ?? entry; let ifFailed = ifOk; if (words.length > 0) { let start = 0; let wrapped = false; for (; start < words.length; start += 1) { if (PREFIXES.has(words[start])) wrapped = true; else if (!KEYWORDS.has(words[start]) && !(wrapped && /^[-\d]/u.test(words[start])) && !/^[A-Za-z_]\w*=/u.test(words[start])) break; } const prefix = words.slice(0, start); if (start < words.length) for (const dir of entry) visit(words.slice(start), prefix, dir); if (words[start] === 'cd' && prefix.every((word) => STAYS.has(word) || /^[A-Za-z_]\w*=/u.test(word))) { ifOk = new Set([...entry].flatMap((dir) => cdTargets(words.slice(start + 1), dir))); if (words.slice(start + 1).some((word) => /[$`]/u.test(word))) unresolved.add(['cd', ...words.slice(start + 1)].join(' ')); if (prefix.includes('!')) ifOk = ifFailed = union(ifOk, ifFailed); } if (depth < 4) { for (const [index, word] of words.entries()) { const rest = words.slice(index + 1); if (SHELLS.has(word.split('/').at(-1)) && rest.some((arg) => /^-[A-Za-z]*c[A-Za-z]*$/u.test(arg))) { for (const arg of rest) if (!arg.startsWith('-')) eachCommand(arg, visit, entry, depth + 1); } } for (const body of substitutions) eachCommand(body, visit, entry, depth + 1); if (words[start] === 'eval') eachCommand(words.slice(start + 1).join(' '), visit, entry, depth + 1); } } else if (!here.closedGroup && !GROUPS.has(operator)) continue; if (operator === '(' || operator === '{') { levels.push(level(entry, operator)); continue; } here.closedGroup = null; if (operator === '|' || operator === '|&') { here.pipeline = entry; continue; } // zsh runs a pipeline's last command in the current shell, and bash runs it in a subshell. if (here.pipeline) [ifOk, ifFailed] = [union(entry, ifOk), union(entry, ifFailed)]; here.pipeline = null; if (here.join === '&&') [here.ifOk, here.ifFailed] = [ifOk, union(here.ifFailed, ifFailed)]; else if (here.join === '||') [here.ifOk, here.ifFailed] = [union(here.ifOk, ifOk), ifFailed]; else [here.ifOk, here.ifFailed] = [ifOk, ifFailed]; here.join = operator === '&&' || operator === '||' ? operator : null; if (here.join) continue; if (operator !== '&') here.dirs = union(here.ifOk, here.ifFailed); if ((operator === ')' || operator === '}') && levels.length > 1) { levels.pop(); levels.at(-1).closedGroup = { start: here.start, after: here.group === '{' ? here.dirs : here.start }; } } } // The subcommand of a `git` command, its arguments, the directory it runs in // and its --git-dir, or null for any other command. function gitCommand(words, cwd) { if (words[0]?.split('/').at(-1) !== 'git') return null; let index = 1; let dir = cwd; let gitDir = null; while (words[index]?.startsWith('-')) { if (words[index] === '-C') { const path = shellPath(words[index + 1] ?? '.', dir); if (path === null) unresolved.add(`git -C ${words[index + 1]}`); dir = path ?? dir; } if (words[index] === '--git-dir') gitDir = words[index + 1] ?? ''; if (words[index].startsWith('--git-dir=')) gitDir = words[index].slice('--git-dir='.length); index += GIT_VALUE_OPTIONS.has(words[index]) ? 2 : 1; } return { sub: words[index], args: words.slice(index + 1), dir, gitDir }; } // Returns the branches a `git push` updates, whether it forces or deletes them // and whether it is a dry run, or null for any other command. function pushes(words, cwd) { const call = gitCommand(words, cwd); if (call?.sub !== 'push') return null; const { args, dir } = call; let forced = false; let every = false; let deleting = false; let dry = false; let tags = false; const positional = []; for (let at = 0; at < args.length; at += 1) { const word = args[at]; if (word === '--') { positional.push(...args.slice(at + 1)); break; } if (PUSH_VALUE_OPTIONS.has(word)) at += 1; else if (word === '--force' || word.startsWith('--force-with-lease')) forced = true; else if (word === '--mirror') forced = every = true; else if (word === '--all' || word === '--branches') every = true; else if (word === '--delete') deleting = true; else if (word === '--dry-run') dry = true; else if (word === '--tags') tags = true; else if (/^-[A-Za-z]+$/u.test(word)) { forced ||= word.includes('f'); deleting ||= word.includes('d'); dry ||= word.includes('n'); } else if (!word.startsWith('-')) positional.push(word); } const current = () => spawnSync('git', ['-C', dir, 'branch', '--show-current'], { encoding: 'utf8' }).stdout.trim(); const refspecs = positional.slice(1); const targets = []; for (const spec of refspecs) { const plain = spec.replace(/^\+/u, ''); if (spec.startsWith('+')) forced = true; if (plain === ':') { targets.push('*'); continue; } if (plain.startsWith(':')) deleting = true; const dst = plain.includes(':') ? plain.slice(plain.lastIndexOf(':') + 1) : plain; targets.push(dst === 'HEAD' || dst === '@' ? current() : dst.replace(/^refs\/heads\//u, '')); } const rewriting = forced || deleting; if (every) return { targets: ['*'], rewriting, dry }; if (refspecs.length > 0) return { targets, rewriting, dry }; return { targets: tags ? [] : [current()], rewriting, dry }; } // Whether a command is `gh pr create` into the branch or with no base, which defaults to the repository's default branch. function opensPr(words, branch) { if (words[0]?.split('/').at(-1) !== 'gh' || words[1] !== 'pr' || !['create', 'new'].includes(words[2])) return false; if (asksHelp(words.slice(3))) return false; let base = null; for (let at = 3; at < words.length; at += 1) { const word = words[at]; if (word === '--base' || word === '-B') base = words[++at] ?? ''; else if (word.startsWith('--base=')) base = word.slice('--base='.length); else if (/^-B./u.test(word)) base = word.slice(2); } return base === null || base.replace(/^refs\/heads\//u, '') === branch; } // gh pr create's flags that take no value; any other option consumes the next word, so `--title --help` sets a title. const PR_SWITCHES = new Set(['--draft', '--editor', '--fill', '--fill-first', '--fill-verbose', '--web', '--dry-run', '--no-maintainer-edit']); const SHORT_SWITCHES = /^[dewf]+/u; function asksHelp(args) { for (let at = 0; at < args.length; at += 1) { const word = args[at]; if (word === '--') return false; if (word === '--help' || word === '--help=true') return true; if (word.startsWith('--')) { if (!word.includes('=') && !PR_SWITCHES.has(word)) at += 1; } else if (word.startsWith('-')) { // A short cluster such as `-dt` ends with a flag that takes the next word, while `-tx` holds its value. const rest = word.slice(1).replace(SHORT_SWITCHES, ''); if (rest.startsWith('h')) return true; if (rest.length === 1) at += 1; } } return false; } const RUN_APPROVAL = /actions\/runs\/.*?\/(?:approve|pending_deployments)\b/u; const MOVES = new Set(['checkout', 'switch', 'reset', 'merge', 'rebase']); // Why a command would delete or overwrite files that the config's companion // repository tracks in a checkout holding its git directory, or null. function companionDenial(words, cwd, companion) { const call = gitCommand(words, cwd); if (!call || !companion?.dir) return null; const { sub, args, dir, gitDir } = call; if (sub !== 'clean' && !MOVES.has(sub)) return null; const top = git(dir, 'rev-parse', '--show-toplevel'); if (top === null || !existsSync(join(top, companion.dir))) return null; const flags = args.filter((word) => /^-[A-Za-z]+$/u.test(word)).join(''); if (sub === 'clean' && !flags.includes('n') && !args.includes('--dry-run')) { if (gitDir !== null && existsSync(resolve(dir, gitDir)) && sameDir(resolve(dir, gitDir), join(top, companion.dir))) return `git clean through ${companion.dir} deletes every public file, which that repository does not track. Clean through this checkout's own git instead.`; if (/[xX]/u.test(flags)) return `git clean -x or -X in ${top} deletes the files ${companion.dir} tracks, which that checkout's git ignores. Run it without -x or -X, or with -n to list what it would delete.`; } if (!MOVES.has(sub) || gitDir !== null) return null; const paths = args.indexOf('--'); if (paths !== -1 && paths < args.length - 1 && ['checkout', 'reset'].includes(sub)) return null; for (const rev of (paths === -1 ? args : args.slice(0, paths)).filter((word) => !word.startsWith('-'))) { if (git(dir, 'rev-parse', '--verify', '--quiet', `${rev}^{commit}`) === null) continue; if (git(dir, 'cat-file', '-e', `${rev}:${companion.list}`) !== null) continue; return `${rev} has no ${companion.list}, so moving ${top} there overwrites the files ${companion.dir} tracks with their old copies. Read an old file with \`git show ${rev}:\`, or look around in a detached worktree from \`git worktree add --detach ${rev}\`.`; } return null; } const globMatches = (pattern, name) => new RegExp(`^${pattern.split('*').map((part) => part.replace(/[.+?^${}()|[\]\\]/gu, '\\$&')).join('.*')}$`, 'u').test(name); // Claude Code kills a hook at its settings entry's timeout, 10 seconds in Plate, // and a killed hook lets the edit through. So the git calls share one budget // that ends 8 seconds after the process starts, instead of a short limit per // call, which refused valid edits on a loaded host. const GIT_DEADLINE = performance.timeOrigin + 8000; const git = (dir, ...args) => { const timeout = Math.floor(GIT_DEADLINE - Date.now()); if (timeout <= 0) return null; const run = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8', maxBuffer: 1 << 28, timeout, killSignal: 'SIGKILL' }); return run.error || run.status !== 0 ? null : run.stdout.replace(/\n$/u, ''); }; const sameDir = (a, b) => { const [x, y] = [statSync(a), statSync(b)]; return x.dev === y.dev && x.ino === y.ino; }; function resolvePhysically(path) { let parts = path.split(sep).filter(Boolean); let current = sep; for (let index = 0, hops = 0; index < parts.length; index += 1) { if (parts[index] === '.') continue; if (parts[index] === '..') { current = dirname(current); continue; } const next = join(current, parts[index]); let link; try { link = lstatSync(next).isSymbolicLink(); } catch { current = next; continue; } if (!link) { current = realpathSync.native(next); continue; } if ((hops += 1) > 40) throw new Error(`too many symlinks at ${next}`); const target = readlinkSync(next); parts = [...target.split(sep).filter(Boolean), ...parts.slice(index + 1)]; if (isAbsolute(target)) current = sep; index = -1; } return current; } function mainCheckoutPath(file, main) { let root = file; while (!existsSync(root) || !sameDir(root, main)) { if (dirname(root) === root) return null; root = dirname(root); } const path = relative(root, file); if (path.split(sep)[0] === '.git') return path; let dir = file; while (!existsSync(dir) || !statSync(dir).isDirectory()) dir = dirname(dir); const top = git(dir, 'rev-parse', '--show-toplevel'); if (top === null) throw new Error(`git could not read ${dir}`); return sameDir(top, main) ? path : null; } const deny = (reason) => { process.stdout.write( JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: `guard.mjs: ${reason}` }, }) ); process.exit(0); }; // Claude Code trims the path, expands ~ and resolves it against cwd before the // hook sees it and before it writes, so the cleaned spelling is the one that // lands. A host that wrote the raw spelling would follow links before any .., // so a raw path holding . or .. is walked too, and either walk can deny. function editDenial(config, file, cwd) { if (typeof config.branch !== 'string' || config.branch === '') throw new Error('.agents/pstack.json names no branch'); const common = git(dirname(fileURLToPath(import.meta.url)), 'rev-parse', '--path-format=absolute', '--git-common-dir'); if (common === null) return 'git could not read this repository, so the guard cannot tell whether this edit lands in the main checkout. Fix git, then retry.'; const main = dirname(common); const raw = file.trim().replace(/^~(?=\/|$)/u, homedir()); const spellings = new Set([resolve(cwd, raw), isAbsolute(raw) ? raw : `${cwd}${sep}${raw}`]); const hits = [...spellings].map((spelling) => mainCheckoutPath(resolvePhysically(spelling), main)).filter((path) => path !== null); if (hits.length === 0) return null; const branch = git(main, 'branch', '--show-current'); if (branch === null) return "git could not read the main checkout's branch, so the guard refuses this edit there. Fix git, then retry."; if (branch !== '' && ![config.branch, config.protected].includes(branch)) return null; const artifacts = config.plans && join(config.plans, 'artifacts') + sep; const path = hits.find((hit) => !(artifacts && hit.startsWith(artifacts))); if (path === undefined) return null; const here = git(cwd, 'rev-parse', '--show-toplevel'); const worktree = path.split(sep)[0] !== '.git' && here !== null && !sameDir(here, main) && sameDir(git(here, 'rev-parse', '--path-format=absolute', '--git-common-dir') ?? here, common) ? here : null; return `agents never edit the main checkout on ${branch || 'a detached HEAD'}, here ${path}. ${worktree ? `Edit ${join(worktree, path)} in your worktree instead` : 'Move to your own worktree, such as with EnterWorktree, edit there'}, and land it with land.mjs.${artifacts ? ` Only ${artifacts}, which holds the suggested-task ledger, is writable in the main checkout.` : ''}`; } function budgetDenial({ liftsStep, overBudget, stepLines, stepRecords }, budget, config, file, cwd) { const path = resolvePhysically(resolve(cwd, file.trim().replace(/^~(?=\/|$)/u, homedir()))); let dir = dirname(path); while (!existsSync(dir)) dir = dirname(dir); const top = git(dir, 'rev-parse', '--show-toplevel'); const common = top && git(top, 'rev-parse', '--path-format=absolute', '--git-common-dir'); const ours = git(dirname(fileURLToPath(import.meta.url)), 'rev-parse', '--path-format=absolute', '--git-common-dir'); if (!common || !ours || !sameDir(common, ours)) return null; const name = relative(top, path).split(sep).join('/'); if (budget.excluded(name) || git(top, 'check-ignore', '-q', '--', name) !== null) return null; const step = stepLines(top, config, git); if (!step || step.product <= budget.lines) return null; const records = stepRecords(top, config, git, step.files); if (!records?.planned || records.logs.some((log) => liftsStep(readFileSync(log, 'utf8')))) return null; const companion = config.companion?.dir && existsSync(join(top, config.companion.dir)); return `this worktree's change since ${step.base} ${overBudget(step.product, budget.lines)}. So the guard refuses this edit to ${name} now, while the step is built, instead of at its panel. To split, save the whole diff in the run directory${companion ? `, the ${config.companion.dir} half's too` : ''}, restore in this worktree every file the first lettered step does not need, with \`git restore --source ${step.sha} -- \` for a tracked file, land that step, then apply the rest in a new worktree for the next one. Tests, specs, fixtures, Markdown, plans, excluded globs and files git ignores stay editable. A "big step:" row counts in a decision log this worktree changes, until that log's next "landed as" row.`; } const failOpen = (check) => { try { return check(); } catch { return null; } }; const input = JSON.parse(readFileSync(0, 'utf8')); if (!existsSync(CONFIG)) process.exit(0); if (EDIT_TOOLS.has(input.tool_name)) { const file = input.tool_input?.file_path ?? input.tool_input?.notebook_path; if (typeof file !== 'string') process.exit(0); let reason; try { const config = JSON.parse(readFileSync(CONFIG, 'utf8')); const cwd = input.cwd ?? process.cwd(); reason = editDenial(config, file, cwd); if (!reason) { const status = await import('./status.mjs'); const budget = status.stepBudget(config); reason = failOpen(() => budgetDenial(status, budget, config, file, cwd)); } } catch (error) { reason = `the guard failed (${error.message}), so it refuses this edit. Fix the path, git or .agents/pstack.json, then retry.`; } if (reason) deny(reason); process.exit(0); } const config = JSON.parse(readFileSync(CONFIG, 'utf8')); if (BASE_SYNC.test(input.tool_name ?? '')) { deny( `the app's base-branch sync refuses origin/${config.branch} whenever it changes .claude files. Commit your work, then run \`git fetch origin ${config.branch} && git rebase origin/${config.branch}\` in this worktree; land.mjs also rebases before it pushes.` ); } const command = input.tool_input?.command; if (typeof command !== 'string') process.exit(0); const kept = new Set([config.branch, config.protected].filter(Boolean)); const hits = new Set(); let direct = false; let pr = false; let lost = null; eachCommand(command, (words, prefix, dir) => { lost ??= companionDenial(words, dir, config.companion); const push = pushes(words, dir); for (const target of push?.targets ?? []) { for (const name of target.includes('*') ? [...kept].filter((branch) => globMatches(target, branch)) : [target]) { if (push.rewriting) { if (kept.has(name)) hits.add(name); } else if (name === config.branch && !push.dry && !prefix.includes('PSTACK_RELEASE=1')) direct = true; } } pr ||= opensPr(words, config.branch); }, new Set([input.cwd ?? process.cwd()])); const reasons = []; if (hits.size > 0) reasons.push(`agents never force-push or delete ${[...hits].join(' and ')}. Tell the owner, who can run it in their own terminal if they want it:\n ${command}`); if (direct) { reasons.push( `agents push ${config.branch} only through \`node .agents/pstack/land.mjs\` from their worktree, which squashes the task, runs its checks and adds the Session: line review.mjs reads. Tell the owner, who can run it in their own terminal if they want it:\n ${command}` ); } if (lost) reasons.push(lost); if (pr) { reasons.push( `agents open a PR into ${config.branch} only through \`node .agents/pstack/land.mjs\`, which renders the plan page as its body. A PR stacked on another branch names that branch with --base.` ); } if (RUN_APPROVAL.test(command.replace(/['"\\]/gu, ''))) { reasons.push( `agents never approve a workflow run, such as a contributor's fork run waiting for approval, because that needs the user's word. Tell the user which runs wait, so they click "Approve and run workflows" on the PR or run the command in their own terminal. A line that only mentions such a path, such as a commit message, writes it without \`actions/runs/\`:\n ${command}` ); } if ((lost || direct || hits.size > 0) && unresolved.size > 0) { reasons.push( `The guard could not resolve ${[...unresolved].map((part) => `\`${part}\``).join(', ')}, so it judged what follows in the directory before that step. If it runs elsewhere, repeat it with an absolute path.` ); } if (reasons.length > 0) deny(reasons.join('\n'));