@brainervirus/workit-core 8.22.3 → 8.24.0

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") {