@fusengine/harness 0.1.91 → 0.1.93

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/handle.ts

@@ -1,10 +1,12 @@
+import { join } from "node:path";
 import { projectLayout } from "../config/layout";
 import { detectFramework } from "../policy/detect-framework";
 import { detectCreationIntent } from "../policy/creation-intent";
 import { recordBrainstormRequired } from "../tracking/session-state";
 import { withTrack } from "../tracking/store";
 import { normalizeEvent } from "./normalize";
-import { defaultStateDir, trackFile } from "./paths";
+import { defaultStateDir, projectHash, trackFile } from "./paths";
+import { fuseHarnessHome } from "./home-state";
 import { designLifecycle } from "./design-lifecycle";
 import { promptSubmitContext } from "./inject-context";
 import { lifecycleStdout } from "./lifecycle-bridge";
@@ -22,6 +24,7 @@ import { codexPromptOrigin } from "./confirm/codex-prompt-origin";
 import { cursorProjectCwd } from "../adapters/cursor/context";
 import { toCursorLifecycleResponse } from "../adapters/cursor/respond";
 import type { HandleOptions, HandleOutcome } from "./handle-types";
+import type { NormalizedEvent } from "./normalize";
 export type { HandleOptions, HandleOutcome } from "./handle-types";
 
 /** Raw Claude hook event name from a payload (empty when absent). */
@@ -29,6 +32,62 @@ function rawEventName(payload: Record<string, unknown>): string {
   return typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
 }
 
