@fusengine/harness 0.1.89 → 0.1.91

package/src/runtime/gate.ts

@@ -0,0 +1,128 @@
+import { evaluate, type PolicyResult } from "../policy/evaluate";
+import { protectedPathGate } from "../policy/trivial-edits";
+import { existingLineCounts, isApexScoped } from "./gate-helpers";
+import { FAIL_CLOSED } from "../policy/guards";
+import { loadTrack } from "../tracking/store";
+import { dryGate } from "./dry";
+import { preCommitGate } from "./precommit";
+import { modularGate } from "./modular";
+import { frameworkSkillGate } from "./framework-skill-gate";
+import { reconcileRefReadsFromTranscript } from "../freshness/ref-evidence";
+import { reconcileRefReadsFromJournal } from "../freshness/ref-journal";
+import { isShadcnWrite, shadcnSkillGate } from "../policy/shadcn-skill-gate";
+import { isTailwindWrite, tailwindSkillGate } from "../policy/tailwind-skill-gate";
+import { geminiMcpGate } from "../policy/gemini-mcp-gate";
+import { apexScopedGate } from "./gate-apex";
+import { withDenyLoop } from "./deny-loop-store";
+import { recordOneShot } from "../tracking/one-shot";
+import { dirname } from "node:path";
+import type { GateInput } from "./gate-input";
+import type { Prompt } from "../prompt/types";
+
+export type { GateInput } from "./gate-input";
+
+/** Prior agents the freshness gate requires before a code edit. */
+export const REQUIRED_AGENTS: ReadonlyArray<string> = ["explore-codebase", "research-expert"];
+
+/**
+ * Default freshness window (ms). Matches the plugin's `FUSE_ENFORCE_TTL_SEC`
+ * default (120s); only a fallback for callers that omit `windowMs` (e.g. tests) —
+ * the real CLI path always supplies it from `resolveTtlSec()` (`src/config/ttl.ts`).
+ */
+export const DEFAULT_WINDOW_MS = 120_000;
+
+/** Trivial edits allowed within the window before the full APEX gates apply. */
+export const TRIVIAL_BUDGET = 4;
+
+/**
+ * Full gate: {@link runGates} yields the first blocking prompt (or null); the tail
+ * records the one-shot metric ({@link recordOneShot}, observation-only) then lets
+ * {@link withDenyLoop} rewrite an identical retried deny (decision unchanged).
+ */
+export async function gate(input: GateInput): Promise<Prompt | null> {
+  const prompt = await runGates(input);
+  return finalizeGate(input, prompt, input.command);
+}
+
+/**
+ * Gate independent Cursor command candidates without merging their shell syntax.
+ * Stateful outcome bookkeeping runs once, against the command that decided the
+ * aggregate result. A single distinct candidate follows {@link gate} verbatim.
+ */
+export async function gateCommandCandidates(input: GateInput, candidates: readonly string[]): Promise<Prompt | null> {
+  const distinct = [...new Set(candidates)];
+  if (distinct.length <= 1) return gate(input);
+
+  let decisive: { prompt: Prompt; command: string } | undefined;
+  for (const command of distinct) {
+    const prompt = await runGates({ ...input, command });
+    if (!prompt) continue;
+    if (!decisive || promptRank(prompt) > promptRank(decisive.prompt)) decisive = { prompt, command };
+    if (prompt.kind === "block") break;
+  }
+  return finalizeGate(input, decisive?.prompt ?? null, decisive?.command ?? input.command);
+}
+
+/** Persist one final gate outcome and apply deny-loop enrichment exactly once. */
+function finalizeGate(input: GateInput, prompt: Prompt | null, command: string | undefined): Prompt | null {
+  const op = { filePath: input.filePath, content: input.content, command };
+  const dir = dirname(input.trackFile);
+  recordOneShot(prompt, op, { now: input.now, dir, sessionId: input.sessionId });
+  return withDenyLoop(prompt, input.tool, op, { now: input.now, dir, windowMs: input.windowMs ?? DEFAULT_WINDOW_MS, sessionId: input.sessionId });
+}
+
+/** Higher numeric values dominate while equal values preserve wire order. */
+function promptRank(prompt: Prompt): number {
+  return prompt.kind === "block" ? 3 : prompt.kind === "ask" ? 2 : 1;
+}
+
+/** Stateless guards, then the trivial fast path, then the stateful APEX gates. */
+async function runGates(input: GateInput): Promise<Prompt | null> {
+  // Pre-commit lint hard-block runs FIRST: evaluate()'s GIT_ASK branch would
+  // otherwise short-circuit a `git commit` before the linters get to veto it.
+  const precommit = preCommitGate(input.tool, input.command, input.cwd);
+  if (precommit) return precommit;
+  // Hook-managed paths: absolute deny on ALL extensions, BEFORE the code-ext/exempt filters (parity enforce-apex-phases.ts:48-52 — isApexScoped never routes a non-code/exempt path to the guard).
+  const protectedDeny = protectedPathGate(input.tool, input.filePath);
+  if (protectedDeny) return protectedDeny;
+  const { raw: existingLines, code: existingCodeLines, content: existingContent } = existingLineCounts(input.filePath);
+  let quick: PolicyResult;
+  try {
+    quick = evaluate({ tool: input.tool, filePath: input.filePath, content: input.content, command: input.command, agentType: input.agentType, existingLines, existingContent, oldString: input.oldString, isReplaceAll: input.isReplaceAll, neverApproval: input.neverApproval });
+  } catch {
+    return FAIL_CLOSED;
+  }
+  if (quick.decision !== "allow" && quick.prompt) return quick.prompt;
+  const modular = modularGate(input.tool, input.filePath, input.content, input.cwd);
+  if (modular) return modular;
+  if (!input.filePath) return null;
+  const filePath = input.filePath;
+  // Reconcile refsRead BEFORE any consumer from two durable, race-immune sources (racy load→save loses lone
+  // writes under the fan-out): the transcript restores the LEAD's flushed read, the append-only journal (ref-journal.ts) the TEAMMATE's un-flushed one (lag > TTL).
+  const track = reconcileRefReadsFromJournal(
+    reconcileRefReadsFromTranscript(await loadTrack(input.trackFile), input.transcriptPath, input.now),
+    dirname(input.trackFile), input.now,
+  );
+  const solidOrSkill = frameworkSkillGate(input, track.refsRead, existingCodeLines);
+  if (solidOrSkill) return solidOrSkill;
+  // Standalone shadcn/ui gate (ports check-skill-loaded.py): runs independently of `framework` since a components.json / .css write may detect as "generic", mirroring the real plugin's own PreToolUse hook alongside react's.
+  if (isShadcnWrite(input.tool, filePath)) {
+    const shadcnBlock = shadcnSkillGate(input.tool, filePath, input.content ?? "", { refsRead: track.refsRead, authorizations: track.authorizations, sessionId: input.sessionId });
+    if (shadcnBlock) return shadcnBlock;
+  }
+  // Standalone Tailwind base-skill gate (ports check-tailwind-skill.py Phase 1): a .tsx/.jsx write with Tailwind classes needs a base Tailwind skill read, independent of framework.
+  if (isTailwindWrite(input.tool, filePath, input.content ?? "")) {
+    const twBlock = tailwindSkillGate(input.tool, filePath, input.content ?? "", track.refsRead);
+    if (twBlock) return twBlock;
+  }
+  // OPT-IN Gemini Design MCP gate (ports enforce-gemini-mcp.py) — a no-op unless FUSE_ENFORCE_GEMINI_MCP is set, then blocks hand-written Tailwind UI until a mcp__gemini-design__* call is made this session.
+  const geminiBlock = geminiMcpGate(input.tool, filePath, input.content ?? "", { authorizations: track.authorizations, sessionId: input.sessionId });
+  if (geminiBlock) return geminiBlock;
+  // The freshness/doc/SOLID APEX gates only police code files (require-apex-agents.py parity): non-code and exempt paths skip straight to the DRY check below.
+  if (isApexScoped(input.filePath)) {
+    const apex = await apexScopedGate(input, track, input.windowMs ?? DEFAULT_WINDOW_MS);
+    if (apex) return apex;
+  }
+  // DRY duplication (effectful: greps the codebase) — runs once the APEX gates pass.
+  return dryGate(input.tool, input.filePath, input.content, input.cwd);
+}

