@fusengine/harness 0.1.91 → 0.1.93

package/src/runtime/prd/prd-subagent-context.ts

@@ -0,0 +1,69 @@
+/**
+ * @module prd-subagent-context
+ * SubagentStart injection (design doc §2.3) — the sub-agent's own PRD slice,
+ * never the whole task. Kept SYNCHRONOUS on purpose: `dispatchLifecycle` is
+ * called synchronously (no `await`) from `lifecycle-bridge.ts`/`handle.ts`,
+ * and making that chain async for one new injector would touch 3 unrelated
+ * files purely for signature plumbing — `prd-io.ts`'s sync twins
+ * (`readRouterSync`/`readTaskFileSync`) exist precisely so this call site
+ * needs zero signature changes anywhere else.
+ */
+import { contextResponse } from "../../adapters/claude";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import {
+  agentSlices, isPrdEnabled, prdProjectRoot, readRouterSync, readTaskFileSync, renderAgentSliceMarkdown,
+  type PrdSubagentSlice,
+} from "../../policy/prd";
+import { respond } from "../respond";
+
+/** Compliance reminder appended after the rendered slice(s) — the 3 rules a sub-agent must keep in mind. */
+const RULES = [
+  "1. Write ONLY the files listed in your slice above.",
+  "2. Report completion to YOUR OWN agent-report file above — never another agent's.",
+  "3. Do not mark a sub-task done until the work is actually finished; the coordinator validates from your report.",
+].join("\n");
+
+/** `agent_type`, same fallback `dispatch-aipilot.ts`'s `agentTypeOf` uses (duplicated here per SOLID file-size discipline, not cross-imported). */
+function agentTypeOf(payload: Record<string, unknown>): string {
+  return String(payload.agent_type ?? payload.subagent_type ?? "");
+}
+
+/**
+ * Build the SubagentStart PRD context injection for this agent, or `""` when
+ * the module is off, the caller is unnamed, or nothing in the router
+ * concerns it.
+ * @param payload - The raw SubagentStart hook payload.
+ * @param cwd - Project root.
+ * @param id - Harness target id.
+ * @returns The native `additionalContext` hook stdout, or `""`.
+ */
+export function prdSubagentContext(payload: Record<string, unknown>, cwd: string, id: string): string {
+  if (!isPrdEnabled(cwd, id)) return "";
+  const agentType = agentTypeOf(payload);
+  if (!agentType) return "";
+  const root = prdProjectRoot(cwd);
+  const homeSeg = harnessHomeSegment(id);
+  const router = readRouterSync(root, homeSeg);
+  if (!router) return "";
+
+  const slices: PrdSubagentSlice[] = [];
+  for (const [task, entry] of Object.entries(router)) {
+    const taskFile = readTaskFileSync(root, homeSeg, entry.prd);
+    if (!taskFile) continue;
+    slices.push(...agentSlices(taskFile, agentType, task));
+  }
+  if (slices.length === 0) return "";
+
+  const text = `${renderAgentSliceMarkdown(slices)}\n\n### Rules\n${RULES}`;
+  // gemini-cli/cline don't understand Claude's hookSpecificOutput.additionalContext
+  // envelope: gemini-cli's native shape has no hookEventName field and cline's
+  // is `{contextModification}` entirely — route them through respond()'s
+  // already-correct "inform" branches. claude-code/codex/kimi/cursor/hermes
+  // stay on contextResponse unchanged: respond()'s "inform" kind re-wraps the
+  // text through formatPrompt (adds a "[NOTE] title" line), which would NOT
+  // reproduce today's byte-identical raw-markdown output.
+  if (id === "gemini-cli" || id === "cline") {
+    return respond(id, { kind: "inform", title: "PRD assignment", reason: text }, "SubagentStart");
+  }
+  return contextResponse("SubagentStart", text);
+}

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

