@brainervirus/workit-core 8.22.2 → 8.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.22.2",
+  "version": "8.23.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-fanout/SKILL.md

@@ -20,14 +20,14 @@ units of ~100+ lines each. Coupled work stays with one owner. Workit never spawn
    PR (`references/orchestration.md`).
 2. **Record standing orders** (`workit ledger standing add "<order>"`): every
    user directive all workers share. Directives decay across resumes.
-3. **Brief each worker verbatim** with `workit fanout brief <slice>`: plan
-   fields, standing orders, SCRATCH, session id, fan-in and heavy-lease rules.
+3. **Brief each worker verbatim**: `workit fanout worktree create <slice>`
+   (every host), then `workit fanout brief <slice>` (WORKTREE, SCRATCH, rules).
    Never hand-edit it; change the plan or the standing orders and render again.
 4. **Spawn in a rolling window**, in the background, each in its own worktree:
    keep 4-6 in flight and refill from `spawnable` in `workit fanout status` as
    each one finishes. Model: the brief's `model:` line, else TIER
-   (`references/orchestration.md`). Claude Code: the `implementer` agent;
-   elsewhere first `workit fanout worktree create <slice>`.
+   (`references/orchestration.md`). Claude Code: the `implementer` agent, never
+   with `isolation: "worktree"`; Workit's hooks confine it to its WORKTREE.
 5. **Judge liveness by side effects only:** `workit fanout status` (head age,
    PR, CI, verdict, landed; STUCK past the TIMEBOX). Stop a stuck worker and
    observe that it exited (a timeout is not proof). Removing a worktree drops

package/skills/workit-fanout/references/brief.md

@@ -25,6 +25,7 @@ REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
   each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),
   anything out of scope as a follow-up, not a diff.
 STANDING: <the standing orders, verbatim: `workit ledger standing add` records each one>
+WORKTREE: <the path `workit fanout worktree create <slice>` made; the worker runs `workit --cwd <it> …` there>
   <identity line, per the lead's host: see "Identity and git rules per host" below>
 ```
 
@@ -48,6 +49,7 @@ FORBIDDEN: no edits outside SCOPE; no schema migration; no new packages
 FAN-IN: one PR per slice. Never rebase, retarget, merge or force-push: the lead owns topology.
 REPORT: as in the template
 STANDING: conventional commits; no comments that restate code; ask nothing, record rulings instead
+WORKTREE: ../app-wt/usage-endpoint  (made by `workit fanout worktree create usage-endpoint`; yours alone)
 ```
 
 ## Plan file
@@ -106,25 +108,29 @@ lead's host (`WORKIT_HOST`, or the host's own session variable):
 
 | Lead's host | Identity line | RULES 1 and 3 |
 | --- | --- | --- |
-| Claude Code | `Session: your env already has WORKIT_SESSION_ID (the lead's id)`; no `export`, no hand-minted id (SubagentStart issues `<lead>:<agent id>` only to verifiers and reviewers, never to an implementer, so the worker's commits carry the lead's id) | plain git: `git fetch origin && git switch -c <branch> origin/<base>` and `git commit -m <msg> --trailer "Workit-Session: <the env WORKIT_SESSION_ID>" --trailer "<host attribution>" -- <paths in SCOPE>`, because worktree isolation refuses every `workit git` form |
+| Claude Code | `Session: your env already has WORKIT_SESSION_ID (the lead's id)`; no `export`, no hand-minted id (SubagentStart issues `<lead>:<agent id>` only to verifiers and reviewers, never to an implementer, so the worker's commits carry the lead's id) | `workit git branch <branch> --base <base>`, `workit git commit -m <msg> -- <paths in SCOPE>`: the implementer runs without Claude Code's worktree isolation, which refused every `workit git` form |
 | OpenCode, Pi, Codex | `Session: your host already sets WORKIT_SESSION_ID in your shell`; export nothing (the host derives the id and an export cannot replace it) | `workit git branch <branch> --base <base>`, `workit git commit -m <msg> -- <paths in SCOPE>` |
 | Cursor, CI, a plain terminal | `export WORKIT_SESSION_ID=<lead>-w-<slice>` (`+try<n>` for a race attempt): declared, not checked | the same `workit git` forms |
 
-`MODE: resume` is `git switch <branch>` on every host (the branch exists; the
-lead removed the dead worker's worktree after its exit, so the switch
-succeeds), then continue from its head. A race attempt (`--attempt <n>`)
-follows its host's row with the branch `<branch>-try<n>`.
+Once `workit fanout worktree create <slice>` made the worktree, the brief's
+WORKTREE line names it and RULES 1 and 3 run against it on every host:
+`workit --cwd <worktree> git commit …`, `workit --cwd <worktree> check <name>`,
+one verb per call. The worktree is already on the branch (MODE new or resume),
+so no branch command comes first. Without one, `MODE: resume` is
+`git switch <branch>` (the branch exists), then continue from its head. A race
+attempt (`--attempt <n>`) follows its host's row with the branch
+`<branch>-try<n>`.
 
 ## Worker rules (`workit fanout brief` appends them as RULES)
 
-1. First command: create the branch (`MODE: new`; the worktree may start on a
-   name that breaks branch policy) or `git switch` to it (`MODE: resume`),
-   as the table above says for your host.
+1. Work only in WORKTREE, already on the branch, one verb per call against it
+   (`workit --cwd <worktree> …`); Workit's hooks deny an implementer's change
+   outside it. With no worktree made yet: create the branch (`MODE: new`) or
+   `git switch` to it (`MODE: resume`), as the table above says.
 2. Decide ambiguities yourself and record them:
    `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`.
    Stop only for an irreversible action, a security-sensitive one, or a side
    effect outside the worktree.
-3. Commit as the table says (`workit git commit -m "<msg>" -- <paths in SCOPE>`,
-   or plain git with the trailers on Claude Code); push only if the brief says
-   so.
+3. Commit with `workit --cwd <worktree> git commit -m "<msg>" -- <paths in SCOPE>`;
+   push only if the brief says so.
 4. Never record a verdict on your own work.

package/skills/workit-fanout/references/orchestration.md

@@ -35,8 +35,8 @@ parent is verified, appears there by itself.
 
 A slice is retried when it is STUCK, its worker exits without meeting
 ACCEPTANCE, or its verdict fails. Stop the worker and observe that it exited.
-Release its worktree: `workit fanout worktree release <slice>` (native
-worktrees: record `git -C <wt> status --short` first). Then spawn one fresh
+Release its worktree: `workit fanout worktree release <slice>` (it records
+`git status` first), and create it again for the retry. Then spawn one fresh
 worker with `workit fanout brief <slice> --mode resume`: same branch, and the
 brief points at its head and its ledger rows (last report, verdicts,
 rulings). If the retry fails too, escalate instead of a third worker:
@@ -69,9 +69,9 @@ list. The fixer applies that list once, then one focused recheck follows.
 When a hard slice has an uncertain approach and a cheap VERIFY, run 2-3
 attempts at once instead of retrying in series. `workit fanout brief <slice>
 --attempt <n>` gives each attempt its own branch (`<branch>-try<n>`), session
-and scratch dir. Each attempt needs its own worktree: Claude Code's
-`implementer` isolates natively; on other hosts `fanout worktree create` makes
-only the slice's own worktree, so run the attempts one after another there.
+and scratch dir. Each attempt needs its own worktree, and `fanout worktree
+create` makes only the slice's own one, so run the attempts one after another
+there on every host.
 Verify every attempt, keep the one with the best verdict (accepted first,
 then the fewest changed files, then the earliest), point the slice branch at
 it (`git branch <branch> <winner>`), have the verifier record the verdict on
@@ -109,7 +109,7 @@ Which session id a verdict carries, per host:
   `WORKIT_SESSION_ID=<lead>:verifier-<random hex>`, a fresh suffix per
   verifier. Cursor cannot check it: it is declared, not derived.
 - A worker's commits: on Claude Code the lead's `WORKIT_SESSION_ID` already in