package/src/runtime/handle-post.ts

@@ -0,0 +1,104 @@
+import { extractText } from "../cache/mcp-response";
+import { activityFor } from "./activity";
+import { mcpPostStore } from "./mcp";
+import { recordActivity } from "./record";
+import { designGate } from "./design";
+import { postEditContext } from "./lifecycle-bridge";
+import { postTrackingSideEffects } from "./lifecycle/post-tracking";
+import { aipilotPostToolUse, checkFileSize, validateTailwind } from "./lifecycle";
+import { seoPostToolUseResponse } from "./lifecycle/seo/post-tool-use";
+import { classifyAgentEvidence, recordAgentEvidence } from "../freshness/agent-evidence-record";
+import { recordCodexSpawnEvidence } from "../freshness/codex-spawn-evidence";
+import { captureBashReceipt } from "./receipt-capture";
+import { recordCodexPostFailure } from "../tracking/codex-post-failure";
+import { defaultStateDir } from "./paths";
+import { fanOutFiles, firstFileMatch } from "./post-fanout";
+import { postOutcome } from "./post-outcome";
+import type { PreContext } from "./handle-pre";
+import type { HandleOutcome } from "./handle";
+
+function isCursorAfterFileEdit(id: string, payload: Record<string, unknown>): boolean {
+  if (id !== "cursor") return false;
+  const hookEvent = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+  if (hookEvent) return /^afterFileEdit$/i.test(hookEvent);
+  return typeof payload.file_path === "string" && Array.isArray(payload.edits);
+}
+
+/**
+ * Run the PostToolUse pipeline: store the MCP response, emit a design warning,
+ * record the activity into the session track, apply per-scope side-effects (SEO
+ * deny, aipilot task cache), then inject the post-edit context.
+ *
+ * POST is advisory-only for the design pipeline: it can never undo a tool
+ * that already ran (the hard block lives in the PreToolUse `designFilesGate`).
+ * `designGate` therefore stays on the RAW, un-fanned event — its
+ * `recordPost` apply_patch branch is promote-only and resolves relative
+ * `design-system.md` paths via `join(cwd, …)` (design-helpers.ts); fanning
+ * that call would instead route the file through the Write/Edit branch,
+ * which reads `event.filePath` UNRESOLVED (breaking cwd-relative promotion)
+ * and can DEGRADE the state — both forbidden by the apply_patch promote-only
+ * doctrine (see `design-files-gate.ts` module doc). Only `designPassNotice`
+ * (pure formatting, no disk access, no state write) is fanned via
+ * {@link fanOutFiles}, so `apply_patch` gets one notice line per real file
+ * instead of none.
+ * @param ctx - The resolved context (same shape as the pre pipeline).
+ * @returns The native hook outcome.
+ */
+export async function handlePost(ctx: PreContext): Promise<HandleOutcome> {
+  const { id, payload, event, framework, mcpDir, file, opts } = ctx;
+  const cursorAfterFileEdit = isCursorAfterFileEdit(id, payload);
+  const designCacheDir = ctx.designCacheDir ?? mcpDir;
+  let response = payload.tool_response ?? payload.tool_output;
+  if (id === "cursor" && /^afterMCPExecution$/i.test(event.eventName ?? "")) {
+    try {
+      response = typeof payload.result_json === "string" ? JSON.parse(payload.result_json) : payload.result_json;
+    } catch {
+      response = undefined;
+    }
+  }
+  mcpPostStore(event.tool, event.input, response, mcpDir);
+  const designWarn = designGate(payload, event, designCacheDir, opts.cwd, opts.corpusRoot);
+  const activities = activityFor({ tool: event.tool, input: event.input, sessionId: event.sessionId, framework, now: opts.now, responseLength: extractText(response).length });
+  for (const activity of activities) await recordActivity(file, activity);
+  // Session-scoped evidence (parity track-subagent-research.py): sub-agent hooks
+  // carry the LEAD's session_id — Task/Agent launches excluded (credited above).
+  const evidence = classifyAgentEvidence(event.tool, event.input, response);
+  if (evidence) await recordAgentEvidence(file, evidence, opts.now, typeof payload.agent_id === "string" ? payload.agent_id : undefined);
+  // Codex multi_agent_v2 `spawn_agent` -> same session track (no-op for every
+  // other harness / non-spawn tool / missing `agent_type`; see module doc).
+  await recordCodexSpawnEvidence(file, id, event.tool, event.input, opts.now);
+  // Verification receipts (tsc/bun test runs) — structured responses only
+  // (Kimi's string `tool_output` would forge a success receipt; see module).
+  await captureBashReceipt(file, event.tool, event.command, payload.tool_result, response, opts.now);
+  if (id === "codex") recordCodexPostFailure(event.tool, payload.tool_result ?? response, { now: opts.now, dir: defaultStateDir(opts.cwd), sessionId: event.sessionId });
+  // Codex `apply_patch` and Cursor `afterFileEdit` fan into per-file events for
+  // 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);
+  const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
+  if (seoDeny && !cursorAfterFileEdit) return { stdout: seoDeny, exit: 0 };
+  if (opts.scope === "solid") {
+    const solidWarn = firstFileMatch(files, checkFileSize);
+    if (solidWarn && !cursorAfterFileEdit) return { stdout: solidWarn, exit: 0 };
+  }
+  if (opts.scope === "tailwindcss") {
+    const tailwindWarn = firstFileMatch(files, validateTailwind);
+    if (tailwindWarn && !cursorAfterFileEdit) return { stdout: tailwindWarn, exit: 0 };
+  }
+  if (opts.scope === "aipilot" && (event.tool === "TaskCreate" || event.tool === "TaskUpdate" || event.tool === "Write" || event.tool === "Edit")) {
+    const out = await aipilotPostToolUse(payload, opts.cwd, id);
+    if (out && !cursorAfterFileEdit) return { stdout: out, exit: 0 };
+  }
+  let extra = "";
+  for (const f of files) {
+    extra = await postEditContext(opts.scope ?? "core", f, opts.now, id);
+    if (extra) break;
+  }
+  return postOutcome({
+    id, agentId: typeof payload.agent_id === "string" ? payload.agent_id : "", sessionId: event.sessionId,
+    now: opts.now, cwd: opts.cwd, activities, files,
+    designCacheDir, designWarn, extra,
+    cursorAfterFileEdit,
+    cursorEventName: typeof payload.hook_event_name === "string" ? payload.hook_event_name : "",
+  });
+}

