@fusengine/harness 0.1.92 → 0.1.94

package/src/policy/prd/prd-ownership.ts

@@ -0,0 +1,99 @@
+/**
+ * The PreToolUse ownership decision. Everything it needs is passed in — no
+ * I/O. Pure functions over already-loaded router/task-PRD/bindings data.
+ */
+import type { PrdIdentity, PrdOwnershipVerdict, PrdPathKind, PrdTaskFile } from "./interfaces/types";
+
+/** True when `name === agentType`, or `"<agentType>-<n>"` with `n >= 2`. */
+export function matchesAgentName(name: string, agentType: string): boolean {
+  if (name === agentType) return true;
+  if (!name.startsWith(agentType)) return false;
+  const suffix = name.slice(agentType.length);
+  if (!suffix.startsWith("-")) return false;
+  const numPart = suffix.slice(1);
+  return /^\d+$/.test(numPart) && Number(numPart) >= 2;
+}
+
+/** Agent names in `taskFile` whose name matches `agentType` (base or `-n` suffixed). */
+export function candidateAgentNames(agentType: string, taskFile: PrdTaskFile): string[] {
+  return Object.keys(taskFile).filter((name) => matchesAgentName(name, agentType));
+}
+
+/**
+ * agentId -> bound name resolution. `bindings` is the journal's `prdOwners`
+ * map (agentId -> name), read-only here. Returns the candidate already
+ * bound to this agentId, or the SOLE still-unbound candidate (free to bind
+ * now), or `null` (ambiguous: >1 free candidate, or 0 candidates at all).
+ */
+export function resolveOwnerBinding(
+  candidates: string[],
+  agentId: string,
+  bindings: Record<string, string>,
+): { name: string; alreadyBound: boolean } | null {
+  const boundToMe = bindings[agentId];
+  if (boundToMe !== undefined && candidates.includes(boundToMe)) {
+    return { name: boundToMe, alreadyBound: true };
+  }
+  const takenByOthers = new Set(
+    Object.entries(bindings).filter(([id]) => id !== agentId).map(([, name]) => name),
+  );
+  const free = candidates.filter((c) => !takenByOthers.has(c));
+  if (free.length !== 1) return null;
+  const [name] = free;
+  return name === undefined ? null : { name, alreadyBound: false };
+}
+
+const COORDINATOR_ONLY_LABEL: Record<"router" | "task" | "docs", string> = {
+  router: "router",
+  task: "task PRD",
+  docs: "docs",
+};
+
+function evaluateCoordinatorOnly(kind: "router" | "task" | "docs", identity: PrdIdentity): PrdOwnershipVerdict {
+  if (identity.lead === true) return { allow: true };
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  return { allow: false, reason: `${COORDINATOR_ONLY_LABEL[kind]} is coordinator-only` };
+}
+
+function evaluateAgentReport(
+  agent: string,
+  identity: PrdIdentity,
+  taskFile: PrdTaskFile | null,
+  bindings: Record<string, string>,
+): PrdOwnershipVerdict {
+  if (identity.lead === true) return { allow: false, reason: "agent report is not the coordinator's to write" };
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  if (identity.agentType === undefined || identity.agentId === undefined) {
+    return { allow: false, reason: "unidentifiable agent_type — cannot verify ownership" };
+  }
+  const candidates = candidateAgentNames(identity.agentType, taskFile ?? {});
+  const resolved = resolveOwnerBinding(candidates, identity.agentId, bindings);
+  if (!resolved || resolved.name !== agent) {
+    return { allow: false, reason: "name doesn't match your agent_type, or already bound to another agent" };
+  }
+  return resolved.alreadyBound
+    ? { allow: true }
+    : { allow: true, bind: { agentId: identity.agentId, name: resolved.name } };
+}
+
+/**
+ * Top-level PreToolUse verdict for ONE file path already known to be in
+ * scope (`classifyPrdPath` returned non-`"other"`/non-`null` upstream).
+ */
+export function evaluateWriteOwnership(input: {
+  kind: PrdPathKind;
+  identity: PrdIdentity;
+  taskFile: PrdTaskFile | null;
+  bindings: Record<string, string>;
+}): PrdOwnershipVerdict {
+  const { kind, identity, taskFile, bindings } = input;
+
+  if (kind.kind === "router" || kind.kind === "task" || kind.kind === "docs") {
+    return evaluateCoordinatorOnly(kind.kind, identity);
+  }
+  if (kind.kind === "agentReport") {
+    return evaluateAgentReport(kind.agent, identity, taskFile, bindings);
+  }
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  return { allow: false, reason: "not a recognized PRD file" };
+}

