@fusengine/harness 0.1.91 → 0.1.93

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;
+}

package/src/runtime/prd/prd-candidate-files.ts

@@ -0,0 +1,23 @@
+/**
+ * @module prd-candidate-files
+ * Shared candidate-path extraction for a hook event, used by both
+ * {@link prdPreGate} and {@link prdPostCheck} — the fanned-out
+ * `apply_patch`/`afterFileEdit` set when present, else the single
+ * `event.filePath`.
+ */
+import type { NormalizedEvent } from "../normalize";
+
+/**
+ * @param event - The normalized hook event.
+ * @param restrictToWrite - When true (PreToolUse — the default), a bare
+ * `event.filePath` only counts for `Write`/`Edit` (never a `Read`, which must
+ * stay unaffected by the ownership gate). PostToolUse call sites pass
+ * `false`: they only ever see a real Write/Edit-shaped event already.
+ * @returns The candidate file paths (possibly empty).
+ */
+export function prdCandidateFiles(event: NormalizedEvent, restrictToWrite = true): string[] {
+  if (event.files?.length) return event.files.map((f) => f.filePath);
+  if (!event.filePath) return [];
+  if (restrictToWrite && event.tool !== "Write" && event.tool !== "Edit") return [];
+  return [event.filePath];
+}

package/src/runtime/prd/prd-canon.ts

@@ -0,0 +1,50 @@
+/**
+ * @module prd-canon
+ * Best-effort symlink canonicalization for the paths `prdPreGate`/
+ * `prdPostCheck` feed into lot A's pure `isPrdScopedPath`/`classifyPrdPath`
+ * (documented "string/path compare only — no fs", by design). Those
+ * comparisons need `root` and each candidate file path on the SAME
+ * representation — but on macOS, `process.cwd()` inside a spawned process
+ * resolves `/var` to its canonical `/private/var` while a caller-constructed
+ * absolute path (e.g. from `os.tmpdir()`) may still carry the unresolved
+ * `/var` alias, so two paths naming the identical file compare unequal.
+ * Same `realpathSync.native` + raw-path-on-failure idiom already used by
+ * `adapters/cursor/context.ts`'s `cursorAbsolutePath`.
+ */
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, sep } from "node:path";
+
+/** Canonicalizes an existing directory (e.g. the project root); the raw value on failure. */
+export function canonicalRoot(root: string): string {
+  try {
+    return realpathSync.native(root);
+  } catch {
+    return root;
+  }
+}
+
+/**
+ * Canonicalizes an absolute file path that may not exist yet — including
+ * under a brand-new subdirectory (e.g. a task's FIRST `prd/docs/<task>.md`,
+ * whose `docs/` dir doesn't exist yet either): walks up from the full path,
+ * dropping one segment at a time, until an ancestor resolves, then rejoins
+ * the non-existent tail onto that canonical prefix. `root` itself always
+ * resolves (guaranteed present by `isPrdEnabled`), so this always terminates
+ * on a real answer for any path actually under the project root. A relative
+ * path is returned as-is (no `root` to anchor a symlink comparison against).
+ */
+export function canonicalFilePath(path: string): string {
+  if (!isAbsolute(path)) return path;
+  const parts = path.split(sep);
+  for (let end = parts.length; end > 0; end--) {
+    const prefix = parts.slice(0, end).join(sep) || sep;
+    try {
+      const real = realpathSync.native(prefix);
+      const tail = parts.slice(end);
+      return tail.length > 0 ? join(real, ...tail) : real;
+    } catch {
+      continue; // try a shorter, more likely to exist, ancestor
+    }
+  }
+  return path;
+}

package/src/runtime/prd/prd-identity.ts