package/src/runtime/handle-pre.ts

@@ -0,0 +1,137 @@
+import { dirname } from "node:path";
+import { loadRefs } from "../refs/loader";
+import { gate, gateCommandCandidates } from "./gate";
+import { MCP_TTL_MS, mcpPreIntercept } from "./mcp";
+import type { NormalizedEvent } from "./normalize";
+import { recordActivity } from "./record";
+import { respond } from "./respond";
+import { withDenyNotice } from "./deny-notice";
+import { designGate } from "./design";
+import { taskContext } from "./inject-context";
+import { securityAdvisory, securityAdvisoryForPatch } from "./lifecycle/security/check-skill";
+import { solidScopeOutcome } from "./solid-pre";
+import { isAgentTool } from "./is-agent-tool";
+import { allowOutcome } from "./pre-allow";
+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 type { HandleOptions, HandleOutcome } from "./handle";
+
+/** Context the PreToolUse pipeline needs (resolved once by {@link handleHook}). */
+export interface PreContext {
+  id: string;
+  payload: Record<string, unknown>;
+  event: NormalizedEvent;
+  framework: string;
+  mcpDir: string;
+  /**
+   * Session-anchored design-pipeline cache dir (see design-cache-resolve.ts) —
+   * distinct from `mcpDir`. Optional: pre-existing context literals (tests
+   * built before this field existed) omit it and fall back to `mcpDir`
+   * unchanged, so they keep their old, already-passing behavior verbatim.
+   */
+  designCacheDir?: string;
+  file: string;
+  opts: HandleOptions;
+}
+
+/**
+ * Run the PreToolUse pipeline: MCP/WebFetch cache intercept, design gate, APEX Task context injection, then the stateless+APEX gate chain, returning the native hook outcome (deny/ask/inject or allow).
+ * @param ctx - The resolved pre-context.
+ * @returns The hook outcome.
+ */
+export async function handlePre(ctx: PreContext): Promise<HandleOutcome> {
+  const { id, payload, event, framework, mcpDir, file, opts } = ctx;
+  const designCacheDir = ctx.designCacheDir ?? mcpDir;
+  const intercept = mcpPreIntercept(id, event.tool, event.input, mcpDir, MCP_TTL_MS, opts.now);
+  if (intercept !== null) {
+    if (intercept.docSource) await recordActivity(file, { kind: "doc", framework, sessionId: event.sessionId, source: intercept.docSource });
+    return { stdout: intercept.stdout, exit: 0 };
+  }
+
+  const designBlock = designGate(payload, event, designCacheDir, opts.cwd, opts.corpusRoot);
+  if (designBlock) return { stdout: withDenyNotice(id, respond(id, designBlock, event.eventName ?? "PreToolUse"), designBlock, event.sessionId, dirname(file), opts.now), exit: 0 };
+
+  if (id === "cursor" && (event.eventName === "beforeReadFile" || event.eventName === "beforeTabFileRead")) {
+    const readPolicy = evaluate({ tool: event.tool, filePath: event.filePath });
+    return {
+      stdout: readPolicy.prompt
+        ? respond(id, readPolicy.prompt, event.eventName)
+        : JSON.stringify({ permission: "allow" }),
+      exit: 0,
+    };
+  }
+
+  // Security scope is advisory-only (ports check-security-skill.py): emit the
+  // non-blocking advisory when the skill is unread, else allow — NEVER run the
+  // core APEX/SOLID/file-size gate chain (the security plugin never did).
+  if (opts.scope === "security") {
+    return { stdout: event.files?.length ? securityAdvisoryForPatch(event.files, opts.now) : securityAdvisory(event.tool, event.filePath ?? "", opts.now), exit: 0 };
+  }
+
+  // Solid scope mirrors security above: run ONLY the solid-scope gates
+  // (file-size deny, then Go/Python interface-location) and ALWAYS return —
+  // NEVER the core gate chain: core-guards owns it, so falling through would
+  // run gate() twice per edit (duplicate denies + added latency).
+  if (opts.scope === "solid") {
+    return solidScopeOutcome(id, event, file, opts.now);
+  }
+
+  // PreToolUse sub-agent dispatch (Task on claude/codex, Agent/AgentSwarm on
+  // kimi): inject APEX sub-agent context when the target apex dir exists.
+  if (isAgentTool(event.tool)) {
+    const taskCtx = taskContext(opts.cwd, id);
+    if (taskCtx) return { stdout: taskCtx, exit: 0 };
+  }
+
+  // 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.
+  if (event.files && event.files.length > 0) {
+    const patchPrompt = applyPatchGate(event.files, opts.cwd);
+    if (patchPrompt) return { stdout: withDenyNotice(id, respond(id, patchPrompt, event.eventName ?? "PreToolUse"), patchPrompt, event.sessionId, dirname(file), opts.now), exit: 0 };
+  }
+
+  const refs = opts.refsDir ? await loadRefs(opts.refsDir) : undefined;
+  const gateInput = {
+    sessionId: event.sessionId,
+    framework,
+    tool: event.tool,
+    filePath: event.filePath,
+    content: event.content,
+    command: event.command,
+    cwd: opts.cwd,
+    refs,
+    isReplaceAll: event.input.replace_all === true,
+    oldString: event.oldString,
+    agentType: event.agentType,
+    agentId: typeof payload.agent_id === "string" ? payload.agent_id : undefined,
+    windowMs: opts.windowMs,
+    now: opts.now,
+    trackFile: file,
+    transcriptPath: typeof payload.transcript_path === "string" ? payload.transcript_path : undefined,
+    neverApproval: id === "codex" && isBypassPermissions(event.permissionMode),
+  };
+  const prompt = id === "cursor" && (event.commandCandidates?.length ?? 0) > 1
+    ? await gateCommandCandidates(gateInput, event.commandCandidates!)
+    : await gate(gateInput);
+  if (prompt) {
+    // CONFIRM <code> flow: ONLY changes anything when Codex/Kimi are about to
+    // downgrade THIS `ask` to a hard deny (confirmGate returns null in every
+    // other case — including every claude-code call, unconditionally, and
+    // every non-`ask` prompt kind — so the line below is byte-identical to
+    // the pre-CONFIRM behavior whenever it applies).
+    const confirm = confirmGate(id, prompt, event.command, event.sessionId, opts.now, opts.home,
+      id === "codex" ? { tool: event.tool, cwd: event.cwd ?? opts.cwd, toolUseId: event.toolUseId } : undefined);
+    if (confirm?.allow) {
+      return allowOutcome(id, event, payload, designCacheDir, opts.cwd, { trackFile: file, windowMs: opts.windowMs, now: opts.now }, opts.corpusRoot);
+    }
+    const finalPrompt = confirm ? confirm.prompt : prompt;
+    return { stdout: withDenyNotice(id, respond(id, finalPrompt, event.eventName ?? "PreToolUse"), finalPrompt, event.sessionId, dirname(file), opts.now), exit: 0 };
+  }
+  // Every gate allowed: hand off to the ALLOW-path assembly (pass notice +
+  // decision-time lesson + evidence-fresh notice). A deny/ask already returned
+  // above, so nothing it emits can block nor override a decision.
+  return allowOutcome(id, event, payload, designCacheDir, opts.cwd, { trackFile: file, windowMs: opts.windowMs, now: opts.now }, opts.corpusRoot);
+}