+/**
+ * `payload.tool_input` parsed into an object when it's a JSON STRING —
+ * Cursor's real wire format for `beforeMCPExecution`/`afterMCPExecution`
+ * (ground truth), unlike every other harness (and Cursor's own
+ * `preToolUse`/`postToolUse`), which always sends it as an object already.
+ * `undefined` when `tool_input` is already an object, absent, or fails to
+ * parse into one (fail-open — the caller then keeps the original value).
+ * @param payload - The raw hook payload.
+ */
+function cursorParsedToolInput(payload: Record<string, unknown>): Record<string, unknown> | undefined {
+  const raw = payload.tool_input;
+  if (typeof raw !== "string") return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `id === "cursor"` only: project the already-resolved canonical `tool_name`
+ * (`event.tool`, normalized by {@link normalizeEvent}) and `cwd` (the project
+ * root resolved via `cursorProjectCwd`, already applied to `opts.cwd`) onto a
+ * shallow payload copy — the single passage point for every downstream
+ * consumer that reads `payload.tool_name`/`payload.cwd`/`payload.tool_input`
+ * RAW instead of `event.tool`/`opts.cwd`/`event.input` (lifecycle-bridge's
+ * `failure-lesson.ts`/`agent-memory.ts`, handle-scope-async's aipilot/memory
+ * dispatchers — including `doc-cache-gate.ts`'s `libraryOf`, which never
+ * `JSON.parse`s a string `tool_input` itself — and the seo scope's
+ * `post-tool-use.ts`). `tool_input` is additionally replaced by its parsed
+ * object form via {@link cursorParsedToolInput} when Cursor sent it as a
+ * JSON string (`beforeMCPExecution`/`afterMCPExecution`). Cursor's own wire
+ * values ("Shell", `MCP:<tool>`, a bare `workspace_roots` array with no
+ * `cwd` field, a stringified `tool_input`, …) are preserved under
+ * `cursor_tool_name`/`cursor_cwd`/`cursor_tool_input` so nothing is lost.
+ * Every other harness id is untouched (returns the SAME object,
+ * byte-identical).
+ * @param payload - The raw hook payload.
+ * @param event - The already-normalized event (`event.tool` is canonical).
+ * @param cwd - The resolved project root for this invocation.
+ * @param id - Harness adapter id.
+ */
+function cursorRawPayloadProjection(payload: Record<string, unknown>, event: NormalizedEvent, cwd: string, id: string): Record<string, unknown> {
+  if (id !== "cursor") return payload;
+  const parsedToolInput = cursorParsedToolInput(payload);
+  return {
+    ...payload,
+    cursor_tool_name: payload.tool_name,
+    cursor_cwd: payload.cwd,
+    tool_name: event.tool,
+    cwd,
+    ...(parsedToolInput ? { cursor_tool_input: payload.tool_input, tool_input: parsedToolInput } : {}),
+  };
+}
+
 /**
  * The full hook handler: on a PRE event it gates the tool-use (stateless guards
  * then APEX gates from the session track) and returns the native response; on a
@@ -41,6 +100,10 @@ async function handleHookCore(id: string, payload: Record<string, unknown>, opts
     const cursorCwd = cursorProjectCwd(event.cwd, event.workspaceRoots ?? [], event.filePath, opts.cwd);
     if (cursorCwd !== opts.cwd) opts = { ...opts, cwd: cursorCwd };
   }
+  // Single passage point (see cursorRawPayloadProjection doc): every raw-payload
+  // consumer below this line gets the canonical tool_name/cwd on Cursor; every
+  // other harness id gets `payload` back untouched (byte-identical object).
+  const hookPayload = cursorRawPayloadProjection(payload, event, opts.cwd, id);
   const rawPrompt = payload.prompt;
   const userPrompt = typeof rawPrompt === "string" || Array.isArray(rawPrompt) ? promptText(rawPrompt) : undefined;
   if (id === "codex" && rawEventName(payload) === "UserPromptSubmit" && userPrompt !== undefined) {
@@ -75,11 +138,11 @@ async function handleHookCore(id: string, payload: Record<string, unknown>, opts
   if (id === "codex" && rawEventName(payload) === "SessionStart") resyncCodexAgents();
 
   // Async per-scope lifecycle (aipilot cache handlers + memory-neural Graphiti).
-  const asyncOut = await asyncScopeStdout(opts.scope, rawEventName(payload), payload, opts.cwd, opts.now, id);
+  const asyncOut = await asyncScopeStdout(opts.scope, rawEventName(payload), hookPayload, opts.cwd, opts.now, id);
   if (asyncOut !== null) return { stdout: asyncOut, exit: 0 };
 
   // Ported lifecycle/session/context hooks (SessionStart, SubagentStart/Stop, etc.).
-  const life = lifecycleStdout(payload, opts.cwd, opts.scope ?? "core", opts.now, id);
+  const life = lifecycleStdout(hookPayload, opts.cwd, opts.scope ?? "core", opts.now, id);
   if (life !== null) {
     // Claude-Code-only: attachBudgetRecap's systemMessage envelope assumes the
     // Claude adapter's stdout shape (mirrors the designLifecycle gate above).
@@ -99,18 +162,36 @@ async function handleHookCore(id: string, payload: Record<string, unknown>, opts
   }
 
   if (event.phase === "post") {
-    return handlePost({ id, payload, event, framework, mcpDir, designCacheDir, file, opts });
+    return handlePost({ id, payload: hookPayload, event, framework, mcpDir, designCacheDir, file, opts });
   }
 
-  return handlePre({ id, payload, event, framework, mcpDir, designCacheDir, file, opts });
+  return handlePre({ id, payload: hookPayload, event, framework, mcpDir, designCacheDir, file, opts });
 }
 
 /**
  * Run one hook and adapt every Cursor scope outcome at the common runtime exit.
  * Other harnesses retain the core handler's stdout and exit status unchanged.
+ * Cursor's shared `additional_context` budget context (see
+ * `../adapters/cursor/context-budget.ts`) is assembled here too — this is
+ * the single point every Cursor stdout passes through exactly once, so it's
+ * also the single point that reserves from and records into the registry.
+ * With no `session_id`/`conversation_id` at all, `sessionId` is `""` — the
+ * registry key would degenerate to one bucket shared by every session-less
+ * call on the same (cwd, event) pair, so `budget` stays `undefined` instead
+ * (falls back to the flat per-response cap in `toCursorLifecycleResponse`,
+ * with zero registry I/O). `stateDir` honors `opts.home` (test-only OS home
+ * override, see `HandleOptions`) so tests never need the real `os.homedir()`.
  */
 export async function handleHook(id: string, payload: Record<string, unknown>, opts: HandleOptions): Promise<HandleOutcome> {
   const outcome = await handleHookCore(id, payload, opts);
   if (id !== "cursor") return outcome;
-  return { ...outcome, stdout: toCursorLifecycleResponse(outcome.stdout, rawEventName(payload)) };
+  const eventName = rawEventName(payload);
+  const cursorEvent = normalizeEvent(id, payload);
+  const cwd = cursorProjectCwd(cursorEvent.cwd, cursorEvent.workspaceRoots ?? [], cursorEvent.filePath, opts.cwd);
+  const sessionId = cursorEvent.sessionId;
+  const generationId = typeof payload.generation_id === "string" && payload.generation_id ? payload.generation_id : undefined;
+  const toolUseId = typeof payload.tool_use_id === "string" && payload.tool_use_id ? payload.tool_use_id : undefined;
+  const stateDir = join(fuseHarnessHome(opts.home), "state", projectHash(cwd));
+  const budget = sessionId ? { stateDir, sessionId, event: eventName, generationId, toolUseId } : undefined;
+  return { ...outcome, stdout: toCursorLifecycleResponse(outcome.stdout, eventName, budget) };
 }

package/src/runtime/lifecycle/aipilot/dispatch-aipilot.ts

@@ -90,7 +90,13 @@ export async function dispatchAipilot(event: string, payload: Record<string, unk
   if (event === "SubagentStop") return onSubagentStop(payload, cwd, home, id);
   // Stop too: Codex emits no SessionEnd, so its ai-pilot hooks.json wires Stop here as the sole analytics-flush trigger — reusing the SessionEnd handler verbatim (codex-plugins/docs/reference/hooks.md).
   if (event === "SessionEnd" || event === "Stop") { await cacheAnalyticsSave(home, now); return ""; }
-  if (event === "PreToolUse") return docCacheGate(payload, cwd, now, home, id);
+  // "BeforeMCPExecution" is a Cursor-only lifecycle literal (produced solely
+  // by cursorEventContract in adapters/cursor/events.ts); asyncScopeStdout
+  // forwards every non-Cursor id's `hook_event_name` RAW and unvalidated, so
+  // gating on the literal alone would let a claude-code/codex payload that
+  // happens to carry this exact string reach docCacheGate — the guard must
+  // be structural (`id === "cursor"`), never event-name-only.
+  if (event === "PreToolUse" || (id === "cursor" && event === "BeforeMCPExecution")) return docCacheGate(payload, cwd, now, home, id);
   return null;
 }
 

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/lifecycle/failure-lesson.ts

@@ -5,8 +5,12 @@
  * matches the failure message — reusing the PreToolUse {@link lessonFor} index and
  * its cooldown (idempotent under the ~11-process fan-out). Fail-open throughout.
  *
- * Claude-Code-only: no equivalent `PostToolUseFailure` hook exists on Codex or
- * Hermes, so this handler is never reached through those adapters.
+ * Claude-Code-only in the sense that no equivalent `PostToolUseFailure` hook
+ * exists on Codex or Hermes — but Cursor's own `postToolUseFailure` DOES
+ * arrive here too, via `lifecycle-bridge.ts`'s `lifecycleStdout` translating
+ * the wire event name and forwarding to `dispatchLifecycle`'s
+ * `"PostToolUseFailure"` case (see `handle.ts`'s `cursorRawPayloadProjection`
+ * for how `data.tool_name` below arrives already canonicalized on Cursor).
  * @packageDocumentation
  */
 import { homedir } from "node:os";

package/src/runtime/lifecycle/rules-root.ts

@@ -2,8 +2,15 @@
  * Dynamic rules-plugin root resolution. The historical `CLAUDE_PLUGIN_ROOT ??
  * cwd` chain only worked when the harness exported the plugin root — Kimi
  * injects `KIMI_PLUGIN_ROOT` instead, and a bare cwd fallback never held a
- * `rules/` dir. Resolution order (first hit wins):
- * 1. `CLAUDE_PLUGIN_ROOT` (claude-code/codex plugin-declared hooks);
+ * `rules/` dir.
+ *
+ * `id === "cursor"` is resolved by a SEPARATE branch (`resolveCursorPluginRoot`)
+ * before any of the below, because Cursor's env contract differs from the
+ * other harnesses (see `../../adapters/cursor/plugin-root.ts`) — it is never
+ * folded into the shared switch. For every other id, resolution order (first
+ * hit wins, unchanged):
+ * 1. `CLAUDE_PLUGIN_ROOT` (read for ALL non-cursor ids, historical quirk —
+ *    frozen by non-regression tests, do not "fix" without an explicit ask);
  * 2. `KIMI_PLUGIN_ROOT` (kimi plugin-declared hooks);
  * 3. Per-harness install probe (claude marketplace, codex versioned cache,
  *    kimi managed plugins) — first `<plugin>/rules` dir whose plugin folder
@@ -14,6 +21,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { maxSemver } from "../../util/semver";
+import { resolveCursorPluginRoot } from "../../adapters/cursor/plugin-root";
 
 /** Immediate child dir names of `dir`, or [] when unreadable. */
 function children(dir: string): string[] {
@@ -72,6 +80,14 @@ export function resolveRulesRoot(
   cwd: string,
   env: Record<string, string | undefined> = process.env,
 ): string {
+  if (id === "cursor") {
+    const result = resolveCursorPluginRoot(env, cwd);
+    if (result.root) return result.root;
+    process.stderr.write(
+      `[fuse-harness] cursor: no plugin root proven (checked: ${result.checked.join("; ")}); rules root falls back to ${cwd}\n`,
+    );
+    return cwd;
+  }
   if (env.CLAUDE_PLUGIN_ROOT) return env.CLAUDE_PLUGIN_ROOT;
   if (env.KIMI_PLUGIN_ROOT) return env.KIMI_PLUGIN_ROOT;
   const home = env.HOME ?? homedir();

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";