-  its env (SubagentStart issues no implementer id; plain git, no export, so the
+  its env (SubagentStart issues no implementer id; no export, so the
   lead authored those commits: a verifier or reviewer records the verdict, not
   the lead); on OpenCode, Pi and Codex the id the host already
   puts in its shell; on Cursor, CI and a plain terminal the brief's

package/skills/workit-implement/SKILL.md

@@ -47,6 +47,8 @@ description: Build a requested change in small verified steps - follow local pat
    `workit verify-delivery push`).
 
 Independent slices that could run in parallel: fan them out (workit-fanout).
+One `implementer` slice: `workit fanout worktree create <slice>` before spawning,
+then `workit fanout brief <slice>`; no host isolation (Workit's hooks confine it).
 
 Stay inline by default (workspace `delegation: inline-first`). Hand work off
 only past the thresholds: an explorer after about 3 tool calls or 10k tokens

package/src/core/task-contract.ts

@@ -1068,10 +1068,6 @@ export const advertisedOperationSchemas = {
 } as const;
 export type TaskStartRequest = z.infer<typeof taskOperations.start>;
 
-const compiledOperationSchemas = Object.fromEntries(
-  OPERATION_FAMILIES.map((family) => [family, z.compile(operationSchemas[family])]),
-) as typeof operationSchemas;
-
 export type Id = string;
 export type Revision = string;
 export type Digest = string;
@@ -1165,8 +1161,7 @@ export function parseOperation(family: OperationFamily, input: unknown): Result<
     (input as { schemaVersion?: unknown }).schemaVersion !== SCHEMA_VERSION
   )
     return failure("unsupported_version", "unsupported schema version", { operation: family });