@@ -0,0 +1,32 @@
+/**
+ * @module prd-identity
+ * Resolve a {@link PrdIdentity} from a normalized hook event. Structural, not
+ * field-presence-based: Cursor and Kimi NEVER carry `agent_id`/`agent_type` on
+ * a sub-agent's own tool-use (live-captured — see the PRD design doc Risks
+ * §1/§2), so on those two targets the absence of `agentId` is NOT evidence of
+ * being the lead — it is a harness ceiling, and the verdict must stay
+ * `"unknown"` (advisory, never a hard block) regardless of what the payload
+ * carries. Every other target (claude-code, codex, and any future harness
+ * sharing their schema) DOES carry `agent_id` on a real sub-agent call, so
+ * there `agentId`'s absence structurally proves "this is the lead".
+ */
+import type { NormalizedEvent } from "../normalize";
+import type { PrdIdentity } from "../../policy/prd/interfaces/types";
+
+/** Harness targets whose payloads never carry per-event agent identity (live-confirmed for Cursor; documented schema for Kimi — design doc Risks §1/§2). */
+const NO_IDENTITY_SUPPORT: ReadonlySet<string> = new Set(["cursor", "kimi"]);
+
+/**
+ * Resolve the PRD identity of the current tool-use.
+ * @param id - Harness target id (e.g. "claude-code", "codex", "cursor", "kimi").
+ * @param event - The normalized hook event (reads `agentId`/`agentType`).
+ * @returns The resolved {@link PrdIdentity} — `lead: "unknown"` on Cursor/Kimi,
+ * `lead: true` when no `agentId` is present elsewhere, `lead: false` (with
+ * whatever `agentType` came along, possibly undefined — see design Risks §4)
+ * otherwise.
+ */
+export function resolvePrdIdentity(id: string, event: NormalizedEvent): PrdIdentity {
+  if (NO_IDENTITY_SUPPORT.has(id)) return { lead: "unknown", agentId: event.agentId, agentType: event.agentType };
+  if (!event.agentId) return { lead: true };
+  return { lead: false, agentId: event.agentId, agentType: event.agentType };
+}

package/src/runtime/prd/prd-post-check.ts

@@ -0,0 +1,73 @@
+/**
+ * @module prd-post-check
+ * PostToolUse cross-check (design doc §2.2). Side-effect only — never
+ * produces stdout. Fires only when the touched path just resolved to a
+ * task-PRD or the router (the only two places a `validated` status is
+ * asserted), reloads every named agent's own report, and journals any NEW
+ * cross-check violation (deduped by `{task,agent,sub,reason}` so a repeated
+ * PostToolUse on the same file never re-appends the same finding).
+ */
+import { hashText } from "../../util/json-io";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import {
+  classifyPrdPath, crossCheckTask, isPrdEnabled, prdProjectRoot,
+  readAgentReport, readRouter, readTaskFile,
+  type PrdAgentReportFile, type PrdCrossCheckViolation,
+} from "../../policy/prd";
+import { withTrack } from "../../tracking/store";
+import { recordPrdViolation } from "../../tracking/session-state";
+import { prdCandidateFiles } from "./prd-candidate-files";
+import { canonicalFilePath, canonicalRoot } from "./prd-canon";
+import type { NormalizedEvent } from "../normalize";
+
+/** Stable dedup key for one violation, shared across replays of the same PostToolUse. */
+function violationKey(v: PrdCrossCheckViolation): string {
+  return hashText(JSON.stringify([v.task, v.agent, v.sub, v.reason]));
+}
+
+/**
+ * Run the PRD PostToolUse cross-check. Side-effect only — journals new
+ * violations, never returns anything to render.
+ */
+export async function prdPostCheck(id: string, event: NormalizedEvent, cwd: string, trackFilePath: string, now: number): Promise<void> {
+  if (!isPrdEnabled(cwd, id)) return;
+  const root = canonicalRoot(prdProjectRoot(cwd)); // see prd-canon.ts — same representation as the candidate file paths below
+  const homeSeg = harnessHomeSegment(id);
+  const router = await readRouter(root, homeSeg);
+  if (!router) return;
+
+  const files = prdCandidateFiles(event, false).map(canonicalFilePath);
+  const touchedTasks = new Set<string>();
+  for (const f of files) {
+    const kind = classifyPrdPath(f, root, homeSeg, router);
+    if (kind?.kind === "task") touchedTasks.add(kind.task);
+    else if (kind?.kind === "router") for (const task of Object.keys(router)) touchedTasks.add(task);
+  }
+  if (touchedTasks.size === 0) return;
+
+  const violations: PrdCrossCheckViolation[] = [];
+  for (const task of touchedTasks) {
+    const entry = router[task];
+    if (!entry) continue;
+    const taskFile = await readTaskFile(root, homeSeg, entry.prd);
+    if (!taskFile) continue;
+    const reports: Record<string, PrdAgentReportFile> = {};
+    for (const agent of Object.keys(taskFile)) {
+      const report = await readAgentReport(root, homeSeg, agent);
+      if (report) reports[agent] = report;
+    }
+    violations.push(...crossCheckTask(taskFile, reports, task));
+  }
+  if (violations.length === 0) return;
+
+  await withTrack(trackFilePath, (t) => {
+    const known = new Set((t.prdViolations ?? []).map(violationKey));
+    let next = t;
+    for (const v of violations) {
+      if (known.has(violationKey(v))) continue;
+      known.add(violationKey(v));
+      next = recordPrdViolation(next, { ...v, ts: now });
+    }
+    return next;
+  });
+}

