@fusengine/harness 0.1.90 → 0.1.91

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

package/src/runtime/inject-budget-recap.ts

@@ -0,0 +1,47 @@
+/**
+ * @module inject-budget-recap
+ * ONE event-level recap of every {@link module:inject-budget.capFragment}
+ * -tracked fragment injected for a SessionStart/SubagentStart event — the
+ * aggregated view the per-fragment caps never gave: each injection point
+ * (dev-context, snapshot sections, lessons, apex-subagent, ...) caps and
+ * reports itself in ISOLATION, with no total across the whole event.
+ *
+ * Rides the user-visible `systemMessage` channel, Claude-Code-only (gate at
+ * the call site — mirrors the existing `id === "claude-code"` pattern for
+ * `designLifecycle` in handle.ts): other adapters do not all re-export
+ * `attachSystemMessage`, and stamping a Claude-shaped envelope onto another
+ * harness's stdout shape would be silently wrong there.
+ *
+ * Deduped via {@link module:inject-dedup.onceExclusive}, not the JSON
+ * `oncePerWindow`: SessionStart/SubagentStart fan out across every installed
+ * plugin exactly like PostToolUse does (see burst-window.ts) — a shared-JSON
+ * read-modify-write here would risk the same lost-update race already fixed
+ * for the sniper reminder (lesson 2026-07-05 16:00).
+ * @packageDocumentation
+ */
+import { attachSystemMessage } from "../adapters/claude";
+import { budgetReport } from "./inject-budget";
+import { fragmentRegistry } from "./fragment-registry";
+import { onceExclusive } from "./inject-dedup";
+import { BURST_DEDUP_MS } from "./burst-window";
+import { defaultStateDir } from "./paths";
+
+/**
+ * Attach the aggregated recap onto `stdout` when 2+ fragments were recorded
+ * for `rawEvent`. A lone fragment already carries its own visibility (its
+ * producer's own per-fragment report, when it has one) — no recap is added
+ * for that case, so the common single-fragment event stays noise-free.
+ * @param stdout - The already-rendered hook stdout for this event.
+ * @param rawEvent - The raw hook event name (only SessionStart/SubagentStart qualify; others pass through unchanged).
+ * @param sessionId - Current session id (dedup scope).
+ * @param cwd - Project root (state-dir scope for the dedup marker).
+ * @param now - Clock.
+ * @returns `stdout` with a `systemMessage` recap attached, or `stdout` unchanged.
+ */
+export function attachBudgetRecap(stdout: string, rawEvent: string, sessionId: string, cwd: string, now: number): string {
+  if (rawEvent !== "SessionStart" && rawEvent !== "SubagentStart") return stdout;
+  const fragments = fragmentRegistry();
+  if (fragments.length <= 1) return stdout;
+  if (!onceExclusive(`budget:${sessionId}:${rawEvent}`, BURST_DEDUP_MS, { now, dir: defaultStateDir(cwd) })) return stdout;
+  return attachSystemMessage(stdout, budgetReport(fragments));
+}

package/src/runtime/inject-budget.ts

@@ -0,0 +1,81 @@
+/**
+ * @module inject-budget
+ * Hard per-fragment ceiling for harness-PRODUCED context injections (lessons,
+ * snapshot sections, APEX task context, cartographer/dev-context blocks) —
+ * inspired by Codex's "ContextualUserFragment, no item > 10K tokens" pattern.
+ * NEVER apply this to owner-authored content (CLAUDE.md/rules): that path is
+ * a locked invariant (see the "owner invariant" tests in
+ * test/dedup-inject.test.ts) and must always ship uncapped and in full.
+ *
+ * A real regression motivated this: MEMORY/LESSON.md's SessionStart injection
+ * had grown to ~44k tokens with no per-fragment or total alarm, silently
+ * bloating every SessionStart/SubagentStart turn.
+ * @packageDocumentation
+ */
+import { recordFragment } from "./fragment-registry";
+
+/**
+ * Hard cap per fragment, in characters. ~8000 chars ≈ 2000 tokens at the
+ * conservative ~4 chars/token ratio for mixed FR/EN prose — the accepted
+ * approximation absent a real tokenizer (cf. LangChain's `trim_messages`
+ * fallback token_counter). Chosen because a SINGLE SessionStart already
+ * stacks several harness fragments (lessons, snapshot, dev-context,
+ * cartographer) on top of the uncapped CLAUDE.md block, and the known 11x
+ * multi-plugin hook fan-out can multiply whatever ships — 2k tokens/fragment
+ * keeps the harness-produced share bounded even under that fan-out, while
+ * still leaving room for a few dozen useful lines of content.
+ */
+export const FRAGMENT_CHAR_CAP = 8000;
+
+/**
+ * Cap `text` at {@link FRAGMENT_CHAR_CAP} characters, cutting at the last
+ * newline within budget so no line is chopped mid-sentence. Text at or under
+ * the cap is returned byte-identical (no-op). Over the cap, a single English
+ * truncation line is appended so the reader knows content was dropped and
+ * that the SOURCE FILE itself is untouched (only this injected view is cut).
+ * @param label - Short identifier of the fragment (e.g. "lessons", "Git").
+ * @param text - The candidate fragment body.
+ * @returns `text` unchanged, or a truncated copy ending in the cut notice — always ≤ the cap.
+ */
+export function capFragment(label: string, text: string): string {
+  if (text.length <= FRAGMENT_CHAR_CAP) {
+    recordFragment(label, text.length);
+    return text;
+  }
+  const totalLen = text.length;
+  // Bound the label so a pathological (very long) label can never, by itself,
+  // push the suffix — and thus the output — past the cap. Real labels are short
+  // internal constants, so this is byte-identical for every actual caller.
+  const safeLabel = label.length <= 80 ? label : `${label.slice(0, 77)}...`;
+  const suffixFor = (keptLen: number): string =>
+    `\n[truncated ${safeLabel}: kept ${keptLen} of ${totalLen} chars — source file unchanged]`;
+  // Reserve worst-case suffix size using totalLen's digit count: kept length
+  // can only be <= totalLen, so its digit count never exceeds this reserve.
+  const reserve = suffixFor(totalLen).length;
+  const budget = Math.max(0, FRAGMENT_CHAR_CAP - reserve);
+  const slice = text.slice(0, budget);
+  const lastNl = slice.lastIndexOf("\n");
+  const kept = (lastNl > 0 ? slice.slice(0, lastNl) : slice).trimEnd();
+  const result = kept + suffixFor(kept.length);
+  recordFragment(label, result.length);
+  return result;
+}
+
+/** One named fragment's injected size, for {@link budgetReport}. */
+export interface FragmentSize {
+  label: string;
+  chars: number;
+}
+
+/**
+ * One-line numeric recap of what a batch of fragments actually injected —
+ * the owner-requested visibility so a silent blowup (like the 44k-token
+ * lessons block) shows up as a number instead of going unnoticed.
+ * @param fragments - The injected fragments (post-cap sizes).
+ * @returns e.g. `"injected 5 fragments, 14.2k chars"`, or `"injected 0 fragments"` when empty.
+ */
+export function budgetReport(fragments: FragmentSize[]): string {
+  if (fragments.length === 0) return "injected 0 fragments";
+  const total = fragments.reduce((sum, f) => sum + f.chars, 0);
+  return `injected ${fragments.length} fragments, ${(total / 1000).toFixed(1)}k chars`;
+}