package/src/runtime/handle-scope-async.ts

@@ -0,0 +1,29 @@
+/**
+ * Pre-pipeline async scope interception for {@link handleHook}. The aipilot and
+ * memory scopes reach external resources (cache files / Graphiti HTTP) and may
+ * emit stdout for lifecycle events, so they run before the sync gate pipeline.
+ */
+import { dispatchAipilot } from "./lifecycle";
+import { dispatchMemory } from "./lifecycle/memory/dispatch";
+import { cursorEventContract } from "../adapters/cursor/events";
+import { toCursorLifecycleResponse } from "../adapters/cursor/respond";
+import type { PluginScope } from "./lifecycle";
+
+/**
+ * Run the async per-scope dispatcher for the invoking scope, if any.
+ * @param scope - The invoking plugin scope.
+ * @param event - The raw hook event name.
+ * @param payload - The raw hook payload.
+ * @param cwd - Project root.
+ * @param now - Clock.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native stdout when intercepted, or `null` to fall through.
+ */
+export async function asyncScopeStdout(scope: PluginScope | undefined, event: string, payload: Record<string, unknown>, cwd: string, now: number, id: string = "claude-code"): Promise<string | null> {
+  const dispatchedEvent = id === "cursor" ? cursorEventContract(event).lifecycle : event;
+  if (dispatchedEvent === null) return null;
+  let stdout: string | null = null;
+  if (scope === "aipilot") stdout = await dispatchAipilot(dispatchedEvent, payload, cwd, now, undefined, id);
+  if (scope === "memory") stdout = await dispatchMemory(dispatchedEvent, payload, cwd, now);
+  return id === "cursor" && stdout !== null ? toCursorLifecycleResponse(stdout, event) : stdout;
+}