package/src/runtime/prd/prd-pre-gate.ts

@@ -0,0 +1,172 @@
+/**
+ * @module prd-pre-gate
+ * PreToolUse orchestrator for the PRD module (design doc §2.0/§2.1). Inert
+ * unless {@link isPrdEnabled}: one env read + one `statSync`, zero further
+ * disk access. When active, denies a Bash write under `apex/prd/` for
+ * EVERYONE (no identity check needed — see below) — covering both shell
+ * output redirects (`>`/`>>`, `shellOutputRedirects`) AND the non-redirect
+ * write verbs `cp`, `mv`, `tee`, `sed -i`/`perl -i`, `install`, `dd of=`
+ * (`extraBashWriteTargets`, `prd-bash-targets.ts`) — then resolves ownership
+ * for Write/Edit/apply_patch/afterFileEdit targets and either short-circuits
+ * past `gate()`/`protectedPathGuard` with an allow, or returns the standard
+ * deny — never both, never a silent pass-through of a denied write.
+ */
+import { dirname } from "node:path";
+import type { Prompt } from "../../prompt/types";
+import { respond } from "../respond";
+import { withDenyNotice } from "../deny-notice";
+import { allowOutcome } from "../pre-allow";
+import { projectLayout } from "../../config/layout";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import { shellOutputRedirects } from "../../policy/guards/bash-write-redirects";
+import { extraBashWriteTargets } from "./prd-bash-targets";
+import {
+  candidateAgentNames, classifyPrdPath, evaluateWriteOwnership, isPrdEnabled, isPrdScopedPath,
+  prdProjectRoot, readAllTaskFiles, readRouter,
+  type PrdOwnershipVerdict, type PrdPathKind, type PrdTaskFile,
+} from "../../policy/prd";
+import { loadTrack, withTrack } from "../../tracking/store";
+import { recordPrdOwner } from "../../tracking/session-state";
+import { resolvePrdIdentity } from "./prd-identity";
+import { prdCandidateFiles } from "./prd-candidate-files";
+import { canonicalFilePath, canonicalRoot } from "./prd-canon";
+import type { NormalizedEvent } from "../normalize";
+import type { HandleOutcome } from "../handle";
+
+const ACTIONS = ["Write only the files/report this agent owns per its PRD slice", "Run `harness prd status` to see the current assignment"];
+
+function denyOutcome(id: string, event: NormalizedEvent, trackFilePath: string, now: number, reason: string): HandleOutcome {
+  const prompt: Prompt = { kind: "block", ruleId: "prd-ownership", title: "PRD ownership", reason, actions: ACTIONS };
+  return { stdout: withDenyNotice(id, respond(id, prompt, event.eventName ?? "PreToolUse"), prompt, event.sessionId, dirname(trackFilePath), now), exit: 0 };
+}
+
+/**
+ * Narrows `taskFile` to the names `evaluateWriteOwnership` needs to correctly
+ * resolve a SPECIFIC requested agent-report name, WITHOUT changing lot A's
+ * pure `resolveOwnerBinding`/`evaluateWriteOwnership` (unmodified) — a lot B
+ * integration adapter around a real call-site gap, not a policy change.
+ *
+ * Two rules, matching the design's "first-come, exact-name-first" contract:
+ * - `target === agentType` (claiming YOUR OWN exact name): always legitimate
+ *   on a cold start — narrow to just `target`, so a same-type SIBLING's mere
+ *   existence never manufactures a false "ambiguous" (`resolveOwnerBinding`
+ *   otherwise sees 2 equally-free candidates and gives up for BOTH).
+ * - `target !== agentType` (claiming a "-n" SIBLING slot): only legitimate
+ *   once the EXACT-match name is already claimed by someone else — keep
+ *   BOTH names, so `resolveOwnerBinding` sees 2 free candidates (denied,
+ *   ambiguous) until the exact slot is taken, then exactly 1 (allowed).
+ * In every case, this agentId's own EXISTING binding (if any) and every
+ * name already claimed by anyone are also kept, so a mismatch against an
+ * established binding is still caught (never silently dropped from view).
+ */
+function narrowForTarget(taskFile: PrdTaskFile, agentType: string, target: string, agentId: string, bindings: Record<string, string>): PrdTaskFile {
+  const allCandidates = candidateAgentNames(agentType, taskFile);
+  const keep = new Set<string>([target]);
+  if (target !== agentType) keep.add(agentType);
+  const myBinding = bindings[agentId];
+  if (myBinding !== undefined) keep.add(myBinding);
+  for (const name of Object.values(bindings)) keep.add(name);
+  const out: PrdTaskFile = {};
+  for (const name of allCandidates) {
+    const entry = taskFile[name];
+    if (keep.has(name) && entry) out[name] = entry;
+  }
+  return out;
+}
+
+/** The task-PRD (if any) that declares `agent` as a literal key, across every task in the router. */
+function governingTaskFile(agent: string, taskFiles: Record<string, PrdTaskFile | null>): PrdTaskFile | null {
+  for (const tf of Object.values(taskFiles)) {
+    if (tf && Object.hasOwn(tf, agent)) return tf;
+  }
+  return null;
+}
+
+/**
+ * Run the PreToolUse PRD gate.
+ * @returns The native outcome (allow bypassing `gate()`, or deny), or `null`
+ * to fall through to the ordinary pipeline (module off, or nothing in scope).
+ */
+export async function prdPreGate(
+  id: string,
+  payload: Record<string, unknown>,
+  event: NormalizedEvent,
+  cwd: string,
+  trackFilePath: string,
+  now: number,
+): Promise<HandleOutcome | null> {
+  if (!isPrdEnabled(cwd, id)) return null;
+  // Canonicalized once: `isPrdScopedPath`/`classifyPrdPath` are pure
+  // string/path compares (lot A, by design, no fs) — on macOS, `cwd` (from a
+  // spawned process) resolves `/var` to `/private/var` while a caller's own
+  // absolute path may still carry the unresolved alias, so root and target
+  // must share ONE representation before any comparison (prd-canon.ts).
+  const root = canonicalRoot(prdProjectRoot(cwd));
+  const homeSeg = harnessHomeSegment(id);
+
+  if (event.tool === "Bash" && event.command) {
+    const redirectHit = shellOutputRedirects(event.command).some((r) => isPrdScopedPath(canonicalFilePath(r.target), root, homeSeg));
+    // Beyond `>`/`>>` redirects: cp/mv/tee/sed -i/perl -i/install/dd of= also
+    // write a file without any redirect operator (prd-bash-targets.ts, local
+    // to this module — never merged into the shared bash-write-redirects.ts/
+    // protectedPathGuard, see that file's own header for why).
+    const verbHit = extraBashWriteTargets(event.command).some((t) => isPrdScopedPath(canonicalFilePath(t), root, homeSeg));
+    if (redirectHit || verbHit) return denyOutcome(id, event, trackFilePath, now, "PRD files must be written via Write/Edit/apply_patch, never Bash.");
+  }
+
+  const files = prdCandidateFiles(event).map(canonicalFilePath);
+  if (files.length === 0) return null;
+
+  const router = await readRouter(root, homeSeg);
+  if (router === null) {
+    if (!files.some((f) => isPrdScopedPath(f, root, homeSeg))) return null;
+    return denyOutcome(id, event, trackFilePath, now, "PRD router is malformed JSON — fix apex/prd.json or unset FUSE_PRD.");
+  }
+
+  const inScope = files
+    .map((f) => ({ file: f, kind: classifyPrdPath(f, root, homeSeg, router) }))
+    .filter((c): c is { file: string; kind: PrdPathKind } => c.kind !== null && c.kind.kind !== "other");
+  if (inScope.length === 0) return null;
+
+  const identity = resolvePrdIdentity(id, event);
+  const track = await loadTrack(trackFilePath);
+  // Mutated in-loop (never the loaded track): a 2nd agent-report file in the
+  // SAME envelope must see the 1st file's pending bind, or a single agentId
+  // could claim two different agent names in one apply_patch batch (each
+  // looks free in isolation otherwise).
+  let bindings = { ...(track.prdOwners ?? {}) };
+  const taskFiles = inScope.some((c) => c.kind.kind === "agentReport") ? await readAllTaskFiles(root, homeSeg, router) : {};
+
+  const binds: { agentId: string; name: string }[] = [];
+  for (const { file, kind } of inScope) {
+    let taskFile: PrdTaskFile | null = null;
+    if (kind.kind === "agentReport") {
+      const governing = governingTaskFile(kind.agent, taskFiles);
+      taskFile = governing && identity.agentType !== undefined && identity.agentId !== undefined
+        ? narrowForTarget(governing, identity.agentType, kind.agent, identity.agentId, bindings)
+        : governing;
+    }
+    const verdict: PrdOwnershipVerdict = evaluateWriteOwnership({ kind, identity, taskFile, bindings });
+    if (verdict.allow === false) return denyOutcome(id, event, trackFilePath, now, `${file}: ${verdict.reason}`);
+    if (verdict.allow === true && verdict.bind) {
+      binds.push(verdict.bind);
+      bindings = { ...bindings, [verdict.bind.agentId]: verdict.bind.name };
+    }
+  }
+
+  // A mixed envelope (some candidate files never classified in-scope by
+  // classifyPrdPath, e.g. a genuinely unrelated file bundled into the SAME
+  // apply_patch) must never ride THIS allow past applyPatchGate/gate() for
+  // those other files — only a PURE-PRD envelope (every candidate file
+  // in-scope) may short-circuit. A denial above (ownership violation on an
+  // in-scope file) still fires regardless of mixing; only the ALLOW path is
+  // restricted here, so it never becomes a silent bypass for an unclassified
+  // file the PRD gate was never meant to authorize.
+  if (inScope.length !== files.length) return null;
+
+  if (binds.length > 0) {
+    await withTrack(trackFilePath, (t) => binds.reduce((acc, b) => recordPrdOwner(acc, b.agentId, b.name), t));
+  }
+  const mcpDir = projectLayout(cwd).cacheDir;
+  return allowOutcome(id, event, payload, mcpDir, cwd, { trackFile: trackFilePath, now });
+}

