@tekmidian/pai 0.61.0 → 0.62.0

package/docs/commands/worker.md

@@ -20,6 +20,7 @@ pai worker <subcommand> [options]
 |---------|-------------|
 | [`pai worker run [args...]`](#pai-worker-run-args) | Run one claude-code worker through the configured provider. |
 | [`pai worker ps`](#pai-worker-ps) | List workers of this session (RUNNING + FINISHED); --all for every worker |
+| [`pai worker pending`](#pai-worker-pending) | Finished workers whose branch or worktree holds work not yet merged into this repo |
 | [`pai worker follow [id]`](#pai-worker-follow-id) | Live transcript of one worker, or of this session's running workers |
 | [`pai worker replay <id>`](#pai-worker-replay-id) | Print the transcript of one finished or running worker |
 | [`pai worker watch`](#pai-worker-watch) | ps refreshed every 2 seconds (plain `watch`, colors kept) |
@@ -31,6 +32,7 @@ pai worker <subcommand> [options]
 | [`pai worker merge <id>`](#pai-worker-merge-id) | Merge a worker's worktree branch (worker/<id>) into the original checkout, then remove the worktree and delete the branch |
 | [`pai worker wait <ids...>`](#pai-worker-wait-ids) | Poll workers until they finish; prints each result as one JSON line, exit 1 on failure or timeout |
 | [`pai worker discard <id>`](#pai-worker-discard-id) | Drop a worker's worktree and branch, keeping nothing |
+| [`pai worker gc`](#pai-worker-gc) | Archive leftover worker worktrees (state kept under refs/pai-archive/<id>; gitignored files are not kept) |
 | [`pai worker kill <id>`](#pai-worker-kill-id) | Send SIGTERM to a running worker process |
 | [`pai worker controls <id> <who>`](#pai-worker-controls-id-who) | Hand the desktop controls (clickr) to a worker or take them back. |
 | [`pai worker resume <id> <text>`](#pai-worker-resume-id-text) | Continue a finished worker on the same provider: claude --resume <session> |
@@ -107,6 +109,19 @@ List workers of this session (RUNNING + FINISHED); --all for every worker
 | `--all` | Show workers of all sessions, not just this terminal's |  |
 
 
+### pai worker pending
+
+Finished workers whose branch or worktree holds work not yet merged into this repo
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--all` | Every repo in the log dir, not just the current one |  |
+| `--json` | Machine-readable output |  |
+| `--gate` | Release gate: exit 1 with the list unless PAI_ALLOW_PENDING=1 |  |
+
+
 ### pai worker follow [id]
 
 Live transcript of one worker, or of this session's running workers
@@ -259,6 +274,18 @@ Drop a worker's worktree and branch, keeping nothing
 | `<id>` | required |
 
 
+### pai worker gc
+
+Archive leftover worker worktrees (state kept under refs/pai-archive/<id>; gitignored files are not kept)
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--older-than <hours>` | minimum age of a finished worker | `24` |
+| `--dry-run` | print what would be archived, change nothing |  |
+
+
 ### pai worker kill <id>
 
 Send SIGTERM to a running worker process

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",
@@ -61,7 +61,7 @@
     "dev": "tsdown --watch",
     "test": "vitest",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "bun run build"
+    "prepublishOnly": "bun run build && node dist/cli/index.mjs worker pending --gate"
   },
   "author": "Matthias Nott",
   "license": "MIT",

package/scripts/build-hooks.mjs

@@ -31,7 +31,7 @@ import {
 } from "fs";
 import { join, resolve, basename } from "path";
 import { homedir, platform } from "os";
-import { isInsideWorkerWorktree } from "./lib/sync-guard.mjs";
+import { syncSkipReason } from "./lib/sync-guard.mjs";
 
 const HOOKS_SRC = "src/hooks/ts";
 const HOOKS_OUT = "dist/hooks";
@@ -164,10 +164,11 @@ console.log(
 // --sync: Symlink (or copy on Windows) all deployable files to ~/.claude/
 // ---------------------------------------------------------------------------
 
-if (doSync && isInsideWorkerWorktree(process.cwd())) {
-  // Never repoint the live ~/.claude symlinks at a worktree that `pai worker
-  // merge` will delete — see scripts/lib/sync-guard.mjs.
-  console.log("✔ Hook symlinks skipped: build runs inside a worker worktree");
+const skipReason = doSync ? syncSkipReason() : null;
+if (skipReason) {
+  // Only the canonical install repoints the live ~/.claude symlinks — see
+  // scripts/lib/sync-guard.mjs.
+  console.log(skipReason.startsWith("skipping") ? skipReason : `✔ Hook symlinks skipped: ${skipReason}`);
 } else if (doSync) {
   const useSymlinks = platform() !== "win32";
   const claudeDir = join(homedir(), ".claude");

package/scripts/build-skill-stubs.mjs

@@ -32,7 +32,7 @@ import {
 } from "fs";
 import { join, resolve } from "path";
 import { homedir, platform } from "os";
-import { isInsideWorkerWorktree } from "./lib/sync-guard.mjs";
+import { syncSkipReason } from "./lib/sync-guard.mjs";
 
 const PROMPTS_DIR = "src/daemon-mcp/prompts";
 const CUSTOM_DIR = join(PROMPTS_DIR, "custom");
@@ -206,10 +206,11 @@ for (const [fileName, dir] of [
 const customLabel = customNames.length > 0 ? ` (${builtinNames.length} built-in + ${customNames.length} custom)` : "";
 console.log(`✔ ${generated} skill stubs generated in ${STUBS_OUT}/${customLabel}`);
 
-if (doSync && isInsideWorkerWorktree(process.cwd())) {
-  // Never repoint the live ~/.claude/skills symlinks at a worktree that
-  // `pai worker merge` will delete — see scripts/lib/sync-guard.mjs.
-  console.log("✔ Skill symlinks skipped: build runs inside a worker worktree");
+const skipReason = doSync ? syncSkipReason() : null;
+if (skipReason) {
+  // Only the canonical install repoints the live ~/.claude/skills symlinks —
+  // see scripts/lib/sync-guard.mjs.
+  console.log(skipReason.startsWith("skipping") ? skipReason : `✔ Skill symlinks skipped: ${skipReason}`);
 } else if (doSync) {
   syncSymlinks(generatedDirNames);
 }

package/src/hooks/ts/lib/worker-guard.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { decideWorkerGuard, parseCommand, type WorkerGuardContext } from "./worker-guard.js";
+
+const WT = "/work/wt/abc";
+const MAIN = "/work/main";
+const HOME = "/home/u";
+
+const wtCtx = (over: Partial<WorkerGuardContext> = {}): WorkerGuardContext => ({
+  cwd: WT,
+  home: HOME,
+  worktreeRoot: WT,
+  inWorktree: true,
+  mainCheckout: MAIN,
+  testScript: () => "vitest",
+  ...over,
+});
+const sharedCtx = wtCtx({ cwd: MAIN, worktreeRoot: MAIN, inWorktree: false, mainCheckout: null });
+
+const WORKER = { PAI_WORKER: "1" };
+const bash = (command: string) => ({ tool_name: "Bash", tool_input: { command } });
+const edit = (tool_name: string, file_path: string) => ({ tool_name, tool_input: { file_path } });
+
+const DENY: [string, ReturnType<typeof bash>, WorkerGuardContext, string][] = [
+  ["ln -s into main node_modules", bash(`ln -s ${MAIN}/node_modules node_modules`), wtCtx(), "runner provisions node_modules"],
+  ["ln -sf relative escape", bash("ln -sf ../../../main/node_modules node_modules"), wtCtx(), "runner provisions node_modules"],
+  ["ln -s after cd &&", bash("cd /tmp && ln -s /elsewhere/x y"), wtCtx(), "runner provisions node_modules"],
+  ["cp -R worktree to /tmp", bash(`cp -R ${WT} /tmp/build`), wtCtx(), "never from a copy"],
+  ["cp -r . to /tmp", bash("cp -r . /tmp/build"), wtCtx(), "never from a copy"],
+  ["rsync -a . elsewhere", bash("rsync -a ./ /tmp/build/"), wtCtx(), "never from a copy"],
+  ["rsync main checkout", bash(`rsync -av ${MAIN}/ /tmp/b`), wtCtx(), "never from a copy"],
+  ["git push", bash("git push origin HEAD"), wtCtx(), "git push blocked"],
+  ["push after &&", bash("git commit -m x && git push"), wtCtx(), "git push blocked"],
+  ["env-prefixed push", bash("GIT_SSH=x git -C . push"), wtCtx(), "git push blocked"],
+  ["npm publish", bash("npm publish --access public"), wtCtx(), "publish blocked"],
+  ["bun publish", bash("bun publish"), wtCtx(), "publish blocked"],
+  ["npm version bump", bash("npm version patch"), wtCtx(), "npm version blocked"],
+  ["git tag create", bash("git tag v1.0.0"), wtCtx(), "git tag blocked"],
+  ["git stash in shared checkout", bash("git stash"), sharedCtx, "shared checkout"],
+  ["git reset --hard in shared checkout", bash("git reset --hard HEAD"), sharedCtx, "shared checkout"],
+  ["git checkout -- . in shared checkout", bash("git checkout -- ."), sharedCtx, "shared checkout"],
+  ["git restore . in shared checkout", bash("git restore ."), sharedCtx, "shared checkout"],
+  ["git clean -fd in shared checkout", bash("git clean -fd"), sharedCtx, "shared checkout"],
+  ["git switch in shared checkout", bash("git switch other"), sharedCtx, "shared checkout"],
+  ["git checkout branch in shared checkout", bash("git checkout other"), sharedCtx, "shared checkout"],
+  ["TODO.md via redirect", bash("echo x >> Notes/TODO.md"), wtCtx(), "Notes/TODO.md"],
+  ["TODO.md via tee", bash("echo x | tee Notes/TODO.md"), wtCtx(), "Notes/TODO.md"],
+  ["TODO.md via sed -i", bash("sed -i '' s/a/b/ Notes/TODO.md"), wtCtx(), "Notes/TODO.md"],
+  ["bun test on vitest repo", bash("cd sub && bun test"), wtCtx(), "vitest"],
+  ["bash -c wrapper", bash(`bash -c 'git push'`), wtCtx(), "git push blocked"],
+  ["cd into main checkout", bash(`cd ${MAIN}/src`), wtCtx(), "relative to your worktree"],
+  ["cd main then work", bash(`cd ${MAIN} && ls`), wtCtx(), "relative to your worktree"],
+  ["redirect to claude.json", bash(`echo {} > ${HOME}/.claude.json`), wtCtx(), "temp-dir copies"],
+  ["tilde settings.json sed -i", bash("sed -i s/a/b/ ~/.claude/settings.json"), wtCtx(), "temp-dir copies"],
+  ["cp onto pai yaml", bash("cp /tmp/x.yaml ~/.claude/pai/config.yaml"), wtCtx(), "temp-dir copies"],
+  ["mv pai json", bash("mv /tmp/x ~/.claude/pai/config.json"), wtCtx(), "temp-dir copies"],
+];
+
+const ALLOW: [string, ReturnType<typeof bash>, WorkerGuardContext][] = [
+  ["ln -s inside worktree", bash("ln -s ../node_modules/x lib/x"), wtCtx()],
+  ["ln -s absolute inside worktree", bash(`ln -s ${WT}/a b`), wtCtx()],
+  ["cp -R within worktree", bash("cp -R src /work/wt/abc/tmp/src2"), wtCtx()],
+  ["cp -r subdir to /tmp", bash("cp -r src /tmp/src"), wtCtx()],
+  ["git status/diff/log", bash("git status && git diff --stat | head && git log -3"), wtCtx()],
+  ["git add + commit", bash(`git add -A && git commit -m "fix: mention git push and git stash"`), wtCtx()],
+  ["git reset in worktree", bash("git reset --hard HEAD~1"), wtCtx()],
+  ["git stash list in shared checkout", bash("git stash list"), sharedCtx],
+  ["git tag listing", bash("git tag -l 'v*'"), wtCtx()],
+  ["npm version (read)", bash("npm version"), wtCtx()],
+  ["npm run build", bash("npm run build"), wtCtx()],
+  ["bun test on non-vitest repo", bash("bun test"), wtCtx({ testScript: () => "bun test" })],
+  ["cd inside worktree", bash("cd src && ls"), wtCtx()],
+  ["cat TODO.md", bash("cat Notes/TODO.md"), wtCtx()],
+  ["read live config", bash("cat ~/.claude/settings.json ~/.claude.json | head"), wtCtx()],
+  ["write other Notes file", bash("echo x > Notes/other.md"), wtCtx()],
+  ["write deep pai file", bash("echo x > ~/.claude/pai/logs/x.json"), wtCtx()],
+  ["stderr dup redirect", bash("npm test 2>&1 | tail"), wtCtx()],
+  ["git checkout -b in worktree", bash("git checkout -b topic"), wtCtx()],
+];
+
+describe("decideWorkerGuard", () => {
+  it.each(DENY)("denies: %s", (_n, input, ctx, needle) => {
+    const d = decideWorkerGuard(input, WORKER, () => ctx);
+    expect(d.decision).toBe("deny");
+    expect((d as { reason: string }).reason).toContain(needle);
+  });
+
+  it.each(ALLOW)("allows: %s", (_n, input, ctx) => {
+    expect(decideWorkerGuard(input, WORKER, () => ctx).decision).toBe("allow");
+  });
+
+  it("is a no-op when PAI_WORKER is unset", () => {
+    for (const [, input, ctx] of DENY) {
+      expect(decideWorkerGuard(input, {}, () => ctx).decision).toBe("allow");
+    }
+  });
+
+  it.each([
+    ["Write", `${WT}/Notes/TODO.md`, "deny"],
+    ["Edit", "Notes/TODO.md", "deny"],
+    ["MultiEdit", `${MAIN}/Notes/TODO.md`, "deny"],
+    ["Write", `${HOME}/.claude/settings.json`, "deny"],
+    ["Edit", `${HOME}/.claude.json`, "deny"],
+    ["Write", `${HOME}/.claude/pai/config.yaml`, "deny"],
+    ["Write", `${WT}/Notes/other.md`, "allow"],
+    ["Edit", `${WT}/src/a.ts`, "allow"],
+    ["Write", `${HOME}/.claude/pai/logs/x.yaml`, "allow"],
+  ])("%s %s -> %s", (tool, path, want) => {
+    expect(decideWorkerGuard(edit(tool, path), WORKER, () => wtCtx()).decision).toBe(want);
+    expect(decideWorkerGuard(edit(tool, path), {}, () => wtCtx()).decision).toBe("allow");
+  });
+
+  it("ignores other tools", () => {
+    expect(decideWorkerGuard({ tool_name: "Read", tool_input: { file_path: "Notes/TODO.md" } }, WORKER, () => wtCtx()).decision).toBe("allow");
+  });
+});
+
+describe("commit attribution", () => {
+  const TRAILER = "Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>";
+  const run = (c: string) => decideWorkerGuard(bash(c), WORKER, () => wtCtx());
+  const dir = mkdtempSync(join(tmpdir(), "wg-"));
+  const bad = join(dir, "bad.txt");
+  const good = join(dir, "good.txt");
+  writeFileSync(bad, `feat: x\n\n${TRAILER}\n`);
+  writeFileSync(good, "feat: x\n");
+
+  it.each([
+    ["-m trailer", `git commit -m "feat: x" -m "${TRAILER}"`],
+    ["heredoc trailer", `git commit -m "$(cat <<'EOF'\nfeat: x\n\n${TRAILER}\nEOF\n)"`],
+    ["generated-with", `git commit -m "feat: x 🤖 Generated with [Claude Code](https://claude.com/claude-code)"`],
+    ["-F file trailer", `git commit -F ${bad}`],
+    ["--file= trailer", `git commit --file=${bad}`],
+  ])("denies %s", (_n, c) => {
+    const d = run(c);
+    expect(d.decision).toBe("deny");
+    expect((d as { reason: string }).reason).toContain("no AI attribution in commits");
+  });
+
+  it.each([
+    ["plain commit", 'git commit -m "feat: add thing"'],
+    ["prose mentioning claude", 'git commit -m "fix: handle claude output parsing"'],
+    ["-F clean file", `git commit -F ${good}`],
+    ["-F missing file", `git commit -F ${dir}/nope.txt`],
+  ])("allows %s", (_n, c) => {
+    expect(run(c).decision).toBe("allow");
+  });
+});
+
+describe("parseCommand", () => {
+  it("splits operators outside quotes and captures redirects", () => {
+    expect(parseCommand(`a 'b && c'; d > f 2>&1 || e | g`)).toEqual([
+      { words: ["a", "b && c"], redirects: [] },
+      { words: ["d"], redirects: ["f"] },
+      { words: ["e"], redirects: [] },
+      { words: ["g"], redirects: [] },
+    ]);
+  });
+});
+
+describe("worker-guard entry", () => {
+  const ENTRYPOINT = "src/hooks/ts/pre-tool-use/worker-guard.ts";
+  const run = (env: NodeJS.ProcessEnv, command: string): string => {
+    const { PAI_WORKER: _drop, ...base } = process.env;
+    return execFileSync("bun", [ENTRYPOINT], {
+      input: JSON.stringify({ tool_name: "Bash", cwd: process.cwd(), tool_input: { command } }),
+      encoding: "utf8",
+      timeout: 15_000,
+      env: { ...base, ...env },
+    });
+  };
+
+  it("denies git push for a worker", () => {
+    const out = JSON.parse(run({ PAI_WORKER: "1" }, "git push")).hookSpecificOutput;
+    expect(out.permissionDecision).toBe("deny");
+    expect(out.permissionDecisionReason).toContain("git push blocked");
+  });
+
+  it("prints nothing in an interactive session", () => {
+    expect(run({}, "git push")).toBe("");
+  });
+
+  it("prints nothing for an allowed worker command", () => {
+    expect(run({ PAI_WORKER: "1" }, "git status")).toBe("");
+  });
+});

package/src/hooks/ts/lib/worker-guard.ts

@@ -0,0 +1,315 @@
+/**
+ * worker-guard.ts — the decision behind the worker-only PreToolUse guard.
+ *
+ * Pure but for reading a `git commit -F <file>` message: no stdin, no git — the hook entry (pre-tool-use/worker-guard.ts)
+ * gathers the context, this module decides, same split as sleep-poll-gate.ts.
+ * Spec prose ("never symlink node_modules", "do not push", ...) was broken by
+ * workers anyway; this is the enforcement. Active only for PAI_WORKER=1.
+ *
+ * Parsing is conservative on purpose: a command is split on ; && || | & and
+ * newlines outside quotes, `bash -c '<cmd>'` is unwrapped, `cd` is tracked
+ * across segments. Not caught (false negatives chosen over blocking real
+ * work): $(...) / backtick substitutions, subshell/brace grouping, variables
+ * other than ~ and $HOME in paths, scripts that do the forbidden thing
+ * internally, `git -C <other>` targeting another repo's cwd, cp/rsync with
+ * -t or a source that is a subdirectory of the tree.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { type GateDecision } from "./sleep-poll-gate.js";
+import { decideWorkerGitGuard } from "./worker-git-guard.js";
+
+export interface WorkerGuardInput {
+  tool_name?: string;
+  cwd?: string;
+  tool_input?: { command?: string; file_path?: string; path?: string };
+}
+
+export interface WorkerGuardContext {
+  /** Hook cwd. */
+  cwd: string;
+  home: string;
+  /** Top level of the git tree containing cwd, null outside git. */
+  worktreeRoot: string | null;
+  /** True when cwd is a linked worktree (git-dir differs from common dir). */
+  inWorktree: boolean;
+  /** The main checkout the worktree hangs off; null when not in a worktree. */
+  mainCheckout: string | null;
+  /** package.json `scripts.test` of the tree, null when unknown. */
+  testScript: () => string | null;
+}
+
+interface Segment {
+  words: string[];
+  /** Redirection targets (`> f`, `>> f`, `2>f`). */
+  redirects: string[];
+}
+
+const deny = (reason: string): GateDecision => ({ decision: "deny", reason });
+const ALLOW: GateDecision = { decision: "allow" };
+
+/** Split into segments; quotes group words, operators outside quotes split. */
+export function parseCommand(command: string): Segment[] {
+  const segs: Segment[] = [];
+  let seg: Segment = { words: [], redirects: [] };
+  let tok = "";
+  let has = false; // a token is in progress (covers empty quoted "")
+  let quote: string | null = null;
+  let target: "redir" | "skip" | null = null;
+
+  const flushTok = (): void => {
+    if (!has) return;
+    if (target === "redir") seg.redirects.push(tok);
+    else if (target !== "skip") seg.words.push(tok);
+    target = null;
+    tok = "";
+    has = false;
+  };
+  const endSeg = (): void => {
+    flushTok();
+    if (seg.words.length || seg.redirects.length) segs.push(seg);
+    seg = { words: [], redirects: [] };
+  };
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      else if (ch === "\\" && quote === '"' && i + 1 < command.length) tok += command[++i];
+      else tok += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      has = true;
+    } else if (ch === "\\" && i + 1 < command.length) {
+      tok += command[++i];
+      has = true;
+    } else if (/\s/.test(ch) && ch !== "\n") {
+      flushTok();
+    } else if (ch === ";" || ch === "\n" || ch === "|" || ch === "&") {
+      if (ch === "&" && command[i + 1] === ">") continue; // `&>` redirects
+      endSeg();
+      if ((ch === "|" || ch === "&") && command[i + 1] === ch) i++;
+    } else if (ch === ">" || ch === "<") {
+      if (has && /^\d+$/.test(tok)) {
+        tok = "";
+        has = false;
+      } else flushTok();
+      if (ch === ">" && command[i + 1] === ">") i++;
+      if (command[i + 1] === "&") {
+        i++;
+        target = "skip"; // fd duplication: `2>&1`
+      } else target = ch === ">" ? "redir" : "skip";
+    } else {
+      tok += ch;
+      has = true;
+    }
+  }
+  endSeg();
+  return segs;
+}
+
+const WRAPPERS = new Set(["sudo", "command", "env", "time", "nohup", "exec", "builtin"]);
+
+/** Drop env assignments and wrapper commands from the front. */
+function stripPrefix(words: string[]): string[] {
+  let i = 0;
+  while (i < words.length && (/^[A-Za-z_]\w*=/.test(words[i]) || WRAPPERS.has(words[i]))) i++;
+  return words.slice(i);
+}
+
+const isFlag = (w: string): boolean => w.startsWith("-") && w.length > 1;
+
+function expand(p: string, home: string): string {
+  return p.replace(/^~(?=\/|$)/, home).replace(/^\$\{?HOME\}?(?=\/|$)/, home);
+}
+
+const hasUnresolvedVar = (p: string): boolean => /[$`]/.test(p);
+
+const isInside = (p: string, root: string): boolean => p === root || p.startsWith(root.replace(/\/$/, "") + "/");
+
+/** Absolute, or null when the path holds variables we cannot resolve. */
+function abs(p: string, cwd: string, home: string): string | null {
+  const e = expand(p, home);
+  return hasUnresolvedVar(e) ? null : resolve(cwd, e);
+}
+
+/** Live PAI/Claude config that tests and workers must not write. */
+export function isLiveConfig(p: string, home: string): boolean {
+  if (p === `${home}/.claude.json` || p === `${home}/.claude/settings.json`) return true;
+  return dirname(p) === `${home}/.claude/pai` && /\.(ya?ml|json)$/.test(p);
+}
+
+const isTodo = (p: string): boolean => p === "Notes/TODO.md" || p.endsWith("/Notes/TODO.md");
+
+function protectedPathReason(p: string, home: string): string | null {
+  if (isTodo(p)) return "Notes/TODO.md is the orchestrator's: report what should change in your result instead";
+  if (isLiveConfig(p, home)) return "live PAI/Claude config must not be written: tests use temp-dir copies";
+  return null;
+}
+
+/** Paths a segment writes to (redirects plus the write-side of common tools). */
+function writeTargets(words: string[], redirects: string[]): string[] {
+  const [cmd, ...args] = words;
+  const pos = args.filter((a) => !isFlag(a));
+  const out = [...redirects];
+  if (cmd === "tee" || cmd === "mv") out.push(...pos);
+  else if (cmd === "cp" && pos.length) out.push(pos[pos.length - 1]);
+  else if (cmd === "sed" && args.some((a) => /^-[a-zA-Z]*i|^--in-place/.test(a))) out.push(...pos);
+  return out;
+}
+
+const RECURSIVE_CP = /^-[a-zA-Z]*[rRa]|^--recursive$|^--archive$/;
+const RECURSIVE_RSYNC = /^-[a-zA-Z]*[ra]|^--recursive$|^--archive$/;
+
+const AI_ATTRIBUTION = /Co-Authored-By:[^\n]*(claude|anthropic)|Generated with[^\n]*Claude Code/i;
+
+/** Message text a `git commit` carries: the raw command (-m, heredoc) plus any -F/--file body. */
+function commitMessageText(rest: string[], cwd: string, raw: string, home: string): string {
+  let text = raw;
+  for (let i = 0; i < rest.length; i++) {
+    const f = rest[i] === "-F" || rest[i] === "--file" ? rest[i + 1] : rest[i].startsWith("--file=") ? rest[i].slice(7) : undefined;
+    const p = f ? abs(f, cwd, home) : null;
+    if (!p) continue;
+    try {
+      text += "\n" + readFileSync(p, "utf8");
+    } catch {
+      // missing file: nothing to check
+    }
+  }
+  return text;
+}
+
+const GIT_TREE_CMDS = new Set(["reset", "clean", "restore", "switch", "rebase", "merge", "checkout", "stash"]);
+
+function gitSub(args: string[]): { sub: string; rest: string[] } | null {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "-C" || a === "-c" || a === "--git-dir" || a === "--work-tree") i++;
+    else if (!isFlag(a)) return { sub: a, rest: args.slice(i + 1) };
+  }
+  return null;
+}
+
+/** Decide one segment; `st.cwd` is the tracked working directory. */
+function decideSegment(seg: Segment, st: { cwd: string; raw: string }, ctx: WorkerGuardContext): GateDecision {
+  const words = stripPrefix(seg.words);
+  const [cmd, ...args] = words;
+  const boundary = ctx.worktreeRoot ?? ctx.cwd;
+
+  for (const t of writeTargets(words.length ? words : [""], seg.redirects)) {
+    const p = abs(t, st.cwd, ctx.home);
+    const why = p && protectedPathReason(p, ctx.home);
+    if (why) return deny(`write to ${t} blocked: ${why}`);
+  }
+  if (!cmd) return ALLOW;
+
+  if ((cmd === "bash" || cmd === "sh" || cmd === "zsh") && args[0] === "-c" && args[1]) {
+    return decideCommand(args[1], { ...ctx, cwd: st.cwd });
+  }
+
+  const pos = args.filter((a) => !isFlag(a));
+
+  if (cmd === "cd") {
+    const p = pos[0] ? abs(pos[0], st.cwd, ctx.home) : null;
+    if (!p) return ALLOW;
+    if (ctx.mainCheckout && ctx.worktreeRoot && isInside(p, ctx.mainCheckout) && !isInside(p, ctx.worktreeRoot)) {
+      return deny(`cd ${pos[0]} blocked: it leaves your worktree for the main checkout; use paths relative to your worktree`);
+    }
+    st.cwd = p;
+    return ALLOW;
+  }
+
+  if (cmd === "ln" && args.some((a) => /^-[a-zA-Z]*s|^--symbolic$/.test(a)) && pos.length) {
+    const link = pos[1] ? abs(pos[1], st.cwd, ctx.home) : null;
+    const from = link ? dirname(link) : st.cwd;
+    const target = abs(pos[0], from, ctx.home);
+    if (target && !isInside(target, boundary)) {
+      return deny("ln -s to a target outside your worktree blocked: the runner provisions node_modules in your worktree");
+    }
+    return ALLOW;
+  }
+
+  if ((cmd === "cp" && args.some((a) => RECURSIVE_CP.test(a))) || (cmd === "rsync" && args.some((a) => RECURSIVE_RSYNC.test(a)))) {
+    if (pos.length >= 2) {
+      const dest = abs(pos[pos.length - 1], st.cwd, ctx.home);
+      const roots = [boundary, ctx.mainCheckout].filter((r): r is string => !!r);
+      const copiesRoot = pos.slice(0, -1).some((s) => {
+        const p = abs(s, st.cwd, ctx.home);
+        return !!p && roots.includes(p);
+      });
+      if (copiesRoot && dest && !isInside(dest, boundary)) {
+        return deny(`${cmd} of the repo tree out of your worktree blocked: build and test inside your worktree, never from a copy`);
+      }
+    }
+    return ALLOW;
+  }
+
+  if ((cmd === "npm" || cmd === "bun" || cmd === "pnpm" || cmd === "yarn") && pos[0] === "publish") {
+    return deny(`${cmd} publish blocked: releases are the orchestrator's`);
+  }
+  if (cmd === "npm" && pos[0] === "version" && pos.length > 1) {
+    return deny("npm version blocked: version bumps are the orchestrator's");
+  }
+
+  if (cmd === "bun" && pos[0] === "test" && /vitest/.test(ctx.testScript() ?? "")) {
+    return deny("bun test blocked: this repo's tests are vitest; run `npx vitest run <files>`");
+  }
+
+  if (cmd === "git") {
+    const g = gitSub(args);
+    if (!g) return ALLOW;
+    if (g.sub === "push") return deny("git push blocked: pushing is the orchestrator's; commit on your branch and stop");
+    if (g.sub === "commit" && AI_ATTRIBUTION.test(commitMessageText(g.rest, st.cwd, st.raw, ctx.home))) {
+      return deny("no AI attribution in commits (operator rule): drop the Co-Authored-By / Generated-with line and commit again");
+    }
+    if (g.sub === "tag") {
+      const listing = !g.rest.some((a) => !isFlag(a)) || g.rest.some((a) => /^(-l|--list|-n\d*|--contains|--points-at)$/.test(a));
+      if (!listing) return deny("git tag blocked: releases are the orchestrator's");
+    }
+    if (!ctx.inWorktree) {
+      if (GIT_TREE_CMDS.has(g.sub)) {
+        const r = decideWorkerGitGuard(words.join(" "), true, st.cwd, null);
+        if (r.blocked) return deny(`${r.cmd} blocked: you run in a shared checkout, not a worktree; it can destroy other workers' edits, use --worktree`);
+      }
+      if (g.sub === "checkout" && g.rest.some((a) => !isFlag(a))) {
+        return deny("git checkout <branch> blocked: you run in a shared checkout, not a worktree; use --worktree");
+      }
+    }
+  }
+  return ALLOW;
+}
+
+function decideCommand(command: string, ctx: WorkerGuardContext): GateDecision {
+  const st = { cwd: ctx.cwd, raw: command };
+  for (const seg of parseCommand(command)) {
+    const d = decideSegment(seg, st, ctx);
+    if (d.decision === "deny") return d;
+  }
+  return ALLOW;
+}
+
+export function decideWorkerGuard(
+  input: WorkerGuardInput,
+  env: Record<string, string | undefined>,
+  ctx: () => WorkerGuardContext
+): GateDecision {
+  if (env.PAI_WORKER !== "1") return ALLOW;
+  const tool = input.tool_name;
+  const ti = input.tool_input ?? {};
+
+  if (tool === "Bash") {
+    return typeof ti.command === "string" ? decideCommand(ti.command, ctx()) : ALLOW;
+  }
+  if (tool === "Edit" || tool === "Write" || tool === "MultiEdit" || tool === "NotebookEdit") {
+    const f = ti.file_path ?? ti.path;
+    if (typeof f !== "string") return ALLOW;
+    const c = ctx();
+    const p = abs(f, c.cwd, c.home);
+    const why = p && protectedPathReason(p, c.home);
+    return why ? deny(`edit of ${f} blocked: ${why}`) : ALLOW;
+  }
+  return ALLOW;
+}