@@ -0,0 +1,152 @@
+/**
+ * @module prd-subagent-stop
+ * Block-once gate for a finishing sub-agent with incomplete PRD sub-tasks
+ * (design doc §2.4). SYNC on purpose — the SubagentStop dispatch runs
+ * synchronously in a short-lived hook process; an async write could be
+ * dropped before exit (same reasoning as `track-lock-sync.ts`).
+ */
+import { dirname } from "node:path";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import {
+  candidateAgentNames, incompleteSubTasks, isPrdEnabled, prdProjectRoot,
+  readAgentReportSync, readRouterSync, readTaskFileSync, 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";
+
+/** `agent_type`, same fallback duplicated across the PRD runtime modules (SOLID file-size discipline). */
+function agentTypeOf(payload: Record<string, unknown>): string {
+  return String(payload.agent_type ?? payload.subagent_type ?? "");
+}
+
+/** Renders the block reason for one finishing agent's incomplete sub-tasks. */
+function reasonFor(agent: string, task: string, subs: string[]): string {
+  return `PRD sub-task(s) not done for ${agent} on task "${task}": ${subs.join(", ")}. Finish the work (or ask the coordinator to reassign) before stopping.`;
+}
+
+/**
+ * One-shot key for this finishing instance. Keyed by `agentId` when known —
+ * the STABLE identity of "this specific sub-agent call", regardless of which
+ * same-`agentType` candidate name it happens to match — so an unbound agent
+ * (no prior Write) whose incompleteness is first found under one sibling
+ * name doesn't get blocked a SECOND time on replay under the other sibling
+ * name (both unbound candidates are checked every call; only the key must
+ * stay identical). Falls back to per-name keying when `agentId` is absent
+ * (Kimi-shaped payloads structurally never carry it).
+ */
+function stopKey(sessionId: string, agentId: string | undefined, agent: string): string {
+  return agentId !== undefined ? `${sessionId}:SubagentStop:agent:${agentId}` : `${sessionId}:SubagentStop:${agent}`;
+}
+
+/**
+ * Narrows the agentType-matching candidates to the ONE this specific
+ * `agent_id` is already bound to (per `prdOwners`), when known — otherwise
+ * every same-`agentType` sibling would be checked (and could block THIS
+ * instance for a SIBLING's incomplete work, e.g. `backend-expert` vs
+ * `backend-expert-2` sharing the same reported `agent_type`). Unbound (the
+ * agent hasn't written anything yet) falls back to checking every candidate,
+ * the only defensible default with no binding to disambiguate on.
+ */
+function resolveCandidates(agentType: string, taskFile: PrdTaskFile, agentId: string | undefined, bindings: Record<string, string>): string[] {
+  const all = candidateAgentNames(agentType, taskFile);
+  const bound = agentId !== undefined ? bindings[agentId] : undefined;
+  return bound !== undefined && all.includes(bound) ? [bound] : all;
+}
+
+/**
+ * Persist the one-shot block marker on the SAME side `trackJournalEnabled()`
+ * reads from — mirrors `harvestSubagentTrack`'s branching (`evidence-harvest-
+ * io.ts`), the codebase's only other sync lifecycle writer with this exact
+ * constraint. 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 on every call. Journal mode
+ * (default): unchanged, append the diff. Legacy mode: locked read-modify-
+ * write straight into the snapshot (`signTrack` + atomic write + nonce, same
+ * body as `store.ts#saveTrack`'s legacy branch), so the very next
+ * `readTrackSync(file, false)` sees it.
+ */
+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 SubagentStop block-once gate.
+ * @param payload - The raw SubagentStop hook payload.
+ * @param cwd - Project root.
+ * @param id - Harness target id.
+ * @param trackFilePath - The session track file path.
+ * @param now - Event clock.
+ * @returns `null` when PRD had nothing to say (module off, unnamed agent, or
+ * every assigned sub-task is genuinely done) — the caller falls through to
+ * its normal SubagentStop handling (e.g. `trackAgentMemory`). A non-null
+ * string means PRD DID find an incomplete sub-task for this agent: the
+ * block stdout the first time, or `""` on every later replay of the SAME
+ * incompleteness (already-blocked-once) — either way the caller must return
+ * it AS-IS and skip its normal handling (a stale "agent completed" message
+ * would contradict the block that was just — or already — issued).
+ */
+export function prdSubagentStopGate(payload: Record<string, unknown>, cwd: string, id: string, trackFilePath: string, now: number): string | null {
+  if (!isPrdEnabled(cwd, id)) return null;
+  // Cursor's sub-agent identity is structurally unlinkable at this event
+  // (design doc Risks §1) and Cursor never honors a block on SubagentStop
+  // anyway (adapters.md) — never even build a block payload for it.
+  if (id === "cursor") return null;
+  const agentType = agentTypeOf(payload);
+  if (!agentType) return null;
+  const agentId = typeof payload.agent_id === "string" ? payload.agent_id : undefined;
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+  const root = prdProjectRoot(cwd);
+  const homeSeg = harnessHomeSegment(id);
+  const router = readRouterSync(root, homeSeg);
+  if (!router) return null;
+  const track = readTrackSync(trackFilePath, trackJournalEnabled());
+  const bindings = track.prdOwners ?? {};
+
+  for (const [task, entry] of Object.entries(router)) {
+    const taskFile = readTaskFileSync(root, homeSeg, entry.prd);
+    if (!taskFile) continue;
+    for (const agent of resolveCandidates(agentType, taskFile, agentId, bindings)) {
+      const report = readAgentReportSync(root, homeSeg, agent);
+      const incomplete = incompleteSubTasks(taskFile, agent, task, report);
+      if (incomplete.length === 0) continue;
+      const key = stopKey(sessionId, agentId, agent);
+      if (prdAlreadyBlocked(track, key)) return ""; // already blocked once — silent, but still skip trackAgentMemory
+      persistStopBlocked(trackFilePath, track, key, now);
+      const reason = reasonFor(agent, task, incomplete);
+      // gemini-cli/cline have their OWN native block envelopes (respond()
+      // already knows them: `{decision:"deny"}` / `{cancel:true}`) — the old
+      // hardcoded `blockResponse` sent them the Claude `{decision:"block"}`
+      // shape, which neither honors. claude-code/codex/hermes stay on
+      // `blockResponse` unchanged: `respond()`'s claude-code/codex branch
+      // always calls `denyResponse` (a PreToolUse-only `permissionDecision`,
+      // ignored on Stop-family events — see `blockResponse`'s own doc
+      // comment), and hermes's `toHermesResponse` re-wraps the reason through
+      // `formatPrompt` (adds a "[BLOCKED] title" line) — neither reproduces
+      // today's byte-identical `{decision:"block",reason}`.
+      if (id === "kimi" || id === "gemini-cli" || id === "cline") {
+        return respond(id, { kind: "block", title: "PRD sub-task incomplete", reason }, "SubagentStop");
+      }
+      return blockResponse(reason);
+    }
+  }
+  return null;
+}

package/src/tracking/session-state.ts

@@ -25,7 +25,25 @@ export interface SessionTrack {
   brainstormRequired?: boolean;
   /** Verification receipts (tsc/test) at PostToolUse; absent/empty reads as unverified in the TaskCompleted gate (backward compat, fail-closed). See {@link Receipt}. */
   receipts?: Receipt[];
+  /** PRD (task/agent ownership coordination) — `agent_id` bound to its resolved agent-report name. Optional: absent on any track predating the PRD module (backward compat). */
+  prdOwners?: Record<string, string>;
+  /** PRD cross-check violations detected at PostToolUse (capped, append-only). */
+  prdViolations?: PrdViolationRecord[];
+  /** PRD SubagentStop/Stop one-shot block markers, keyed `"sessionId:event[:agent]"` -> the epoch-ms the block fired. */
+  prdStopBlocked?: Record<string, number>;
 }
+
+/** One PRD cross-check violation, timestamped for the journal/dedup. */
+export interface PrdViolationRecord {
+  ts: number;
+  task: string;
+  agent: string;
+  sub: string;
+  reason: string;
+}
+
+/** Cap on {@link SessionTrack.prdViolations} (mirrors the `receipts` style bound — oldest evicted first). */
+export const PRD_VIOLATIONS_CAP = 50;
 /** A fresh, empty track. */
 export function emptyTrack(): SessionTrack {
   return { authorizations: {}, refsRead: [], agents: [], trivialEdits: [] };
@@ -92,3 +110,31 @@ export function trivialCount(track: SessionTrack, windowMs: number, now: number)
 export function recordBrainstormRequired(track: SessionTrack, required: boolean): SessionTrack {
   return { ...track, brainstormRequired: required };
 }
+
+/** Bind `agentId` to its resolved PRD agent-report `name` (merge; idempotent no-op if already bound to the same name). Immutable. */
+export function recordPrdOwner(track: SessionTrack, agentId: string, name: string): SessionTrack {
+  if (track.prdOwners?.[agentId] === name) return track;
+  return { ...track, prdOwners: { ...track.prdOwners, [agentId]: name } };
+}
+
+/**
+ * Append one PRD cross-check violation. Immutable, uncapped in the mutator
+ * itself — same append-only shape as {@link Receipt} — so the journal diff's
+ * prefix comparison (`tail`, track-diff.ts) never sees an eviction it would
+ * mistake for a bulk rewrite. The {@link PRD_VIOLATIONS_CAP} bound is applied
+ * only when the journal is folded/read (track-journal.ts's `foldEvents`),
+ * mirroring how `trivialEdits`'s sliding window is re-derived at fold time.
+ */
+export function recordPrdViolation(track: SessionTrack, v: PrdViolationRecord): SessionTrack {
+  return { ...track, prdViolations: [...(track.prdViolations ?? []), v] };
+}
+
+/** Record a PRD SubagentStop/Stop one-shot block marker (merge). Immutable. */
+export function recordPrdStopBlocked(track: SessionTrack, key: string, ts: number): SessionTrack {
+  return { ...track, prdStopBlocked: { ...track.prdStopBlocked, [key]: ts } };
+}
+
+/** True when the PRD one-shot block for `key` has already fired. */
+export function prdAlreadyBlocked(track: SessionTrack, key: string): boolean {
+  return track.prdStopBlocked?.[key] !== undefined;
+}

package/src/tracking/track-diff.ts

@@ -46,5 +46,8 @@ export function diffTrackEvents(prev: SessionTrack, next: SessionTrack, now: num
   for (const ts of added(prev.trivialEdits ?? [], next.trivialEdits ?? [])) out.push({ field: "trivialEdits", op: "add", value: ts, ts });
   if (next.target && JSON.stringify(next.target) !== JSON.stringify(prev.target)) out.push({ field: "target", op: "set", value: next.target, ts: Date.parse(next.target.set_at) || now });
   if (next.brainstormRequired !== prev.brainstormRequired) out.push({ field: "brainstormRequired", op: "set", value: next.brainstormRequired, ts: now });
+  for (const [aid, name] of Object.entries(next.prdOwners ?? {})) if (prev.prdOwners?.[aid] !== name) out.push({ field: "prdOwners", op: "merge", value: [aid, name], ts: now });
+  for (const v of tail(prev.prdViolations ?? [], next.prdViolations ?? [])) out.push({ field: "prdViolations", op: "append", value: v, ts: v.ts ?? now });
+  for (const [key, ts] of Object.entries(next.prdStopBlocked ?? {})) if (prev.prdStopBlocked?.[key] !== ts) out.push({ field: "prdStopBlocked", op: "merge", value: [key, ts], ts });
   return out;
 }

package/src/tracking/track-journal.ts

@@ -14,7 +14,7 @@ import { dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { computeMac, loadOrCreateKey } from "./integrity";
 import { withTrackLockSyncBlocking } from "./track-lock-sync";
-import { emptyTrack, type SessionTrack } from "./session-state";
+import { emptyTrack, PRD_VIOLATIONS_CAP, type PrdViolationRecord, type SessionTrack } from "./session-state";
 import type { AuthEntry } from "../freshness/doc-helpers";
 import type { SessionTarget } from "../policy/apex-authorization";
 import type { Receipt } from "./receipts";
@@ -78,6 +78,9 @@ export function foldEvents(events: TrackEvent[], base: SessionTrack = emptyTrack
   const at: Record<string, number> = { ...base.refsReadAt };
   const receipts: Receipt[] = [...(base.receipts ?? [])];
   const trivial = new Set(base.trivialEdits ?? []);
+  const prdOwners: Record<string, string> = { ...base.prdOwners };
+  const prdViolations: PrdViolationRecord[] = [...(base.prdViolations ?? [])];
+  const prdStopBlocked: Record<string, number> = { ...base.prdStopBlocked };
   let targetTs = base.target ? Date.parse(base.target.set_at) || 0 : 0, brainstormTs = 0; // a base flag is unstamped: any event overrides it
   for (const ev of [...events].sort((a, b) => a.ts - b.ts)) { // stable: log order breaks ts ties
     if (ev.field === "refsRead") { const p = String(ev.value); if (!t.refsRead.includes(p)) t.refsRead.push(p); }
@@ -88,9 +91,15 @@ export function foldEvents(events: TrackEvent[], base: SessionTrack = emptyTrack
     else if (ev.field === "trivialEdits") trivial.add(Number(ev.value));
     else if (ev.field === "target" && ev.ts >= targetTs) { t.target = ev.value as SessionTarget; targetTs = ev.ts; }
     else if (ev.field === "brainstormRequired" && ev.ts >= brainstormTs) { t.brainstormRequired = Boolean(ev.value); brainstormTs = ev.ts; }
+    else if (ev.field === "prdOwners") { const [aid, name] = ev.value as [string, string]; prdOwners[aid] = name; }
+    else if (ev.field === "prdViolations") { prdViolations.push(ev.value as PrdViolationRecord); }
+    else if (ev.field === "prdStopBlocked") { const [key, ts] = ev.value as [string, number]; prdStopBlocked[key] = ts; }
   }
   if (Object.keys(at).length) t.refsReadAt = at;
   if (receipts.length) t.receipts = receipts;
+  if (Object.keys(prdOwners).length) t.prdOwners = prdOwners;
+  if (prdViolations.length) t.prdViolations = prdViolations.slice(-PRD_VIOLATIONS_CAP);
+  if (Object.keys(prdStopBlocked).length) t.prdStopBlocked = prdStopBlocked;
   const maxT = Math.max(0, ...trivial);
   t.trivialEdits = [...trivial].filter((x) => x > maxT - TRIVIAL_WINDOW_MS).sort((a, b) => a - b);
   return t;

package/dist/run-DkrzC0gb.mjs

@@ -1,42 +0,0 @@
-import { t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
-import { t as evaluate } from "./evaluate-CMiIqHeH.mjs";
-import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
-import { execFileSync } from "node:child_process";
-//#region src/cli/run.ts
-/** Staged files (Added/Copied/Modified/Renamed). Uses `node:child_process` (Bun shell can hang on `git show`). */
-function stagedFiles() {
-	return execFileSync("git", [
-		"diff",
-		"--cached",
-		"--name-only",
-		"--diff-filter=ACMR"
-	], { encoding: "utf8" }).trim().split("\n").filter(Boolean);
-}
-/**
-* Read a file's staged (index) content — not the working-tree version.
-* Uses `execFileSync` with an argv array (never a shell), so a staged
-* filename containing shell metacharacters (backticks, `$(...)`, quotes)
-* reaches `git show` as a single literal argument — see issue #87.
-*/
-function stagedContent(path) {
-	return execFileSync("git", ["show", `:${path}`], { encoding: "utf8" });
-}
-/**
-* Evaluate staged code files against the policy core; return violation blocks.
-* `read` is injected (the real impl is {@link stagedContent}) so this is pure + testable.
-*/
-function checkStaged(files, read) {
-	const violations = [];
-	for (const file of files) {
-		if (!isCodeFile(file)) continue;
-		const r = evaluate({
-			tool: "Write",
-			filePath: file,
-			content: read(file)
-		});
-		if (r.decision === "deny" && r.prompt) violations.push(`${file}\n${formatPrompt(r.prompt)}`);
-	}
-	return violations;
-}
-//#endregion
-export { stagedContent as n, stagedFiles as r, checkStaged as t };