package/src/runtime/handle-types.ts

@@ -0,0 +1,27 @@
+import type { PluginScope } from "./lifecycle";
+
+/** Options for {@link handleHook} (caller supplies the clock + project root). */
+export interface HandleOptions {
+  now: number;
+  cwd: string;
+  /** Directory of SOLID reference `.md` files for `solidReadGate` (else inert). */
+  refsDir?: string;
+  /** APEX freshness window in ms (from `FUSE_ENFORCE_TTL_SEC`). */
+  windowMs?: number;
+  /** Which plugin's hooks.json invoked the harness (selects lifecycle behavior). */
+  scope?: PluginScope;
+  /**
+   * Test/integration seam: the resolved refs-design corpus root ("" = absent).
+   * Undefined = resolve from disk (the production behavior); supplied = used
+   * as-is, so tests can drive the corpus-present branch deterministically.
+   */
+  corpusRoot?: string;
+  /** Test-only OS home override for the session-anchored design cache dir (see design-cache-resolve.ts). Undefined = real `os.homedir()`. */
+  home?: string;
+}
+
+/** What the hook bin should print + exit with. */
+export interface HandleOutcome {
+  stdout: string;
+  exit: number;
+}

package/src/runtime/handle.ts

@@ -0,0 +1,116 @@
+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 { designLifecycle } from "./design-lifecycle";
+import { promptSubmitContext } from "./inject-context";
+import { lifecycleStdout } from "./lifecycle-bridge";
+import { handlePre } from "./handle-pre";
+import { handlePost } from "./handle-post";
+import { asyncScopeStdout } from "./handle-scope-async";
+import { resolveDesignCacheDir } from "./design-cache-resolve";
+import { resyncCodexAgents } from "./lifecycle/codex-resync/resync";
+import { resetFragmentRegistry } from "./fragment-registry";
+import { attachBudgetRecap } from "./inject-budget-recap";
+import { promptText } from "./prompt-text";
+import { handleConfirmSubmit } from "./confirm/confirm-submit";
+import { submitCodexConfirmation } from "./confirm/codex-confirm";
+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";
+export type { HandleOptions, HandleOutcome } from "./handle-types";
+
+/** Raw Claude hook event name from a payload (empty when absent). */
+function rawEventName(payload: Record<string, unknown>): string {
+  return typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+}
+
+/**
+ * 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
+ * POST event it records the activity into the track. The loop that makes the
+ * package behave like the Claude plugin, on any harness.
+ */
+async function handleHookCore(id: string, payload: Record<string, unknown>, opts: HandleOptions): Promise<HandleOutcome> {
+  const event = normalizeEvent(id, payload);
+  if (id === "cursor") {
+    const cursorCwd = cursorProjectCwd(event.cwd, event.workspaceRoots ?? [], event.filePath, opts.cwd);
+    if (cursorCwd !== opts.cwd) opts = { ...opts, cwd: cursorCwd };
+  }
+  const rawPrompt = payload.prompt;
+  const userPrompt = typeof rawPrompt === "string" || Array.isArray(rawPrompt) ? promptText(rawPrompt) : undefined;
+  if (id === "codex" && rawEventName(payload) === "UserPromptSubmit" && userPrompt !== undefined) {
+    submitCodexConfirmation(event.sessionId, userPrompt, opts.now, opts.home, codexPromptOrigin(payload));
+  }
+  // Fresh slate for this invocation's capFragment tally — one hook event is
+  // exactly one lifecycle branch below (see dispatchLifecycle), so a single
+  // reset here can never mix fragments across unrelated events.
+  resetFragmentRegistry();
+  const layout = projectLayout(opts.cwd);
+  const file = trackFile(event.sessionId, defaultStateDir(opts.cwd));
+  const mcpDir = layout.cacheDir;
+  // Design pipeline (flag + `.design-state-*.json`) is anchored on the session
+  // id, not `mcpDir`/cwd — see design-cache-resolve.ts. `mcpDir` itself stays
+  // cwd-derived for the unrelated MCP/WebFetch cache.
+  const designCacheDir = resolveDesignCacheDir(event.sessionId, mcpDir, opts.home);
+  const framework = detectFramework(event.filePath ?? "", event.content ?? "", opts.cwd);
+
+  // Design-agent lifecycle (SubagentStart/Stop): init/cleanup the pipeline state machine.
+  // claude-code + codex only: verified against openai/codex's OWN generated hook schemas
+  // (codex-rs/hooks/schema/generated/subagent-{start,stop}.command.input.schema.json @ 385c0a93,
+  // superseding the stale 44918ea1 Cargo.toml-only bump) — `agent_id`/`agent_type` are REQUIRED
+  // on both events, unconditional on `hide_spawn_agent_metadata` (that flag only reshapes the
+  // spawn_agent tool RESULT, not the hook payload). `payload.prompt` (design-mode "component"
+  // detection below) is absent from Codex's schema — degrades to detectMode's default, not a
+  // break. Cursor/Gemini/Cline/Hermes remain unverified — NOT added without the same proof.
+  if ((id === "claude-code" || id === "codex") && designLifecycle(payload, designCacheDir, opts.cwd, String(opts.now), opts.now)) {
+    return { stdout: "", exit: 0 };
+  }
+
+  // Codex-only, fail-open: refresh the plugin agents/commands cache on SessionStart when its fingerprint changed (strict no-op on every other harness).
+  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);
+  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);
+  if (life !== null) {
+    // Claude-Code-only: attachBudgetRecap's systemMessage envelope assumes the
+    // Claude adapter's stdout shape (mirrors the designLifecycle gate above).
+    const stdout = id === "claude-code" ? attachBudgetRecap(life, rawEventName(payload), event.sessionId, opts.cwd, opts.now) : life;
+    return { stdout, exit: 0 };
+  }
+
+  // UserPromptSubmit (core scope): brainstorm flag + CLAUDE.md injection.
+  // `payload.prompt` is a string on Claude Code/Codex, an array of content
+  // blocks on Kimi (see promptText) — either shape is normalized to text;
+  // anything else (field absent, or an unrecognized type) stays `undefined`
+  // so the block below is skipped exactly as before promptText existed.
+  if (userPrompt !== undefined) {
+    if (id !== "codex") handleConfirmSubmit(event.sessionId, userPrompt, opts.now, opts.home);
+    await withTrack(file, (track) => recordBrainstormRequired(track, detectCreationIntent(userPrompt)));
+    return { stdout: promptSubmitContext(userPrompt, opts.cwd, id), exit: 0 };
+  }
+
+  if (event.phase === "post") {
+    return handlePost({ id, payload, event, framework, mcpDir, designCacheDir, file, opts });
+  }
+
+  return handlePre({ id, payload, 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.
+ */
+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)) };
+}