package/src/runtime/prd/prd-stop-gate.ts

@@ -0,0 +1,101 @@
+/**
+ * @module prd-stop-gate
+ * Block-once gate for the LEAD's `Stop` event when the router carries an
+ * unresolved PRD cross-check violation (design doc §2.5). SYNC, same
+ * one-shot idiom as {@link prdSubagentStopGate}, keyed `sessionId:Stop`
+ * instead of per-agent. Covers Codex too — its `Stop` already routes to
+ * `stopCore` under `scope === "core"`.
+ */
+import { dirname } from "node:path";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import {
+  hasAnyViolations, isPrdEnabled, prdProjectRoot, readRouterSync, readTaskFileSync,
+  type PrdRouter, type PrdTaskFile,
+} from "../../policy/prd";
+import { journalLogPath, readTrackSync } from "../../tracking/track-compact";
+import { trackJournalEnabled } from "../../tracking/store";
+import { appendEvent } from "../../tracking/track-journal";
+import { diffTrackEvents } from "../../tracking/track-diff";
+import { prdAlreadyBlocked, recordPrdStopBlocked, type SessionTrack } from "../../tracking/session-state";
+import { signTrack, writeLastNonce } from "../../tracking/integrity";
+import { withTrackLockSync } from "../../tracking/track-lock-sync";
+import { atomicWrite } from "../../util/json-io";
+import { blockResponse } from "../../adapters/claude";
+import { respond } from "../respond";
+
+const REASON = "PRD cross-check found unresolved violation(s): a task/sub-task is marked validated without a matching done report. Run `harness prd status` for details.";
+
+/** Sync twin of `readAllTaskFiles` (lot A only exposes the async variant). */
+function readAllTaskFilesSync(root: string, homeSeg: string, router: PrdRouter): Record<string, PrdTaskFile | null> {
+  const out: Record<string, PrdTaskFile | null> = {};
+  for (const [task, entry] of Object.entries(router)) out[task] = readTaskFileSync(root, homeSeg, entry.prd);
+  return out;
+}
+
+/**
+ * Persist the one-shot block marker on the SAME side `trackJournalEnabled()`
+ * reads from. Twin of `prd-subagent-stop.ts`'s own `persistStopBlocked`
+ * (intentionally duplicated, not cross-imported — same SOLID file-size
+ * discipline as this module's other duplicated helpers, e.g.
+ * `readAllTaskFilesSync`). Bug this fixes: the old code always appended to
+ * the journal regardless of mode, but `readTrackSync(file,
+ * trackJournalEnabled())` never folds the log when `FUSE_TRACK_JOURNAL=0`
+ * (track-compact.ts) — so a legacy replay never saw the marker and
+ * re-blocked the lead's Stop on every call.
+ */
+function persistStopBlocked(trackFilePath: string, track: SessionTrack, key: string, now: number): void {
+  if (trackJournalEnabled()) {
+    const next = recordPrdStopBlocked(track, key, now);
+    for (const ev of diffTrackEvents(track, next, now)) appendEvent(journalLogPath(trackFilePath), ev.field, ev.op, ev.value, ev.ts);
+    return;
+  }
+  withTrackLockSync(dirname(trackFilePath), () => {
+    const fresh = readTrackSync(trackFilePath, false); // reload under lock: avoid clobbering a concurrent legacy RMW
+    const envelope = signTrack(recordPrdStopBlocked(fresh, key, now));
+    atomicWrite(trackFilePath, JSON.stringify(envelope, null, 2));
+    writeLastNonce(envelope.nonce);
+  });
+}
+
+/**
+ * Run the PRD lead-Stop block-once gate.
+ * @param payload - The raw Stop hook payload.
+ * @param cwd - Project root.
+ * @param id - Harness target id.
+ * @param trackFilePath - The session track file path.
+ * @param now - Event clock.
+ * @returns The native block stdout (once per session), else `""`.
+ */
+export function prdStopGate(payload: Record<string, unknown>, cwd: string, id: string, trackFilePath: string, now: number): string {
+  if (!isPrdEnabled(cwd, id)) return "";
+  if (id === "cursor") return ""; // `stop` is Cursor's terminal observation event, not gated today (design doc §5 table).
+  const root = prdProjectRoot(cwd);
+  const homeSeg = harnessHomeSegment(id);
+  const router = readRouterSync(root, homeSeg);
+  if (!router) return "";
+  const track = readTrackSync(trackFilePath, trackJournalEnabled());
+  // Two independent violation sources, per the design doc: (a) unresolved
+  // `prdViolations` already journaled by the PostToolUse cross-check
+  // (§2.2 — `hasAnyViolations` has no track access, so THIS is that half),
+  // (b) `hasAnyViolations` itself — a router entry marked `validated` whose
+  // task-PRD isn't actually fully validated.
+  const trackHasViolations = (track.prdViolations?.length ?? 0) > 0;
+  if (!trackHasViolations) {
+    const taskFiles = readAllTaskFilesSync(root, homeSeg, router);
+    if (!hasAnyViolations(router, taskFiles)) return "";
+  }
+
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+  const key = `${sessionId}:Stop`;
+  if (prdAlreadyBlocked(track, key)) return "";
+  persistStopBlocked(trackFilePath, track, key, now);
+
+  // gemini-cli/cline: route through respond() for their own native block
+  // envelope (see prd-subagent-stop.ts's identical routing comment for the
+  // full rationale — claude-code/codex/hermes stay on blockResponse
+  // unchanged, respond() cannot reproduce their byte-identical shape here).
+  if (id === "kimi" || id === "gemini-cli" || id === "cline") {
+    return respond(id, { kind: "block", title: "PRD cross-check", reason: REASON }, "Stop");
+  }
+  return blockResponse(REASON);
+}