package/src/policy/prd/prd-paths.ts

@@ -0,0 +1,88 @@
+/**
+ * Pure path builders and classifiers for the PRD file tree
+ * (`<root>/<homeSeg>/apex/prd*`). No fs access — string/path compare only.
+ */
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import type { PrdPathKind, PrdRouter } from "./interfaces/types";
+
+const AGENT_REPORT_SUFFIX = "-prd.json";
+const DOCS_SUFFIX = ".md";
+
+function apexDir(root: string, homeSeg: string): string {
+  return join(root, homeSeg, "apex");
+}
+
+/** Absolute path to the router (`<root>/<homeSeg>/apex/prd.json`). */
+export function prdRouterPath(root: string, homeSeg: string): string {
+  return join(apexDir(root, homeSeg), "prd.json");
+}
+
+/** Absolute path to the PRD directory (`<root>/<homeSeg>/apex/prd`). */
+export function prdDir(root: string, homeSeg: string): string {
+  return join(apexDir(root, homeSeg), "prd");
+}
+
+/** Absolute path to a task-PRD file, given the router entry's `prd` field. */
+export function prdTaskPath(root: string, homeSeg: string, relPrd: string): string {
+  return join(apexDir(root, homeSeg), relPrd);
+}
+
+/** Absolute path to an agent's own report file (`prd/agents/<agent>-prd.json`). */
+export function prdAgentReportPath(root: string, homeSeg: string, agent: string): string {
+  return join(prdDir(root, homeSeg), "agents", `${agent}${AGENT_REPORT_SUFFIX}`);
+}
+
+/** Absolute path to a task's free-form doc (`prd/docs/<task>.md`). */
+export function prdDocsPath(root: string, homeSeg: string, task: string): string {
+  return join(prdDir(root, homeSeg), "docs", `${task}${DOCS_SUFFIX}`);
+}
+
+function resolveAgainstRoot(filePath: string, root: string): string {
+  return isAbsolute(filePath) ? resolve(filePath) : resolve(root, filePath);
+}
+
+/**
+ * True when `filePath` (absolute or root-relative) resolves under
+ * `<root>/<homeSeg>/apex/prd/`, or is exactly the router itself. Normalizes
+ * via `path.resolve`/`relative`; a `..` that escapes the PRD dir is rejected.
+ */
+export function isPrdScopedPath(filePath: string, root: string, homeSeg: string): boolean {
+  const abs = resolveAgainstRoot(filePath, root);
+  if (abs === resolve(prdRouterPath(root, homeSeg))) return true;
+  const rel = relative(resolve(prdDir(root, homeSeg)), abs);
+  return rel !== "" && rel !== "." && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Classifies an in-scope PRD path into one of the 4 file kinds (router,
+ * task, agentReport, docs), or `"other"` when it is textually under
+ * `apex/prd/` but matches none of the router-declared task files. `null`
+ * when the path is not in scope at all (see {@link isPrdScopedPath}).
+ */
+export function classifyPrdPath(
+  filePath: string,
+  root: string,
+  homeSeg: string,
+  router: PrdRouter | null,
+): PrdPathKind | null {
+  if (!isPrdScopedPath(filePath, root, homeSeg)) return null;
+  const abs = resolveAgainstRoot(filePath, root);
+  if (abs === resolve(prdRouterPath(root, homeSeg))) return { kind: "router" };
+
+  const dir = resolve(prdDir(root, homeSeg));
+  const parts = relative(dir, abs).split(sep);
+  const [first, second] = parts;
+
+  if (parts.length === 2 && first === "agents" && second?.endsWith(AGENT_REPORT_SUFFIX)) {
+    return { kind: "agentReport", agent: second.slice(0, -AGENT_REPORT_SUFFIX.length) };
+  }
+  if (parts.length === 2 && first === "docs" && second?.endsWith(DOCS_SUFFIX)) {
+    return { kind: "docs", task: second.slice(0, -DOCS_SUFFIX.length) };
+  }
+  if (router) {
+    for (const [task, entry] of Object.entries(router)) {
+      if (resolve(prdTaskPath(root, homeSeg, entry.prd)) === abs) return { kind: "task", task };
+    }
+  }
+  return { kind: "other" };
+}

package/src/policy/prd/prd-schema.ts

@@ -0,0 +1,151 @@
+/**
+ * Fail-closed parsers (malformed input -> `null`, never throw) and small
+ * immutable builders for the PRD JSON contract. Pure — no fs.
+ */
+import type {
+  PrdAgentEntryCompacted, PrdAgentReportFile, PrdRouter, PrdRouterEntry, PrdRouterStatus,
+  PrdSubTask, PrdTaskAgentEntry, PrdTaskFile,
+} from "./interfaces/types";
+
+const ROUTER_STATUSES: readonly PrdRouterStatus[] = ["assigned", "in-progress", "validated"];
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+function parseRouterEntry(v: unknown): PrdRouterEntry | null {
+  if (!isRecord(v)) return null;
+  if (typeof v.prd !== "string") return null;
+  if (typeof v.status !== "string" || !ROUTER_STATUSES.includes(v.status as PrdRouterStatus)) return null;
+  const validatedAt = v["validated-at"];
+  if (validatedAt !== undefined && typeof validatedAt !== "string") return null;
+  return validatedAt === undefined
+    ? { prd: v.prd, status: v.status as PrdRouterStatus }
+    : { prd: v.prd, status: v.status as PrdRouterStatus, "validated-at": validatedAt };
+}
+
+/** Parses the router file (`prd.json`); `null` on any malformed shape. */
+export function parseRouter(raw: unknown): PrdRouter | null {
+  if (!isRecord(raw)) return null;
+  const out: PrdRouter = {};
+  for (const [task, v] of Object.entries(raw)) {
+    const entry = parseRouterEntry(v);
+    if (!entry) return null;
+    out[task] = entry;
+  }
+  return out;
+}
+
+function parseSubTask(v: unknown): PrdSubTask | null {
+  if (!isRecord(v) || typeof v.status !== "string") return null;
+  if (v.status !== "assigned" && v.status !== "validated") return null;
+  const validatedAt = v["validated-at"];
+  if (validatedAt !== undefined && typeof validatedAt !== "string") return null;
+  return validatedAt === undefined ? { status: v.status } : { status: v.status, "validated-at": validatedAt };
+}
+
+function parseAgentEntry(v: unknown): PrdTaskAgentEntry | null {
+  if (!isRecord(v) || !isStringArray(v.files)) return null;
+  if (v.status === "validated") {
+    if (typeof v["validated-at"] !== "string") return null;
+    return { status: "validated", files: v.files, "validated-at": v["validated-at"] };
+  }
+  if (!isRecord(v["sub-tasks"])) return null;
+  const subTasks: Record<string, PrdSubTask> = {};
+  for (const [sub, sv] of Object.entries(v["sub-tasks"])) {
+    const parsed = parseSubTask(sv);
+    if (!parsed) return null;
+    subTasks[sub] = parsed;
+  }
+  return { files: v.files, "sub-tasks": subTasks };
+}
+
+/** Parses a task-PRD file; `null` on any malformed shape. */
+export function parseTaskFile(raw: unknown): PrdTaskFile | null {
+  if (!isRecord(raw)) return null;
+  const out: PrdTaskFile = {};
+  for (const [agent, v] of Object.entries(raw)) {
+    const entry = parseAgentEntry(v);
+    if (!entry) return null;
+    out[agent] = entry;
+  }
+  return out;
+}
+
+/** Parses an agent's own report file; `null` on any malformed shape. */
+export function parseAgentReportFile(raw: unknown): PrdAgentReportFile | null {
+  if (!isRecord(raw)) return null;
+  const out: PrdAgentReportFile = {};
+  for (const [task, subs] of Object.entries(raw)) {
+    if (!isRecord(subs)) return null;
+    const parsedSubs: Record<string, PrdAgentReportFile[string][string]> = {};
+    for (const [sub, v] of Object.entries(subs)) {
+      if (!isRecord(v) || v.status !== "done" || !isStringArray(v.modified) || !isStringArray(v.unchanged)) {
+        return null;
+      }
+      const doneAt = v["done-at"];
+      if (doneAt !== undefined && typeof doneAt !== "string") return null;
+      parsedSubs[sub] = doneAt === undefined
+        ? { status: "done", modified: v.modified, unchanged: v.unchanged }
+        : { status: "done", modified: v.modified, unchanged: v.unchanged, "done-at": doneAt };
+    }
+    out[task] = parsedSubs;
+  }
+  return out;
+}
+
+/** True when `e` is the post-compaction shape. */
+export function isCompacted(e: PrdTaskAgentEntry): e is PrdAgentEntryCompacted {
+  return "status" in e && e.status === "validated" && !("sub-tasks" in e);
+}
+
+/** Sub-tasks of an agent entry; `{}` when already compacted. */
+export function subTasksOf(e: PrdTaskAgentEntry): Record<string, PrdSubTask> {
+  return isCompacted(e) ? {} : e["sub-tasks"];
+}
+
+/** Files owned by an agent entry, expanded or compacted. */
+export function filesOf(e: PrdTaskAgentEntry): string[] {
+  return e.files;
+}
+
+/** `["needs >= 2 agents", ...]` — empty when the task PRD satisfies the contract. */
+export function validateTaskFileInvariant(taskFile: PrdTaskFile): string[] {
+  const errors: string[] = [];
+  if (Object.keys(taskFile).length < 2) errors.push("needs >= 2 agents");
+  return errors;
+}
+
+/** Returns a new router with `task`'s status (and optional `validated-at`) updated. */
+export function withRouterStatus(
+  router: PrdRouter,
+  task: string,
+  status: PrdRouterStatus,
+  at?: string,
+): PrdRouter {
+  const existing = router[task];
+  if (!existing) return router;
+  const entry: PrdRouterEntry = at === undefined
+    ? { prd: existing.prd, status }
+    : { prd: existing.prd, status, "validated-at": at };
+  return { ...router, [task]: entry };
+}
+
+/** Returns a new task-PRD file with one agent's sub-task flipped to `validated`. */
+export function withSubTaskValidated(
+  taskFile: PrdTaskFile,
+  agent: string,
+  sub: string,
+  at: string,
+): PrdTaskFile {
+  const entry = taskFile[agent];
+  if (!entry || isCompacted(entry)) return taskFile;
+  const subTask = entry["sub-tasks"][sub];
+  if (!subTask) return taskFile;
+  const nextSubTasks = { ...entry["sub-tasks"], [sub]: { status: "validated" as const, "validated-at": at } };
+  return { ...taskFile, [agent]: { files: entry.files, "sub-tasks": nextSubTasks } };
+}

package/src/runtime/handle-post.ts

@@ -14,6 +14,7 @@ import { recordCodexPostFailure } from "../tracking/codex-post-failure";
 import { defaultStateDir } from "./paths";
 import { fanOutFiles, firstFileMatch } from "./post-fanout";
 import { postOutcome } from "./post-outcome";
+import { prdPostCheck } from "./prd";
 import type { PreContext } from "./handle-pre";
 import type { HandleOutcome } from "./handle";
 
@@ -75,6 +76,7 @@ export async function handlePost(ctx: PreContext): Promise<HandleOutcome> {
   // tracking, validation, post-edit context, and notices.
   const files = fanOutFiles(event);
   for (const f of files) postTrackingSideEffects(opts.scope ?? "core", f, f.input, opts.now, payload, opts.cwd);
+  await prdPostCheck(id, event, opts.cwd, file, opts.now); // PRD cross-check — advisory only, never returns stdout
   const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
   if (seoDeny && !cursorAfterFileEdit) return { stdout: seoDeny, exit: 0 };
   if (opts.scope === "solid") {

package/src/runtime/handle-pre.ts

@@ -16,6 +16,7 @@ import { applyPatchGate } from "./apply-patch-gate";
 import { isBypassPermissions } from "../adapters/codex/permission-mode";
 import { evaluate } from "../policy/evaluate";
 import { confirmGate } from "./confirm/confirm-gate";
+import { prdPreGate } from "./prd";
 import type { HandleOptions, HandleOutcome } from "./handle";
 
 /** Context the PreToolUse pipeline needs (resolved once by {@link handleHook}). */
@@ -85,6 +86,16 @@ export async function handlePre(ctx: PreContext): Promise<HandleOutcome> {
     if (taskCtx) return { stdout: taskCtx, exit: 0 };
   }
 
+  // PRD (task/agent ownership coordination): inert unless FUSE_PRD=1 AND a
+  // router is present — see runtime/prd/prd-pre-gate.ts. Runs BEFORE the
+  // apply_patch gate below: `applyPatchGate` runs `evaluate()` per file, whose
+  // `runGuards()` already includes `protectedPathGuard` — which unconditionally
+  // blocks every `.claude/apex/` path, PRD included. A PRD write this gate just
+  // authorized must short-circuit past both `applyPatchGate` and the gate chain
+  // further down, never reach either.
+  const prdOutcome = await prdPreGate(id, payload, event, opts.cwd, file, opts.now);
+  if (prdOutcome) return prdOutcome;
+
   // Codex `apply_patch`: normalize.ts fanned the freeform patch into per-file
   // changes. OR their static verdicts — one violating hunk blocks the whole
   // envelope. `event.files` is undefined for every other tool/harness.

package/src/runtime/lifecycle/dispatch.ts

@@ -17,6 +17,10 @@ import { cartoSessionStart } from "./cartographer/session-start";
 import { dispatchLessons } from "./lessons/dispatch";
 import { withSnapshot } from "./snapshot";
 import { stopCore } from "./stop-core";
+import { prdSubagentContext, prdSubagentStopGate, prdStopGate } from "../prd";
+import { joinContextResponses } from "../../policy/prd";
+import { sanitizeSessionId } from "../home-state";
+import { defaultStateDir, trackFile } from "../paths";
 
 /** Which plugin's hooks.json invoked the harness (selects SessionStart behavior). */
 export type PluginScope = "core" | "solid" | "rules" | "carto" | "security" | "changelog" | "aipilot" | "lessons" | "seo" | "memory" | "tailwindcss";
@@ -70,11 +74,14 @@ export function dispatchLifecycle(input: LifecycleInput): string | null {
       if (input.scope === "rules") return injectRules(resolveRulesRoot(input.id ?? "claude-code", input.cwd), input.event, input.id ?? "claude-code");
       if (input.scope === "aipilot") return "";
       if (input.scope === "lessons") return dispatchLessons("SubagentStart", input.payload, input.cwd, input.now, input.id ?? "claude-code");
-      return subagentCacheContext(input.payload.session_id);
-    case "Stop":
+      return joinContextResponses(subagentCacheContext(input.payload.session_id), prdSubagentContext(input.payload, input.cwd, input.id ?? "claude-code"));
+    case "Stop": {
       if (input.scope === "lessons") return dispatchLessons("Stop", input.payload, input.cwd, input.now, input.id ?? "claude-code");
-      return input.scope === "core" ? stopCore(input.payload, input.cwd, input.now) : null;
-    case "SubagentStop":
+      if (input.scope !== "core") return null;
+      const prdBlock = prdStopGate(input.payload, input.cwd, input.id ?? "claude-code", trackFile(sanitizeSessionId(input.payload.session_id) ?? "unknown", defaultStateDir(input.cwd)), input.now);
+      return prdBlock || stopCore(input.payload, input.cwd, input.now);
+    }
+    case "SubagentStop": {
       // G0 counterpart of the SubagentStart branch above — the SAME
       // monotone max-write, never a decrement (see confirm-subagent.ts).
       markSubagentSeen(input.payload.session_id, input.now);
@@ -84,7 +91,13 @@ export function dispatchLifecycle(input: LifecycleInput): string | null {
       // explore evidence even when sidechain PostToolUse hooks never fired
       // (#43612/#27655/#34692). SubagentStop is main-session-dispatched (reliable).
       harvestSubagentTrack(input.payload, input.cwd, input.now);
-      return trackAgentMemory(input.payload, undefined, input.now);
+      // null = PRD had nothing to say (off, unnamed agent, or genuinely done)
+      // -> normal trackAgentMemory handling; a non-null string (block, or ""
+      // on an already-blocked replay) must be returned AS-IS, never layered
+      // under a stale "agent completed" message.
+      const prdBlock = prdSubagentStopGate(input.payload, input.cwd, input.id ?? "claude-code", trackFile(sanitizeSessionId(input.payload.session_id) ?? "unknown", defaultStateDir(input.cwd)), input.now);
+      return prdBlock !== null ? prdBlock : trackAgentMemory(input.payload, undefined, input.now);
+    }
     case "TeammateIdle":
       return teammateIdleContext(input.payload, input.cwd, undefined, input.now);
     case "PostToolUseFailure":

package/src/runtime/normalize.ts

@@ -33,6 +33,8 @@ export interface NormalizedEvent {
   permissionMode?: string;
   /** Codex logical tool-use identity, shared by sibling hook callbacks. */
   toolUseId?: string;
+  /** Sub-agent identifier, if the tool-use came from one (Claude/Codex only — Cursor/Kimi never send this field, confirmed live). */
+  agentId?: string;
   /** Harness-reported working directory used to scope Codex authorization. */
   cwd?: string;
   /** Validated Cursor multi-root workspace paths in wire order. */
@@ -71,6 +73,7 @@ export function normalizeEvent(id: string, payload: Record<string, unknown>): No
       ...extractCursorEvent(payload),
       sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
       agentType: str(payload.agent_type),
+      agentId: str(payload.agent_id),
       permissionMode: str(payload.permission_mode),
     };
   }
@@ -83,6 +86,7 @@ export function normalizeEvent(id: string, payload: Record<string, unknown>): No
     input,
     sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
     agentType: str(payload.agent_type) ?? str(input.subagent_type),
+    agentId: str(payload.agent_id),
     permissionMode: str(payload.permission_mode),
     toolUseId: str(payload.tool_use_id),
     cwd: str(payload.cwd),

package/src/runtime/prd/index.ts

@@ -0,0 +1,8 @@
+/** Barrel for `src/runtime/prd/**` — the runtime wiring surface (design doc §2). */
+export { prdPreGate } from "./prd-pre-gate";
+export { prdPostCheck } from "./prd-post-check";
+export { prdSubagentContext } from "./prd-subagent-context";
+export { prdSubagentStopGate } from "./prd-subagent-stop";
+export { prdStopGate } from "./prd-stop-gate";
+export { resolvePrdIdentity } from "./prd-identity";
+export { prdCandidateFiles } from "./prd-candidate-files";

package/src/runtime/prd/prd-bash-targets.ts

@@ -0,0 +1,199 @@
+/**
+ * @module prd-bash-targets
+ * Local, PRD-module-only extension of Bash write-target detection BEYOND
+ * shell output redirects (`>`/`>>`, already covered by `shellOutputRedirects`
+ * in `bash-write-redirects.ts`). Static, best-effort heuristic scanner (never
+ * executes the command) for the write-target argument of common non-redirect
+ * write verbs: `cp`, `mv`, `install` (last positional = destination), `tee`
+ * (every positional = a destination), `sed -i` / `perl -i` (in-place edit —
+ * last positional = the edited file), and `dd of=` (the `of=` operand).
+ *
+ * Deliberately NOT merged into `bash-write-redirects.ts` or
+ * `protectedPathGuard` (`protected-path.ts`) — both are shared, harness-wide
+ * guards; changing them risks a global regression. This is a narrow,
+ * PRD-scoped sibling used ONLY by `prdPreGate`'s Bash branch, feeding its
+ * output through the SAME `isPrdScopedPath` check the redirect targets
+ * already go through — so a target outside the PRD tree is never affected.
+ *
+ * Known limitation: `--` (POSIX end-of-options, GNU coreutils/glibc
+ * `getopt_long`) is honored — a positional arg starting with `-` AFTER `--`
+ * is never mistaken for an option — but `getopt_long`'s default PERMUTE mode
+ * lets a value-taking option (`install -m 644 file dest`, `cp -t DIR a b`)
+ * land anywhere in argv; this scanner doesn't track which options consume a
+ * following value, so a bare value like `644` could in principle be
+ * mistaken for the destination if it were the LAST token. Best-effort only
+ * (mirrors the existing `protectedPathGuard#extractWriteTargets`
+ * precedent): can under/mis-detect an unusual invocation, never cause a
+ * false deny on an out-of-scope path (the caller still scope-checks every
+ * returned target). Not applied to `dd`, whose `if=`/`of=` operands are
+ * never getopt-parsed (coreutils docs: "the only options are
+ * --help/--version").
+ *
+ * 2nd limitation (unfixed, flagged for owner): bundled `-i` (`perl -pi -e`,
+ * `sed -ni`) is missed — only a standalone `-i`/`-i<suffix>` token is seen.
+ */
+
+/** Chain separators this splits a command on (quote/paren-depth aware — never splits inside quotes or `$(...)`/backticks). */
+const CHAIN_CHARS = new Set([";", "&", "|", "\n"]);
+
+/** Balanced-paren scan for a `$(...)` body, quote-aware. @returns Index of the matching `)`, or `input.length` if unterminated. */
+function closingParen(input: string, start: number): number {
+  let depth = 1;
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === "(") depth++;
+    else if (ch === ")" && --depth === 0) return i;
+  }
+  return input.length;
+}
+
+/**
+ * Splits `input[start, end)` into "simple command" strings on unquoted chain
+ * separators, recursing into `$(...)`/backtick substitutions so a write verb
+ * hidden inside a subshell is still found. Bounded: every recursive call
+ * strictly narrows `[start, end)`.
+ * @param out - Accumulator for discovered simple-command strings.
+ */
+function scanCommands(input: string, start: number, end: number, out: string[]): void {
+  let cmdStart = start;
+  let quote: "'" | '"' | null = null;
+  const flush = (to: number): void => {
+    const seg = input.slice(cmdStart, to).trim();
+    if (seg) out.push(seg);
+  };
+  for (let i = start; i < end; i++) {
+    const ch = input[i];
+    if (ch === "\\" && quote !== "'") { i++; continue; }
+    // Single quotes are fully opaque (bash: NO substitution inside `'...'`).
+    // Double quotes still perform command substitution (bash: `"$(...)"` and
+    // `` "`...`" `` both still execute) — only word-splitting/globbing is
+    // suppressed — so `$(`/backtick must still be checked while `quote==='"'`.
+    if (quote === "'") { if (ch === "'") quote = null; continue; }
+    if (ch === "$" && input[i + 1] === "(") {
+      const close = closingParen(input, i + 2);
+      scanCommands(input, i + 2, close, out);
+      i = close;
+      continue;
+    }
+    if (ch === "`") {
+      const close = input.indexOf("`", i + 1);
+      const safeClose = close === -1 || close > end ? end : close;
+      scanCommands(input, i + 1, safeClose, out);
+      i = safeClose;
+      continue;
+    }
+    if (quote === '"') { if (ch === '"') quote = null; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (CHAIN_CHARS.has(ch ?? "")) {
+      flush(i);
+      cmdStart = i + 1;
+      continue;
+    }
+  }
+  flush(end);
+}
+
+/**
+ * Tokenizes one simple-command string into unquoted words (quotes unwrapped,
+ * backslash-escapes resolved outside single quotes) — same unquoting
+ * contract as `bash-write-redirects.ts`'s own `readTarget`.
+ */
+function tokenize(segment: string): string[] {
+  const tokens: string[] = [];
+  let cur = "";
+  let quote: "'" | '"' | null = null;
+  let started = false;
+  for (let i = 0; i < segment.length; i++) {
+    const ch = segment[i] ?? "";
+    if (ch === "\\" && quote !== "'") {
+      if (i + 1 < segment.length) { cur += segment[++i] ?? ""; started = true; }
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null; else cur += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; started = true; continue; }
+    if (/\s/.test(ch)) {
+      if (started) { tokens.push(cur); cur = ""; started = false; }
+      continue;
+    }
+    cur += ch;
+    started = true;
+  }
+  if (started) tokens.push(cur);
+  return tokens;
+}
+
+/** True for a short/long option token (never a bare `-`, the stdin/stdout idiom). */
+function isOption(t: string): boolean {
+  return t.startsWith("-") && t !== "-";
+}
+
+/**
+ * Positional (non-option) arguments, honoring `--` as POSIX end-of-options
+ * (see module doc): every token after a literal `--` is positional even if
+ * it starts with `-`.
+ */
+function positionalArgs(args: string[]): string[] {
+  const out: string[] = [];
+  let optionsEnded = false;
+  for (const t of args) {
+    if (!optionsEnded && t === "--") { optionsEnded = true; continue; }
+    if (!optionsEnded && isOption(t)) continue;
+    out.push(t);
+  }
+  return out;
+}
+
+/**
+ * Write-target argument(s) of one verb invocation, given its ARGUMENTS (verb
+ * token excluded). Empty when the verb isn't covered, or has no destination.
+ * @param verb - The verb basename (leading directory component stripped).
+ */
+function verbWriteTargets(verb: string, args: string[]): string[] {
+  if (verb === "dd") {
+    const of = args.find((t) => t.startsWith("of="));
+    return of ? [of.slice(3)] : [];
+  }
+  if (verb === "tee") return positionalArgs(args);
+  if (verb === "cp" || verb === "mv" || verb === "install") {
+    const p = positionalArgs(args);
+    return p.length > 0 ? [p[p.length - 1] ?? ""] : [];
+  }
+  if (verb === "sed" || verb === "perl") {
+    const inPlace = args.some((t) => t.startsWith("-i") || t === "--in-place" || t.startsWith("--in-place="));
+    if (!inPlace) return [];
+    const p = positionalArgs(args);
+    return p.length > 0 ? [p[p.length - 1] ?? ""] : [];
+  }
+  return [];
+}
+
+/**
+ * Extracts candidate write-target paths from a Bash command string, for the
+ * non-redirect write verbs this module covers (`cp`, `mv`, `install`, `tee`,
+ * `sed -i`/`perl -i`, `dd of=`). Read-only usages (a verb that never writes,
+ * or a write verb whose only in-scope path is a SOURCE argument) never
+ * contribute a target — callers still resolve/scope-check every returned
+ * path themselves (this function does no fs access, no scoping decision).
+ * @param command - The raw Bash command string.
+ * @returns Candidate write-target paths (possibly empty/duplicated).
+ */
+export function extraBashWriteTargets(command: string): string[] {
+  const segments: string[] = [];
+  scanCommands(command, 0, command.length, segments);
+  const out: string[] = [];
+  for (const seg of segments) {
+    const tokens = tokenize(seg);
+    const verbToken = tokens[0];
+    if (!verbToken) continue;
+    const verb = verbToken.split("/").pop() ?? verbToken;
+    out.push(...verbWriteTargets(verb, tokens.slice(1)));
+  }
+  return out;
+}