package/src/runtime/home-state.ts

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { atomicWrite } from "../util/json-io";
+
+/** Home `~/.claude` dir — per-harness config (CLAUDE.md, logs, plugins). */
+export function claudeHome(home: string = homedir()): string {
+  return join(home, ".claude");
+}
+
+/** Neutral, harness-agnostic home for fuse-harness's OWN cache/state: `~/.fuse-harness`. */
+export function fuseHarnessHome(home: string = homedir()): string {
+  return join(home, ".fuse-harness");
+}
+
+/** `~/.fuse-harness/cache` base dir for session/cache state (shared across harnesses). */
+export function fusengineCache(home: string = homedir()): string {
+  return join(fuseHarnessHome(home), "cache");
+}
+
+/** `~/.fuse-harness/cache/sessions` — per-session JSON state dir. */
+export function sessionsDir(home: string = homedir()): string {
+  return join(fusengineCache(home), "sessions");
+}
+
+const SID_RE = /^[a-zA-Z0-9_-]{1,128}$/;
+
+/** Validate a session id (1-128 url-safe chars); null when invalid. */
+export function sanitizeSessionId(sid: unknown): string | null {
+  const s = String(sid ?? "").trim();
+  return SID_RE.test(s) ? s : null;
+}
+
+/** Unified per-session state file path: `sessions/session-<sid>.json`. */
+export function sessionStatePath(sid: string, home: string = homedir()): string {
+  return join(sessionsDir(home), `session-${sid}.json`);
+}
+
+/** Load a session-state dict, or `{}` when missing/corrupt (mirrors Python). */
+export function loadSessionState(sid: string, home: string = homedir()): Record<string, unknown> {
+  const path = sessionStatePath(sid, home);
+  try {
+    if (!existsSync(path)) return {};
+    const data: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return typeof data === "object" && data !== null && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Atomically persist a session-state dict (0o600 via atomicWrite, indent 2). */
+export function saveSessionState(sid: string, state: Record<string, unknown>, home: string = homedir()): void {
+  mkdirSync(sessionsDir(home), { recursive: true, mode: 0o700 });
+  atomicWrite(sessionStatePath(sid, home), JSON.stringify(state, null, 2));
+}

package/src/runtime/index.ts

@@ -0,0 +1,18 @@
+export * from "./paths";
+export * from "./storage";
+export * from "./record";
+export * from "./activity";
+export * from "./gate";
+export * from "./dry";
+export * from "./precommit";
+export * from "./normalize";
+export * from "./respond";
+export * from "./mcp";
+export * from "./inject-context";
+export * from "./home-state";
+export * from "./fs-cleanup";
+export * from "./dev-context";
+export * from "./lifecycle";
+export * from "./lifecycle-bridge";
+export * from "./handle-pre";
+export * from "./handle";

package/src/runtime/inform.ts

@@ -0,0 +1,28 @@
+/**
+ * Lifecycle context-injection renderer. Every emitter that injects text into
+ * the model's context (rules, lessons, CLAUDE.md preamble, ...) goes through
+ * here instead of calling the Claude builders directly:
+ * - kimi: raw text on stdout — Kimi Code CLI appends stdout to the context on
+ *   exit 0 (UserPromptSubmit is blockable; the Claude-shaped
+ *   `additionalContext` envelope would be ignored or leak as raw JSON text).
+ * - every other harness: the historical Claude-shaped envelope, byte-identical
+ *   to what the call sites produced before this module existed (zero-regression
+ *   default — `attachSystemMessage` concatenates notices with "\n", so a single
+ *   combined notice equals the previous chained calls).
+ */
+import { attachSystemMessage, contextResponse } from "../adapters/claude";
+
+/**
+ * Render a context injection for the firing harness.
+ * @param id - Harness id.
+ * @param event - The firing hook event name (envelope tag for Claude shapes).
+ * @param text - The context body to inject.
+ * @param notice - Optional human-facing notice (systemMessage on Claude
+ * shapes; appended as plain text for kimi).
+ * @returns The native hook stdout.
+ */
+export function renderInform(id: string, event: string, text: string, notice?: string): string {
+  if (id === "kimi") return notice ? `${text}\n\n${notice}` : text;
+  const base = contextResponse(event, text);
+  return notice ? attachSystemMessage(base, notice) : base;
+}