-  const compiled = compiledOperationSchemas[family].safeParse(input);
-  const parsed = compiled.success ? operationSchemas[family].safeParse(input) : compiled;
+  const parsed = operationSchemas[family].safeParse(input);
   if (parsed.success) return success(null, null, parsed.data);
   const fields = parsed.error.issues.map((issue) => ({
     path: issue.code === "unrecognized_keys" ? issue.keys.join(".") : issue.path.join("."),

package/src/fanout-brief.ts

@@ -8,9 +8,12 @@
 // `<worktree>+try<n>` and session `<lead>-w-<slice>+try<n>`: slice ids cannot
 // contain `+`, so no attempt collides with another slice's path or session.
 // The lead's host (WORKIT_HOST, or its own session variable) picks the identity
-// and git rules: Claude Code workers use the WORKIT_SESSION_ID in their env (the lead's: SubagentStart issues ids only to judges) and plain
-// git; OpenCode, Pi and Codex workers export nothing (the host derives the id);
-// Cursor, CI and plain terminals export `<lead>-w-<slice>`.
+// rules: Claude Code workers use the WORKIT_SESSION_ID in their env (the
+// lead's: SubagentStart issues ids only to judges); OpenCode, Pi and Codex
+// workers export nothing (the host derives the id);
+// Cursor, CI and plain terminals export `<lead>-w-<slice>`. Once
+// `workit fanout worktree create` made the slice's worktree, WORKTREE and the
+// RULES name it: every git and check command runs as `workit --cwd <worktree> …`.
 // The lead must have a WORKIT_SESSION_ID: worker ids derive from it. A
 // worker id longer than the ledger's 128 characters hashes its slice part. The fan-in line follows the plan's `fanIn`:
 // one PR per slice forbids every merge; integration mode has the worker merge
@@ -64,8 +67,7 @@ const REPORT = [
  * docs/agents/hosts.md):
  *   - `issued`: Claude Code. SubagentStart issues ids only to verifiers and
  *     reviewers, so an implementer keeps the lead's WORKIT_SESSION_ID from its
- *     env; worktree isolation refuses every `workit git` form, so it uses
- *     plain git and never mints an id;
+ *     env and never mints an id;
  *   - `derived`: OpenCode, Pi, Codex. The worker's shell carries the host's own
  *     session id, which exporting WORKIT_SESSION_ID cannot replace;
  *   - `declared`: Cursor, CI, a plain terminal. Nothing vouches for an id, so
@@ -83,7 +85,7 @@ const identityOf = (host: string | null): BriefIdentity => {
 const identityLines = (identity: BriefIdentity, session: string): string[] => {
   if (identity === "issued")
     return [
-      "  Session: your env already has WORKIT_SESSION_ID (the lead's id; SubagentStart issues ids only to verifiers and reviewers). Use it as is, in your Workit-Session trailer and workit commands; never export or hand-mint one.",
+      "  Session: your env already has WORKIT_SESSION_ID (the lead's id; SubagentStart issues ids only to verifiers and reviewers). Use it as is: workit commands read it and `workit git commit` adds the Workit-Session trailer; never export or hand-mint one.",
     ];
   if (identity === "derived")
     return [
@@ -92,25 +94,28 @@ const identityLines = (identity: BriefIdentity, session: string): string[] => {
   return [`  export WORKIT_SESSION_ID=${session}`];
 };
 
+/**
+ * RULES. With the slice's worktree made (`worktree`), every git and check
+ * command names it (`workit --cwd <worktree> …`, one verb per call) and it is
+ * already on the branch; Workit's hooks keep an implementer inside it (#310).
+ */
 const rules = (
-  identity: BriefIdentity,
   mode: BriefMode,
   branch: string,
   base: string,
+  worktree: string | null,
 ): string[] => {
-  const plain = identity === "issued";
+  const workit = worktree ? `workit --cwd ${worktree}` : "workit";
   let first = `  1. First command: \`workit git branch ${branch} --base ${base}\` (your worktree may start on another name).`;
-  if (mode === "resume")
+  if (worktree)
+    first = `  1. Work only in WORKTREE, already on ${branch}${mode === "resume" ? " at its head" : ""}: edit files under it and run each git and check command against it, one verb per call (\`${workit} git commit …\`, \`${workit} check <name>\`), never \`cd … &&\` chains or \`$VAR\` paths. An implementer's change outside it is denied.`;
+  else if (mode === "resume")
     first = `  1. First command: \`git switch ${branch}\`, then continue from its head.`;
-  else if (plain)
-    first = `  1. First command: \`git fetch origin && git switch -c ${branch} origin/${base}\` (plain git: worktree isolation refuses every \`workit git\` form).`;
   return [
     "RULES:",
     first,
     '  2. Decide ambiguities yourself: `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`; stop only for an irreversible, security-sensitive or out-of-worktree action.',
-    plain
-      ? '  3. Commit with plain `git commit -m <msg> --trailer "Workit-Session: <the WORKIT_SESSION_ID in your env>" --trailer "<your host attribution trailer>" -- <paths in SCOPE>`; push only if this brief says so.'
-      : "  3. Commit with `workit git commit -m <msg> -- <paths in SCOPE>`; push only if this brief says so.",
+    `  3. Commit with \`${workit} git commit -m <msg> -- <paths in SCOPE>\`; push only if this brief says so.`,
     "  4. Never record a verdict on your own work.",
     "  5. Run tests, lint, typecheck and builds only through `workit check` (a named check, or `workit check --heavy -- <cmd>`): one machine-wide lease queues every agent, so never a hand-made flock; `workit lock status` shows who holds it.",
     "  6. A failed review gets one fix round and one recheck. Still failing: stop and report the open finding, never a third round (the lead spawns a decider). A product choice is the user's: report it, do not decide it.",
@@ -226,8 +231,11 @@ export function renderBrief(
     ...(standing.length
       ? standing.map((order) => `  - ${order.what}`)
       : ["  - none recorded beyond this brief"]),
+    exists
+      ? `WORKTREE: ${planned}  (made by \`workit fanout worktree create ${slice.id}\`; yours alone)`
+      : `WORKTREE: ${planned}  (not made yet: the lead runs \`workit fanout worktree create ${slice.id}\` before spawning, then renders this brief again)`,
     ...identityLines(identity, minted),
-    ...rules(identity, mode, branch, slice.base),
+    ...rules(mode, branch, slice.base, exists ? planned : null),
   ];
   return {
     ok: true,

package/src/fanout-worktree.ts

@@ -28,6 +28,8 @@ import path from "node:path";
 import { gitBranch } from "./git/ops";
 import { GIT_TIMEOUTS, gitCommonDir, pushRemoteName, resolveRef } from "./git/rev";
 import { appendObserved, readLedger, type LedgerActor } from "./ledger";
+import { FANOUT_TOKEN_FILE } from "./hooks/worktree-confine";
+import { linkWorktreeDependencies, type LinkedDependencies } from "./worktree-deps";
 import {
   branchRef,
   fanoutFail,
@@ -154,8 +156,6 @@ function createdRow(cwd: string, plan: FanoutFile, slice: Slice, target: string)
   return { row, exact: false };
 }
 
-const TOKEN_FILE = "workit-fanout-token";
-
 /** The filesystem calls identity relies on; tests stub them. */
 export const worktreeDeps = {
   stat: (file: string): fs.BigIntStats => fs.statSync(file, { bigint: true }),
@@ -179,7 +179,7 @@ function adminDir(worktree: string): AdminDir | null {
   const file = dir.stdout.trim();
   let token: string | null = null;
   try {
-    token = fs.readFileSync(path.join(file, TOKEN_FILE), "utf8").trim() || null;
+    token = fs.readFileSync(path.join(file, FANOUT_TOKEN_FILE), "utf8").trim() || null;
   } catch {
     token = null;
   }
@@ -204,7 +204,7 @@ function markAdminDir(worktree: string): (AdminDir & { token: string }) | null {
   if (!admin) return null;
   const token = randomBytes(16).toString("hex");
   try {
-    fs.writeFileSync(path.join(admin.path, TOKEN_FILE), `${token}\n`);
+    fs.writeFileSync(path.join(admin.path, FANOUT_TOKEN_FILE), `${token}\n`);
   } catch {
     return null;
   }
@@ -253,6 +253,8 @@ export type CreateOutcome = {
   mode: "new" | "resume";
   /** False when the worktree already existed on the slice's branch. */
   created: boolean;
+  /** node_modules linked from the main checkout (worktree-deps.ts); null when none were. */
+  dependencies: LinkedDependencies | null;
   notes: string[];
 };
 
@@ -301,6 +303,7 @@ export function createSliceWorktree(
         `remove it yourself (git worktree remove ${target}) once you know what it holds`,
       );
     excludeScratch(cwd);
+    const deps = linkWorktreeDependencies(mainCheckout(cwd), target);
     return {
       ok: true,
       data: {
@@ -309,7 +312,13 @@ export function createSliceWorktree(
         head: existing.head ?? "",
         mode: resolveRef(cwd, localRef) ? "resume" : "new",
         created: false,
-        notes: ["the worktree already exists; nothing was changed"],
+        dependencies: deps.linked,
+        notes: [
+          deps.linked
+            ? "the worktree already exists; only its missing dependencies were linked"
+            : "the worktree already exists; nothing was changed",
+          ...deps.notes,
+        ],
       },
     };
   }
@@ -383,6 +392,8 @@ export function createSliceWorktree(
   }
   excludeScratch(cwd);
   const scratch = ensureScratch(target);
+  const deps = linkWorktreeDependencies(mainCheckout(cwd), target);
+  notes.push(...deps.notes);
   const head = gitRun(target, ["rev-parse", "HEAD"]).stdout.trim();
   const baseSha = mode === "new" ? head : null;
   const admin = markAdminDir(target);
@@ -402,7 +413,10 @@ export function createSliceWorktree(
     ...(admin ? { adminId: admin.id, adminIno: admin.ino, adminToken: admin.token } : {}),
     ...(baseSha ? { baseSha } : {}),
   });
-  return { ok: true, data: { ...base, scratch, head, mode, created: true, notes } };
+  return {
+    ok: true,
+    data: { ...base, scratch, head, mode, created: true, dependencies: deps.linked, notes },
+  };
 }
 
 const worktreeFailed = (stderr: string) =>

package/src/hooks/handle.ts

@@ -31,7 +31,8 @@ import { seedStanding, standingDelta } from "./standing";
 import { trackJudge } from "./session-marker";
 import { stopDecision } from "./stop";
 import { liveOwner } from "../core/live-session";
-import { shellGate, writeGate } from "./write-gate";
+import { liveTargets, shellGate, writeGate } from "./write-gate";
+import { confineImplementer, confineImplementerShell, hostIsolated } from "./worktree-confine";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
 export type HookDeps = { descriptor: HostDescriptor; addendum: string | null };
@@ -68,6 +69,12 @@ const workitRole = (
   return Object.hasOwn(ROLES, name) ? ROLES[name] : null;
 };
 
+/** A tool call made by a Workit implementer subagent (the host names its agent type). */
+const implementerAgent = (input: HookInput, descriptor: HostDescriptor): boolean =>
+  Boolean(input.session.agentId) &&
+  input.session.agentType !== null &&
+  workitRole(descriptor, input.session.agentType) === "implementer";
+
 /** `<lead session>:<agent id>`, safe for the ledger's session grammar. */
 const subagentSession = (session: string | null, agentId: string): string =>
   [session, agentId]
@@ -99,17 +106,22 @@ const subagentStartText = (
   const session = input.session.id ?? null;
   const role = workitRole(descriptor, event.agentType);
   const who = `${descriptor.label} subagent ${event.agentId} (${event.agentType})`;
+  // An implementer is host-isolated only when the host put it in its own
+  // worktree (`.claude/worktrees/agent-<id>`); by default the lead makes one.
   const isolated =
     descriptor.subagents.worktreeIsolation === "native" &&
-    (role === "implementer" || CLAUDE_WORKTREE.test(input.cwd));
+    (role === "implementer"
+      ? hostIsolated(input.cwd, event.agentId)
+      : CLAUDE_WORKTREE.test(input.cwd));
   const guide = role === "implementer" ? branchGuidance(input.cwd) : null;
   if (role === "implementer" && isolated)
     return `Workit observed ${who} working in its own git worktree: it may edit and commit there, within its brief's scope. ${isolatedGit(input.cwd)} Plain git is expected here, and the branch name is still policy-checked: a raw \`git switch -c\`, \`git checkout -b\`, \`git branch\` or \`git worktree add -b\` onto a protected or non-compliant name is denied, so use a policy-compliant branch.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   if (isolated)
     return `${isolatedGit(input.cwd)}\n${subagentStartText({ ...input, cwd: "" }, descriptor, event)}`;
   if (role === "implementer")
-    // No host isolation: the lead makes the worktree, and workit git works there.
-    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree (the lead makes one with \`workit fanout worktree create <slice>\`), never in the lead's checkout, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (or \`--kind <kind> --slug <slug>\`, which picks the base); branch policy hooks still deny protected or non-compliant branches, raw git included.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+    // No host isolation: the lead makes the worktree, Workit's hooks confine
+    // the implementer to it (worktree-confine.ts), and workit git works there.
+    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree, the one its brief names (the lead makes it with \`workit fanout worktree create <slice>\` before spawning), never in the lead's checkout, within its brief's scope. Workit binds it to the first Workit worktree it changes: from then on an edit or a mutating git command outside that worktree is denied, and before then so is one outside every Workit worktree. Run Workit against the worktree one verb per call, never \`cd … &&\` chains or \`$VAR\` paths: \`workit --cwd <worktree> git commit -m "<message>" -- <paths>\`, \`workit --cwd <worktree> check <name>\`. The worktree is on the brief's branch once the lead made it; otherwise switch with \`workit --cwd <worktree> git branch <branch> --base <base>\` (or \`--kind <kind> --slug <slug>\`, which picks the base); branch policy hooks still deny protected or non-compliant branches, raw git included.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   const readOnly = `Workit observed ${who} as read-only/agent-guided.`;
   if (role !== "judge" || !event.agentId) return readOnly;
   const own = subagentSession(session, event.agentId);
@@ -189,6 +201,11 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
       if (!postTool) settlePendingCommit(input);
       const raw = canDeny ? rawGitPre(input, event.command, { nudge: false }) : NONE;
       if (raw.kind === "deny") return raw;
+      // An implementer subagent stays in its Workit worktree (#310).
+      if (canDeny && implementerAgent(input, descriptor)) {
+        const confined = confineImplementerShell(input, event.command, event.dialect);
+        if (confined.kind === "deny") return confined;
+      }
       // The before-write gate and the live-session guard (#274).
       const gate = usable(descriptor.events["write.pre"].support)
         ? shellGate(input.cwd, event.command, liveOwner(input, descriptor.transport), event.dialect)
@@ -250,10 +267,14 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
       if (usable(descriptor.events["shell.post"].support))
         rawGitPost(input, event.command, callKey(event.toolUseId, event.command));
       return NONE;
-    case "write.pre":
-      return usable(descriptor.events["write.pre"].support)
-        ? writeGate(input.cwd, event.paths, liveOwner(input, descriptor.transport))
-        : NONE;
+    case "write.pre": {
+      if (!usable(descriptor.events["write.pre"].support)) return NONE;
+      if (implementerAgent(input, descriptor)) {
+        const confined = confineImplementer(input, liveTargets(input.cwd, event.paths));
+        if (confined.kind === "deny") return confined;
+      }
+      return writeGate(input.cwd, event.paths, liveOwner(input, descriptor.transport));
+    }
     case "subagent.start":
       if (workitRole(descriptor, event.agentType) === "judge")
         trackJudge(input, event.agentId, true);

package/src/hooks/raw-git.ts

@@ -788,6 +788,25 @@ export function workitInvocations(
   return found;
 }
 
+/** Workit's global options before the verb: `--json`, and these (`--name value` or `--name=value`). */
+const WORKIT_GLOBAL = /^--(?:cwd|session|token|as)(=|$)/;
+
+/** An invocation's arguments without the global options before the verb, and the last `--cwd` among them. */
+export function skipWorkitGlobals(args: readonly string[]): { rest: string[]; cwd: string | null } {
+  let cwd: string | null = null;
+  let at = 0;
+  for (; at < args.length; at++) {
+    const match = WORKIT_GLOBAL.exec(args[at]);
+    if (match?.[1] === "=") {
+      if (args[at].startsWith("--cwd=")) cwd = args[at].slice(6);
+    } else if (match && args[at + 1] !== undefined) {
+      if (args[at] === "--cwd") cwd = args[at + 1];
+      at++;
+    } else if (args[at] !== "--json") break;
+  }
+  return { rest: args.slice(at), cwd };
+}
+
 /** What one raw invocation means for workit. */
 export type RawAction =
   | { kind: "commit"; amend: boolean }

package/src/hooks/worktree-confine.ts

@@ -0,0 +1,363 @@
+// Worktree confinement for implementer subagents (#310). Without host
+// worktree isolation (Claude Code's refused every command it could not
+// verify, `workit git` included), the lead makes the implementer's worktree
+// with `workit fanout worktree create` and Workit's own hooks keep the
+// implementer in it:
+//
+// - binding: the first edit or mutating git command an implementer makes
+//   inside a worktree that `workit fanout worktree create` made (its admin
+//   dir holds the fanout token) binds that agent to it, in
+//   `<state dir>/worktree-bind/<session+agent>.json`, with a ledger row;
+// - after binding, an edit or mutating git command outside that worktree is
+//   denied naming it; the host's temp dir stays writable;
+// - before binding (ruling: the safe default), an edit outside every Workit
+//   worktree is denied too, so an implementer never edits the lead's checkout;
+// - always, what the lead owns is denied: worktree, ref and config changes
+//   (`git worktree add|remove`, `branch -D`, `update-ref`, a delete push…)
+//   and `workit fanout plan|worktree`.
+//
+// An agent the host isolated itself (a real linked worktree at Claude Code's
+// `<repo>/.claude/worktrees/agent-<id>`) is left to the host. Reads only the
+// filesystem; fails open on any error.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "../core/logger";
+import { appendHookObserved } from "../ledger";
+import type { HookDecision, HookInput } from "./protocol";
+import { inWorkitWorkspace, rawInvocations, skipWorkitGlobals, workitInvocations } from "./raw-git";
+import type { ShellDialect } from "./shell-words";
+import { shellMutationTargets, UNKNOWN_DIR } from "./write-gate";
+
+/** Written by `workit fanout worktree create` into git's admin dir for the worktree. */
+export const FANOUT_TOKEN_FILE = "workit-fanout-token";
+
+const NONE: HookDecision = { kind: "none" };
+const CASE_INSENSITIVE = process.platform === "darwin" || process.platform === "win32";
+
+/** The real path of `file`'s nearest existing ancestor, plus the rest. */
+const canonical = (file: string): string => {
+  let rest = "";
+  for (let dir = path.resolve(file); ; dir = path.dirname(dir)) {
+    try {
+      return path.join(fs.realpathSync.native(dir), rest);
+    } catch {
+      if (path.dirname(dir) === dir) return path.resolve(file);
+      rest = rest ? path.join(path.basename(dir), rest) : path.basename(dir);
+    }
+  }
+};
+
+const within = (child: string, parent: string): boolean => {
+  const fold = (value: string) => (CASE_INSENSITIVE ? value.toLowerCase() : value);
+  const relative = path.relative(fold(parent), fold(child));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+/**
+ * The git checkout `file` is in (the nearest directory above it with a
+ * `.git`), and whether `workit fanout worktree create` made it: its `.git`
+ * file names an admin dir that holds the fanout token. Null outside any
+ * repository.
+ */
+const checkoutOf = (file: string): { root: string; workit: boolean } | null => {
+  for (let dir = canonical(file); ; dir = path.dirname(dir)) {
+    const dotGit = path.join(dir, ".git");
+    if (fs.existsSync(dotGit)) {
+      if (!fs.statSync(dotGit).isFile()) return { root: dir, workit: false };
+      const admin = /^gitdir:\s*(.+)$/mu.exec(fs.readFileSync(dotGit, "utf8"))?.[1]?.trim();
+      return {
+        root: dir,
+        workit:
+          Boolean(admin) && fs.existsSync(path.join(path.resolve(dir, admin!), FANOUT_TOKEN_FILE)),
+      };
+    }
+    if (path.dirname(dir) === dir) return null;
+  }
+};
+
+/** The root of the Workit-made worktree `file` is in, else null. */
+const workitWorktreeOf = (file: string): string | null => {
+  try {
+    const checkout = checkoutOf(file);
+    return checkout?.workit ? checkout.root : null;
+  } catch {
+    return null;
+  }
+};
+
+type Binding = { worktree: string; session: string; agentId: string; at: string };
+
+// Bindings live in Workit's machine state dir, keyed by session and agent, so
+// one is kept wherever the hook's cwd is (even outside every repository).
+const bindingDir = (): string => path.join(resolveStateDir(), "worktree-bind");
+
+const bindingFile = (session: string, agentId: string): string =>
+  path.join(
+    bindingDir(),
+    `${createHash("sha256").update(`${session}\0${agentId}`).digest("hex").slice(0, 32)}.json`,
+  );
+
+const readBinding = (file: string): Binding | null => {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<Binding>;
+    return typeof value.worktree === "string" ? (value as Binding) : null;
+  } catch {
+    return null;
+  }
+};
+
+/** The worktree `input`'s agent is bound to, while that worktree is still a Workit one. */
+const boundWorktree = (input: HookInput): string | null => {
+  const agentId = input.session.agentId;
+  if (!agentId) return null;
+  const binding = readBinding(bindingFile(input.session.id, agentId));
+  return binding && workitWorktreeOf(binding.worktree) === binding.worktree
+    ? binding.worktree
+    : null;
+};
+
+const bind = (input: HookInput, worktree: string): void => {
+  const agentId = input.session.agentId!;
+  const file = bindingFile(input.session.id, agentId);
+  const binding: Binding = {
+    worktree,
+    session: input.session.id,
+    agentId,
+    at: new Date().toISOString(),
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(binding));
+  try {
+    if (inWorkitWorkspace(input.cwd))
+      appendHookObserved(input.cwd, {
+        type: "worktree.bound",
+        actor: { host: input.host, session: input.session.id, agentId },
+        agentType: input.session.agentType,
+        worktree,
+      });
+  } catch {
+    // The binding file is what the hook reads; the row is evidence only.
+  }
+};
+
+/**
+ * Claude Code's own isolation: the agent runs in a linked worktree (its `.git`
+ * is a file) whose root is exactly `<repo>/.claude/worktrees/agent-<its id>`.
+ * A directory that only looks like one is not.
+ */
+export const hostIsolated = (cwd: string, agentId: string | null): boolean => {
+  try {
+    if (agentId === null) return false;
+    const checkout = checkoutOf(cwd);
+    if (!checkout) return false;
+    const dotGit = path.join(checkout.root, ".git");
+    if (!fs.statSync(dotGit).isFile()) return false;
+    const admin = /^gitdir:\s*(.+)$/mu.exec(fs.readFileSync(dotGit, "utf8"))?.[1]?.trim();
+    if (!admin) return false;
+    const adminDir = path.resolve(checkout.root, admin);
+    // The admin dir must point back at this checkout: a forged `.git` file
+    // naming a sibling's admin dir does not make a directory that sibling's.
+    const back = fs.readFileSync(path.join(adminDir, "gitdir"), "utf8").trim();
+    if (path.relative(canonical(path.resolve(adminDir, back)), canonical(dotGit)) !== "")
+      return false;
+    const common = path.join(adminDir, "commondir");
+    const gitDir = fs.existsSync(common)
+      ? path.resolve(adminDir, fs.readFileSync(common, "utf8").trim())
+      : adminDir;
+    const expected = path.join(
+      path.dirname(canonical(gitDir)),
+      ".claude",
+      "worktrees",
+      `agent-${agentId}`,
+    );
+    return path.relative(canonical(expected), checkout.root) === "";
+  } catch {
+    return false;
+  }
+};
+
+const shown = (target: string): string =>
+  path.basename(target) === ".workit-live-target" ? path.dirname(target) : target;
+
+const unboundDeny = (input: HookInput, target: string): HookDecision => {
+  const unblock =
+    "Work only in the worktree your brief names, which the lead made with `workit fanout worktree create <slice>`: edit files under it and run one verb per call against it (`workit --cwd <worktree> git commit -m … -- <paths>`, `workit --cwd <worktree> check <name>`). If your brief names no worktree, stop and report that to the lead.";
+  return {
+    kind: "deny",
+    reason: `workit worktree confinement: implementer ${input.session.agentId} is not working in a Workit worktree yet, and ${shown(target)} is outside every worktree \`workit fanout worktree create\` made, so it would change the lead's checkout. ${unblock}`,
+    unblock,
+  };
+};
+
+const outsideDeny = (input: HookInput, worktree: string, target: string): HookDecision => {
+  const unblock = `Edit only under ${worktree} and run git there, one verb per call: \`workit --cwd ${worktree} git commit -m … -- <paths>\`, \`workit --cwd ${worktree} check <name>\` (or \`git -C ${worktree} …\`); a command whose writes Workit cannot see is judged by the directory it runs in. Anything outside it is a follow-up for your report.`;
+  return {
+    kind: "deny",
+    reason: `workit worktree confinement: implementer ${input.session.agentId} is bound to the worktree ${worktree}, and ${shown(target)} is outside it. ${unblock}`,
+    unblock,
+  };
+};
+
+const unknownDirDeny = (input: HookInput, worktree: string | null): HookDecision => {
+  const wt = worktree ?? "<worktree>";
+  const unblock = `Workit cannot resolve \`cd -\`, \`cd "$X"\` or \`popd\`: write by absolute path, \`git -C ${wt}\` or \`workit --cwd ${wt}\`.`;
+  return {
+    kind: "deny",
+    reason: `workit worktree confinement: implementer ${input.session.agentId} writes after an unknown directory change. ${unblock}`,
+    unblock,
+  };
+};
+
+/**
+ * Judge an implementer's edit or mutating command by the absolute paths it
+ * changes (`targets`). Only targets inside a git checkout, or Workit's
+ * binding records, are judged (scratch and temp files elsewhere are host
+ * policy). Binds on the first target inside a Workit worktree; denies a
+ * target outside the bound worktree (or, unbound, outside every Workit
+ * worktree). Deny reasons name a target as the agent spelled it.
+ */
+export function confineImplementer(input: HookInput, targets: readonly string[]): HookDecision {
+  try {
+    if (!input.session.agentId || hostIsolated(input.cwd, input.session.agentId)) return NONE;
+    if (targets.some((target) => within(path.resolve(target), UNKNOWN_DIR)))
+      return unknownDirDeny(input, boundWorktree(input));
+    const bindings = canonical(bindingDir());
+    const judged = targets
+      .map((named) => ({ named, real: canonical(named) }))
+      .filter(({ real }) => within(real, bindings) || checkoutOf(real) !== null);
+    if (judged.length === 0) return NONE;
+    let worktree = boundWorktree(input);
+    if (!worktree) {
+      for (const { real } of judged) {
+        worktree = within(real, bindings) ? null : workitWorktreeOf(real);
+        if (worktree) break;
+      }
+      if (!worktree) return unboundDeny(input, judged[0].named);
+      bind(input, worktree);
+    }
+    const root = canonical(worktree);
+    const outside = judged.find(({ real }) => !within(real, root) || within(real, bindings));
+    return outside ? outsideDeny(input, worktree, outside.named) : NONE;
+  } catch {
+    return NONE;
+  }
+}
+
+const MUTATING_REMOTE = new Set([
+  "add",
+  "remove",
+  "rm",
+  "rename",
+  "set-url",
+  "set-head",
+  "set-branches",
+  "prune",
+]);
+const CONFIG_READ = /^(?:--get(?:-all|-regexp|-urlmatch)?|--list|-l|get|list)$/;
+const CONFIG_WRITE =
+  /^(?:--(?:unset(?:-all)?|add|replace-all|rename-section|remove-section|edit)|-e|set|unset|rename-section|remove-section|edit)$/;
+const CONFIG_VALUE = /^(?:--file|-f|--blob|--type|--default|--comment)$/;
+
+/**
+ * Whether git `args` (the subcommand first) change what the lead owns: the
+ * repository's worktrees, refs other than by commit, the shared stash, or
+ * its configuration and remotes.
+ */
+const leadOwnedGit = (args: readonly string[]): boolean => {
+  const [sub = "", ...rest] = args;
+  if (rest.some((arg) => arg === "--help" || arg === "-h")) return false;
+  const names = rest.filter((arg) => !arg.startsWith("-"));
+  const flag = (pattern: RegExp) => rest.some((arg) => pattern.test(arg));
+  switch (sub) {
+    case "worktree":
+      return names[0] !== undefined && names[0] !== "list";
+    case "update-ref":
+      return true;
+    case "symbolic-ref":
+      return names.length > 1 || flag(/^(?:-d|--delete)$/);
+    case "branch":
+      return flag(/^-[a-zA-Z]*[dDfmMcC]|^--(?:delete|force|move|copy)$/);
+    case "tag":
+      return flag(/^-[a-zA-Z]*[df]|^--(?:delete|force)$/);
+    case "push": {
+      if (flag(/^(?:-d|--delete|--mirror|--prune)$/)) return true;
+      // names[0] is the remote; the rest are refspecs. `git push [-u] [remote]` and
+      // `git push --force-with-lease [remote]` (the current branch) stay the implementer's.
+      const refspecs = names.slice(1);
+      return (
+        refspecs.some((name) => name.includes(":") || name.startsWith("+")) ||
+        (refspecs.length > 0 && flag(/^-[a-zA-Z]*f|^--force/))
+      );
+    }
+    case "replace":
+    case "filter-branch":
+    case "gc":
+    case "prune":
+    case "repack":
+    case "sparse-checkout":
+      return true;
+    case "notes":
+    case "reflog":
+    case "submodule":
+      return !/^(?:list|show|status|exists)$/.test(names[0] ?? "list");
+    case "stash":
+      return names[0] === "drop" || names[0] === "clear";
+    case "remote":
+      return MUTATING_REMOTE.has(names[0] ?? "");
+    case "config": {
+      if (rest.some((arg) => CONFIG_READ.test(arg))) return false;
+      if (rest.some((arg) => CONFIG_WRITE.test(arg))) return true;
+      let operands = 0;
+      for (let index = 0; index < rest.length; index++)
+        if (CONFIG_VALUE.test(rest[index])) index++;
+        else if (!rest[index].startsWith("-")) operands++;
+      return operands > 1;
+    }
+    default:
+      return false;
+  }
+};
+
+/** A `workit [globals] fanout plan|worktree …` in `args` (also behind `check --`). */
+const leadOwnedWorkit = (args: readonly string[]): boolean =>
+  !args.includes("--help") &&
+  args.some((_, start) => {
+    if (start > 0 && !/(?:^|[\\/])workit(?:\.exe|\.cmd)?$/.test(args[start - 1])) return false;
+    const [verb, sub] = skipWorkitGlobals(args.slice(start)).rest;
+    return verb === "fanout" && /^(?:plan|worktree)$/.test(sub ?? "");
+  });
+
+const leadOwnedDeny = (input: HookInput, command: string): HookDecision => {
+  const unblock =
+    "Worktrees, branches other than your own, refs, tags, remotes, git config, the shared stash and the fan-out plan belong to the lead: report what you need changed as a follow-up instead.";
+  return {
+    kind: "deny",
+    reason: `workit worktree confinement: implementer ${input.session.agentId} may not run \`${command.slice(0, 160)}\`. ${unblock}`,
+    unblock,
+  };
+};
+
+/**
+ * Judge an implementer's shell command: deny what the lead owns, then confine
+ * every path it may change (the strict analysis, see `shellMutationTargets`).
+ */
+export function confineImplementerShell(
+  input: HookInput,
+  command: string,
+  dialect: ShellDialect = "posix",
+): HookDecision {
+  try {
+    if (!input.session.agentId || hostIsolated(input.cwd, input.session.agentId)) return NONE;
+    if (
+      rawInvocations(command, dialect).some(
+        (invocation) => invocation.tool === "git" && leadOwnedGit(invocation.args),
+      ) ||
+      workitInvocations(command, dialect).some(leadOwnedWorkit)
+    )
+      return leadOwnedDeny(input, command);
+  } catch {
+    // An unanalysable command falls through to the path confinement.
+  }
+  return confineImplementer(input, shellMutationTargets(input.cwd, command, dialect, true));
+}

package/src/hooks/write-gate.ts

@@ -4,7 +4,7 @@
 // unblock. History moves (commit, merge, rebase, stash pop) are not edits.
 // Reads only the task index, one task snapshot and the ledger; never
 // migrates, never captures a candidate, and fails open on any state error.
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileSignature, TaskStore } from "../core/task-store";
@@ -25,6 +25,7 @@ import {
   inWorkitWorkspace,
   rawInvocations,
   workitCheckTail,
+  skipWorkitGlobals,
   workitInvocations,
   type RawInvocation,
 } from "./raw-git";
@@ -70,7 +71,7 @@ const exempt = (cwd: string, root: string, file: string, plans: ReadonlySet<stri
   );
 };
 
-const PREFIXES = new Set(["sudo", "command", "env", "nohup", "time", "exec", "xargs"]);
+const PREFIXES = new Set(["sudo", "command", "env", "nohup", "time", "exec", "xargs", "busybox"]);
 const operands = (words: string[]) => words.filter((item) => !item.startsWith("-"));
 
 const SCRIPT_SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
@@ -86,12 +87,9 @@ const wrappedScript = (input: string[]): string | null => {
   const tail = workitCheckTail(words);
   if (!tail) return null;
   if ("script" in tail) return tail.script;
-  const [shell, flag, script] = tail.argv;
-  if (
-    SCRIPT_SHELLS.has((shell.split(/[\\/]/).at(-1) ?? "").toLowerCase()) &&
-    /^-[a-z]*c$/.test(flag ?? "")
-  )
-    return script ?? null;
+  const script = shellScript(tail.argv);
+  if (SCRIPT_SHELLS.has((tail.argv[0]?.split(/[\\/]/).at(-1) ?? "").toLowerCase()) && script)
+    return script;
   return tail.argv.map(quoteWord).join(" ");
 };
 
@@ -167,6 +165,112 @@ const editsOf = (input: string[]): string[] | null => {
   }
 };
 
+/** A `bash -c '<script>'` (any SCRIPT_SHELLS) script, else null. */
+const shellScript = (words: readonly string[]): string | null => {
+  if (!SCRIPT_SHELLS.has((words[0]?.split(/[\\/]/).at(-1) ?? "").toLowerCase())) return null;
+  // Options may come before `-c` (`bash --norc -c`, `sh -e -c`); the script follows it.
+  for (let index = 1; index < words.length; index++) {
+    const word = words[index];
+    if (/^-[a-z]*c$/.test(word)) return words[index + 1] ?? null;
+    if (/^[-+][oO]$/.test(word)) index++;
+    else if (!/^[-+]/.test(word)) return null;
+  }
+  return null;
+};
+
+/** xargs options that take the next word as their value. */
+const XARGS_VALUE = /^-[IinLPdsEa]$/;
+
+/** The command `xargs` (or `find -exec`) runs with `{}` filled in by a path. */
+const runsWriter = (words: readonly string[]): boolean => {
+  const filled = [...words.filter((word) => word !== "{}" && word !== ";" && word !== "+"), "x"];
+  const edits = editsOf(filled);
+  return edits === null || edits.length > 0 || opaqueWrites(filled) !== null;
+};
+
+/**
+ * For an implementer's confinement: commands that may write where the edit
+ * analysis cannot see (interpreters, chmod, rsync, `find -delete`, `xargs rm`,
+ * `awk -i`, a `-c` shell script): the paths they may change, "." standing for
+ * the directory they run in; null when the command is none of them.
+ */
+const opaqueWrites = (input: readonly string[]): string[] | null => {
+  let words = input;
+  while (words.length && (PREFIXES.has(words[0]) || /^\w+=/.test(words[0]))) {
+    if (words[0] === "xargs") {
+      let at = 1;
+      while (words[at]?.startsWith("-")) at += XARGS_VALUE.test(words[at]) ? 2 : 1;
+      return runsWriter(words.slice(at)) ? ["."] : null;
+    }
+    words = words.slice(1);
+  }
+  const [verb, ...args] = words;
+  const name = (verb?.split(/[\\/]/).at(-1) ?? "").toLowerCase();
+  const files = operands(args);
+  const has = (pattern: RegExp) => args.some((arg) => pattern.test(arg));
+  const listed = (named: string[]) => (named.length ? named : ["."]);
+  if (name === "unlink" || name === "shred") return listed(files);
+  // The mode or owner comes first, unless `--reference` names it.
+  if (/^(?:chmod|chown|chgrp|chattr)$/.test(name))
+    return listed(has(/^--reference/) ? files : files.slice(1));
+  if (name === "rsync") {
+    const dest = files.at(-1);
+    // `host:path` is remote; a drive letter (`C:/…`, `C:\…`) is a local path.
+    const remote = /^[\w.@-]*:/.test(dest ?? "") && !/^[A-Za-z]:[\\/]/.test(dest ?? "");
+    return dest === undefined ? ["."] : remote ? [] : [dest];
+  }
+  if (name === "find") {
+    const exec = args.findIndex((arg) => /^-(?:exec|execdir|ok|okdir)$/.test(arg));
+    const writes =
+      has(/^-(?:delete|fprint\w*|fls)$/) || (exec >= 0 && runsWriter(args.slice(exec + 1)));
+    const end = args.findIndex((arg) => /^[-(!]/.test(arg));
+    return writes ? listed(end < 0 ? args : args.slice(0, end)) : null;
+  }
+  if (/^g?awk$/.test(name)) {
+    if (!has(/^-i|^--include/)) return null;
+    const named: string[] = [];
+    let program = !has(/^-f$|^--file/);
+    for (let index = 0; index < args.length; index++)
+      if (/^(?:-[ifvF]|--(?:include|file|assign|field-separator))$/.test(args[index])) index++;
+      else if (args[index].startsWith("-")) continue;
+      else if (program) program = false;
+      else named.push(args[index]);
+    return listed(named);
+  }
+  if (name === "perl") return has(/^-[a-zA-Z]*[eE]/) ? ["."] : null;
+  if (/^(?:python[\d.]*|node|bun|deno|ruby|php)$/.test(name))
+    return has(/^-[a-zA-Z]*[ce]$|^--eval$|^-p$/) ? ["."] : null;
+  return shellScript(words) === null ? null : ["."];
+};
+
+/**
+ * `ln`'s link sources, resolved as the link will: a relative symbolic source
+ * against the directory the link lands in. Writes through such a link change
+ * its source, so an implementer's links are judged by where they point.
+ */
+const linkSources = (args: readonly string[], at: (file: string) => string | null): string[] => {
+  const names = operands([...args]);
+  const into = args.indexOf("-t");
+  const dest = into >= 0 ? args[into + 1] : names.length > 1 ? names.at(-1) : ".";
+  const sources = names.filter((name, index) =>
+    into >= 0 ? name !== dest : index < names.length - 1 || names.length === 1,
+  );
+  const target = dest === undefined ? null : at(dest);
+  const symbolic = args.some((arg) => /^-[a-zA-Z]*s|^--symbolic$/.test(arg));
+  const base =
+    target === null
+      ? null
+      : into >= 0 || sources.length > 1 || existsSync(target) || /[\\/]$/.test(dest ?? "")
+        ? target
+        : path.dirname(target);
+  return sources.flatMap((source) => {
+    if (symbolic && base !== null && !path.isAbsolute(homeExpanded(source)))
+      return [path.resolve(base, source)];
+    const resolved = at(source);
+    return resolved ? [resolved] : [];
+  });
+};
+
 /**
  * Whether a shell command recognizably edits files (redirects, tee, touch,
  * mkdir, cp/mv/rm, `sed -i`/`perl -i`, dd, and working-tree git: apply,
@@ -325,13 +429,25 @@ const CD = new Set(["cd", "chdir", "set-location", "sl"]);
 const PUSHD = new Set(["pushd", "push-location"]);
 const POPD = new Set(["popd", "pop-location"]);
 
-/** A `cd` operand resolved against `dir`; undefined when it cannot be known. */
-const cdInto = (dir: string | undefined, words: string[]): string | undefined => {
+/**
+ * Stands for a directory an implementer's command moved to but the analysis
+ * cannot name (`cd -`, `cd "$X"`, a bare `popd`): a write that lands under it
+ * is denied by `confineImplementer`, as the shell may be anywhere.
+ */
+export const UNKNOWN_DIR = path.resolve(path.parse(process.cwd()).root, ".workit-unknown-dir");
+
+/**
+ * A `cd` operand resolved against `dir`. A target that cannot be known is
+ * undefined, or `UNKNOWN_DIR` when `strict`.
+ */
+const cdInto = (dir: string | undefined, words: string[], strict = false): string | undefined => {
+  const lost = strict ? UNKNOWN_DIR : undefined;
   const named = words.slice(1).find((word) => !word.startsWith("-") || word === "-");
   // Only a leading `~` or `$HOME` expands; a mid-path `~` is literal (Windows 8.3
   // short names like RUNNER~1).
   const target = named === undefined ? undefined : homeExpanded(named);
-  if (dir === undefined || target === "-" || (target && /^~|[$`*?]/.test(target))) return undefined;
+  if (target === "-" || (target && /^~|[$`*?]/.test(target))) return lost;
+  if (dir === undefined) return lost;
   return target === undefined ? os.homedir() : path.resolve(dir, target);
 };
 
@@ -355,6 +471,7 @@ const segmentTargets = (
   command: string,
   dialect: ShellDialect,
   depth = 0,
+  strict = false,
 ): string[] => {
   const targets: string[] = [];
   let dir: string | undefined = cwd;
@@ -378,21 +495,34 @@ const segmentTargets = (
     const words = lead < 0 ? [] : segment.words.slice(lead);
     const name = (words[0]?.split(/[\\/]/).at(-1) ?? "").toLowerCase();
     if (CD.has(name)) {
-      dir = cdInto(dir, words);
+      dir = cdInto(dir, words, strict);
       continue;
     }
     if (PUSHD.has(name)) {
       stack.push(dir);
-      dir = cdInto(dir, words);
+      dir = cdInto(dir, words, strict);
       continue;
     }
     if (POPD.has(name)) {
-      dir = stack.length ? stack.pop() : undefined;
+      dir = stack.length ? stack.pop() : strict ? UNKNOWN_DIR : undefined;
       continue;
     }
-    const inner = depth < 4 ? wrappedScript(words) : null;
+    const inner = depth < 4 ? (wrappedScript(words) ?? (strict ? shellScript(words) : null)) : null;
     if (inner !== null && dir !== undefined)
-      targets.push(...segmentTargets(dir, inner, "posix", depth + 1));
+      targets.push(...segmentTargets(dir, inner, "posix", depth + 1, strict));
+    if (strict && dir !== undefined) {
+      const runIn = dir;
+      for (const sub of depth < 4 ? (segment.subs ?? []) : [])
+        targets.push(...segmentTargets(runIn, sub, dialect, depth + 1, true));
+      const opaque = segment.unanalyzable ? ["."] : inner === null ? opaqueWrites(words) : null;
+      for (const file of opaque ?? []) {
+        const resolved = at(file);
+        if (resolved) targets.push(file === "." ? path.join(resolved, DIR_TARGET) : resolved);
+      }
+      const ln = words.findIndex((word) => /^ln$/i.test(word.split(/[\\/]/).at(-1) ?? ""));
+      if (ln >= 0 && words.slice(0, ln).every((word) => PREFIXES.has(word)))
+        targets.push(...linkSources(words.slice(ln + 1), at));
+    }
     for (const file of segment.redirects)
       if (!/^\/dev\/(?:null|stdout|stderr|tty)$/.test(file)) {
         const resolved = at(file);
@@ -406,18 +536,51 @@ const segmentTargets = (
         const resolved = at(file);
         if (resolved) targets.push(resolved);
       }
-    if (
-      dir !== undefined &&
-      workitInvocations(segment.words.map(quoteWord).join(" "), "posix").some(
-        (args) =>
-          args[0] === "git" && MUTATING_WORKIT_GIT.has(args[1] ?? "") && !inert(args.slice(2), ""),
-      )
-    )
-      targets.push(path.join(dir, DIR_TARGET));
+    if (dir !== undefined)
+      for (const invocation of workitInvocations(segment.words.map(quoteWord).join(" "), "posix")) {
+        const { at: runsIn, args } = workitCwd(dir, invocation);
+        if (
+          args[0] === "git" &&
+          MUTATING_WORKIT_GIT.has(args[1] ?? "") &&
+          !inert(args.slice(2), "")
+        )
+          targets.push(path.join(runsIn, DIR_TARGET));
+      }
   }
   return targets;
 };
 
+/** A workit invocation's global `--cwd <dir>` (or `--cwd=<dir>`), resolved against `dir`. */
+const workitCwd = (dir: string, args: string[]): { at: string; args: string[] } => {
+  const { rest, cwd } = skipWorkitGlobals(args);
+  return { at: cwd === null ? dir : path.resolve(dir, homeExpanded(cwd)), args: rest };
+};
+
+/**
+ * Where one shell command changes files: the files it writes and, as
+ * `<dir>/.workit-live-target`, each directory a mutating git or
+ * `workit git commit|branch` runs in or an unknown write happens in.
+ * `strict` (an implementer's confinement) also reads `-c` shell scripts and
+ * `$(…)`, counts writers the analysis cannot see in the directory they run
+ * in, and judges `ln` sources. Absolute paths; [] when the command cannot be
+ * analysed (fail open).
+ */
+export const shellMutationTargets = (
+  cwd: string,
+  command: string,
+  dialect: ShellDialect = "posix",
+  strict = false,
+): string[] => {
+  try {
+    return [
+      ...segmentTargets(cwd, command, dialect, 0, strict),
+      ...gitMutationDirs(cwd, command, dialect).map((dir) => path.join(dir, DIR_TARGET)),
+    ];
+  } catch {
+    return [];
+  }
+};
+
 /** The command is one simple command led by `WORKIT_LIVE_SESSION=override`. */
 const overridden = (command: string, dialect: ShellDialect): boolean => {
   const segments = segmentsOf(command, dialect);
@@ -482,7 +645,7 @@ const claimAll = (owner: LiveOwner, targets: readonly string[], deps?: LiveDeps)
 };
 
 /** The absolute paths an edit touches: its files, or cwd itself when unknown. */
-const liveTargets = (cwd: string, paths: readonly string[] | null): string[] =>
+export const liveTargets = (cwd: string, paths: readonly string[] | null): string[] =>
   paths?.length ? paths.map((file) => path.resolve(cwd, file)) : [path.join(cwd, DIR_TARGET)];
 
 // --- the issued-registry guard (#292) ---------------------------------------
@@ -593,16 +756,7 @@ export function shellGate(
   }
   const writes = shellWrites(command);
   let targets: string[] = [];
-  if (owner) {
-    try {
-      targets = [
-        ...segmentTargets(cwd, command, dialect),
-        ...gitMutationDirs(cwd, command, dialect).map((dir) => path.join(dir, DIR_TARGET)),
-      ];
-    } catch {
-      targets = [];
-    }
-  }
+  if (owner) targets = shellMutationTargets(cwd, command, dialect);
   if (owner && targets.length) {
     const live = liveGate(owner, targets, deps);
     if (live.kind !== "none") {

package/src/worktree-deps.ts

@@ -0,0 +1,142 @@
+// Dependencies for a fresh worktree (issue #310): a linked worktree has no
+// node_modules, so a resolver walks up to whatever node_modules is above it
+// (the main checkout's, for a worktree nested inside it) and a workspace
+// package resolves to the main checkout's source: tests then run the wrong
+// code. Instead of a package-manager install, the worktree gets its own
+// node_modules that mirrors the main checkout's one level deep:
+//
+// - a symlink is copied as it is: a relative one (bun, npm and yarn link
+//   workspace packages as `../../packages/<name>`, and `.bin` entries as
+//   `../<pkg>/bin/x`) then resolves inside the worktree, which has the same
+//   layout; an absolute one into the main checkout (a Windows junction) is
+//   re-pointed at the worktree's counterpart;
+// - `@scope` directories and `.bin` are mirrored the same way, one level;
+// - anything else (a third-party package) is linked to the main checkout's,
+//   so installed packages are shared, never copied.
+//
+// It runs only where the worktree has no node_modules of its own and git
+// ignores node_modules there (else the links would show as changes and block
+// release). `git worktree remove` unlinks the links and never follows them.
+import fs from "node:fs";
+import path from "node:path";
+import { gitRun } from "./fanout";
+
+const MODULES = "node_modules";
+/** Directories searched for node_modules below the checkout root (packages/<name>). */
+const MAX_DEPTH = 2;
+
+export type LinkedDependencies = {
+  /** The main checkout the links point at. */
+  from: string;
+  /** The node_modules directories made, relative to the worktree. */
+  dirs: string[];
+  /** Links made across them. */
+  entries: number;
+  ms: number;
+};
+
+const within = (child: string, parent: string): boolean => {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+/** node_modules directories of the main checkout, as paths relative to it. */
+function moduleDirs(main: string): string[] {
+  const out: string[] = [];
+  const walk = (relative: string, depth: number) => {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(path.join(main, relative), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const child = path.join(relative, entry.name);
+      if (entry.name === MODULES) out.push(child);
+      else if (depth < MAX_DEPTH && !entry.name.startsWith(".")) walk(child, depth + 1);
+    }
+  };
+  walk("", 0);
+  return out;
+}
+
+function linkEntry(main: string, worktree: string, source: string, target: string): void {
+  const stat = fs.lstatSync(source);
+  if (stat.isSymbolicLink()) {
+    const link = fs.readlinkSync(source);
+    // An absolute link into the main checkout (outside its node_modules) is a
+    // workspace package: point it at the worktree's copy.
+    const outside =
+      path.isAbsolute(link) &&
+      within(link, main) &&
+      !path.relative(main, link).split(path.sep).includes(MODULES);
+    const to = outside ? path.join(worktree, path.relative(main, link)) : link;
+    fs.symlinkSync(to, target, process.platform === "win32" ? "junction" : undefined);
+    return;
+  }
+  fs.symlinkSync(
+    source,
+    target,
+    process.platform === "win32" ? (stat.isDirectory() ? "junction" : "file") : undefined,
+  );
+}
+
+/** Mirror `source` into a new directory `target`; returns the links made. */
+function mirror(main: string, worktree: string, source: string, target: string, top: boolean) {
+  fs.mkdirSync(target);
+  let count = 0;
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const from = path.join(source, entry.name);
+    const to = path.join(target, entry.name);
+    if (top && entry.isDirectory() && (entry.name.startsWith("@") || entry.name === ".bin"))
+      count += mirror(main, worktree, from, to, false);
+    else {
+      linkEntry(main, worktree, from, to);
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * Give `worktree` node_modules that resolve its own workspace packages and
+ * share the main checkout's installed ones. Null when there is nothing to
+ * link (no node_modules in the main checkout), with a note when it was
+ * skipped; never throws.
+ */
+export function linkWorktreeDependencies(
+  main: string,
+  worktree: string,
+): { linked: LinkedDependencies | null; notes: string[] } {
+  const started = performance.now();
+  const notes: string[] = [];
+  const dirs: string[] = [];
+  let entries = 0;
+  for (const relative of moduleDirs(main)) {
+    const target = path.join(worktree, relative);
+    if (!fs.existsSync(path.dirname(target)) || fs.existsSync(target)) continue;
+    // The trailing slash: the directory does not exist yet, and `node_modules/` only matches one.
+    if (!gitRun(worktree, ["check-ignore", "-q", `${relative.split(path.sep).join("/")}/`]).ok) {
+      notes.push(
+        `${relative.split(path.sep).join("/")} is not ignored by git, so it was not linked from ${main}; install dependencies in the worktree yourself`,
+      );
+      continue;
+    }
+    try {
+      entries += mirror(main, worktree, path.join(main, relative), target, true);
+      dirs.push(relative.split(path.sep).join("/"));
+    } catch (error) {
+      fs.rmSync(target, { recursive: true, force: true });
+      notes.push(
+        `could not link ${relative} from ${main} (${(error as Error).message}); install dependencies in the worktree yourself`,
+      );
+    }
+  }
+  if (dirs.length === 0) return { linked: null, notes };
+  const ms = Math.round(performance.now() - started);
+  notes.push(
+    `linked ${dirs.join(", ")} from ${main} (${entries} entries, ${ms} ms): workspace packages resolve to this worktree, installed packages are shared`,
+  );
+  return { linked: { from: main, dirs, entries, ms }, notes };
+}