@fusengine/harness 0.1.89 → 0.1.91

package/src/runtime/deny-loop-store.ts

@@ -0,0 +1,94 @@
+/**
+ * @module deny-loop-store
+ * Sidecar state + gate wiring for the mechanical anti-loop ({@link module:deny-loop}).
+ *
+ * STATE — a standalone sidecar (`deny-loop.json`) in the same per-project state
+ * dir as the session track, NOT a field in `session-state.ts`: that file is owned
+ * by another concern this batch, so a shared field would couple two owners and
+ * contend on one file for two unrelated maps. This mirrors the proven
+ * {@link module:inject-dedup} `oncePerWindow` sidecar (atomicWrite, prune-by-window,
+ * fail-open) and keeps the anti-loop self-contained.
+ *
+ * WINDOW — the hash expires with the same freshness window the gate already uses
+ * (`FUSE_ENFORCE_TTL_SEC` / `windowMs`): a loop is a burst, not a lifetime, so a
+ * stale deny past the window resets and a later identical call is a fresh #1.
+ * @packageDocumentation
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { denyHash, denyLoopCheck, enrichRepeatDeny, type DenyEntry, type DenyLoopResult } from "../policy/deny-loop";
+import { BURST_DEDUP_MS } from "./burst-window";
+import type { Prompt } from "../prompt/types";
+
+/** Sidecar basename under the per-project state dir. */
+const SIDECAR = "deny-loop.json";
+
+/**
+ * Injected clock + state dir + expiry window (no env var; the gate supplies all
+ * three). `sessionId` — when present — scopes the map key AND arms the burst
+ * dedup ({@link module:burst-window}) so the ~11 sibling plugin hooks of ONE
+ * event count once, not once each; two sessions never share a counter. Omitted
+ * by mono-process callers/tests → historical per-hash, no-dedup behaviour.
+ */
+export interface DenyLoopOpts { now: number; dir: string; windowMs: number; sessionId?: string; }
+
+/** Load the `{ hash -> DenyEntry }` map, or `{}` when missing/corrupt. */
+function loadMap(path: string): Record<string, DenyEntry> {
+  try {
+    if (!existsSync(path)) return {};
+    const data: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, DenyEntry>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Drop entries whose last deny is older than the window (bounds size + resets stale loops). */
+function prune(map: Record<string, DenyEntry>, now: number, windowMs: number): Record<string, DenyEntry> {
+  const out: Record<string, DenyEntry> = {};
+  for (const [k, e] of Object.entries(map)) {
+    if (e && typeof e.lastTs === "number" && now - e.lastTs < windowMs) out[k] = e;
+  }
+  return out;
+}
+
+/**
+ * Record a deny for `(tool, input)`: prune, {@link denyLoopCheck}, persist the
+ * bumped entry. Fails open (`isRepeat:false`) when the sidecar is unwritable — a
+ * broken state dir must never manufacture a false `[REPEAT]`.
+ * @param tool - Tool name.
+ * @param input - Identifying tool input.
+ * @param opts - Clock + state dir + window.
+ * @returns `{ isRepeat, count, hash }`.
+ */
+export function recordDeny(tool: string, input: Record<string, unknown>, opts: DenyLoopOpts): DenyLoopResult {
+  const hash = denyHash(tool, input);
+  const sid = opts.sessionId?.trim();
+  const key = sid ? `${hash}::${sid}` : hash;
+  const path = join(opts.dir, SIDECAR);
+  const map = prune(loadMap(path), opts.now, opts.windowMs);
+  const res = denyLoopCheck(key, map, { now: opts.now, windowMs: opts.windowMs, dedupMs: sid ? BURST_DEDUP_MS : 0 });
+  if (!res.deduped) {
+    map[key] = { count: res.count, lastTs: opts.now };
+    try { atomicWrite(path, JSON.stringify(map)); } catch { /* fail-open: never fabricate a repeat */ }
+  }
+  return { ...res, hash };
+}
+
+/**
+ * Gate tail: record every block deny; on a repeat, return the enriched prompt.
+ * Allows (`null`) and non-block prompts (`ask`/`inform`) pass through untouched —
+ * a loop is a retried REFUSAL, and only `block` is a refusal. The decision is
+ * NEVER changed; only a repeated block's message is rewritten.
+ * @param prompt - The gate's outcome.
+ * @param tool - Tool name.
+ * @param input - Identifying tool input.
+ * @param opts - Clock + state dir + window.
+ * @returns The prompt, enriched only when it is a repeated block.
+ */
+export function withDenyLoop(prompt: Prompt | null, tool: string, input: Record<string, unknown>, opts: DenyLoopOpts): Prompt | null {
+  if (!prompt || prompt.kind !== "block") return prompt;
+  const { isRepeat, count } = recordDeny(tool, input, opts);
+  return isRepeat ? enrichRepeatDeny(prompt, count) : prompt;
+}

package/src/runtime/deny-notice.ts

@@ -0,0 +1,52 @@
+/**
+ * @module deny-notice
+ * Attach a user-visible notice to a deny/ask hook response — the owner-reported
+ * gap where `permissionDecision: deny/ask` (the agent-only channel) left the
+ * human staring at a silent terminal. Mirrors {@link module:notices}'s
+ * compliance notices but for the BLOCKING outcomes those never covered.
+ * @packageDocumentation
+ */
+import figures from "figures";
+import type { Prompt } from "../prompt/types";
+import { attachSystemMessage } from "../adapters/claude";
+import { onceExclusive } from "./inject-dedup";
+import { BURST_DEDUP_MS } from "./burst-window";
+
+/**
+ * The human-facing line for a block/ask outcome: the gate's own
+ * {@link Prompt.userMessage} when it set one, else a generic symbol + title —
+ * text-presentation Unicode only (`figures.cross`/`?`), never emoji: terminal-safe,
+ * single-cell width, with the Windows fallbacks `figures` already resolves, matching
+ * the existing notice family (`notices.ts`'s `✓`/`⚠`, left untouched by this module).
+ * Null for `inform` ({@link module:respond}'s own `userMessage` path already
+ * covers it) or when neither applies.
+ */
+export function denyAskNotice(prompt: Prompt): string | null {
+  if (prompt.kind === "block") return prompt.userMessage ?? `${figures.cross} ${prompt.title}`;
+  if (prompt.kind === "ask") return prompt.userMessage ?? `? ${prompt.title}`;
+  return null;
+}
+
+/**
+ * Attach {@link denyAskNotice} onto an already-rendered deny/ask `stdout`, for
+ * the harnesses whose human channel is `systemMessage` (claude-code/codex —
+ * `permissionDecision`/`permissionDecisionReason` stay byte-intact, only the
+ * top-level field is added). Every other harness passes `stdout` through
+ * unchanged: Cursor already emits `user_message` natively (respond.ts), Hermes
+ * and cline have no human channel. Deduped via {@link onceExclusive} against
+ * the ~11 sibling-plugin fan-out for one real event (same window as the
+ * sniper reminder / compliance notices).
+ * @param id - Harness id (`ctx.id` from `PreContext`).
+ * @param stdout - The rendered hook response (from {@link module:respond.respond}).
+ * @param prompt - The {@link Prompt} that produced `stdout`.
+ * @param sessionId - Current session id (dedup scope).
+ * @param dir - State-dir for the dedup marker (per-project state dir).
+ * @param now - Event clock (tests pass a fake one).
+ */
+export function withDenyNotice(id: string, stdout: string, prompt: Prompt, sessionId: string, dir: string, now?: number): string {
+  if (id !== "claude-code" && id !== "codex") return stdout;
+  const notice = denyAskNotice(prompt);
+  if (!notice) return stdout;
+  if (!onceExclusive(`deny-notice:${sessionId}:${prompt.title}`, BURST_DEDUP_MS, { now, dir })) return stdout;
+  return attachSystemMessage(stdout, notice);
+}

package/src/runtime/design-cache-resolve.ts

@@ -0,0 +1,51 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fuseHarnessHome, sanitizeSessionId } from "./home-state";
+
+/** `~/.fuse-harness/design-sessions/<sid>` — session-anchored design-state dir. */
+function sessionCacheDir(sid: string, home?: string): string {
+  return join(fuseHarnessHome(home), "design-sessions", sid);
+}
+
+/** True when `dir` already holds the design-agent flag or a `.design-state-*.json` snapshot. */
+function hasDesignState(dir: string): boolean {
+  if (existsSync(join(dir, "design-agent-active"))) return true;
+  try {
+    return readdirSync(dir).some((name) => name.startsWith(".design-state-"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the cache dir the design pipeline (active-agent flag +
+ * `.design-state-<agentId>.json`) should read AND write for this hook call.
+ *
+ * Anchored on the session id, not the invoking process's `cwd`: a design
+ * agent's `SubagentStart` and its later tool writes can run with different
+ * `process.cwd()` values, and a cwd-keyed cache dir then silently misses the
+ * flag/state — every design gate fails open (see MEMORY/LESSON.md).
+ *
+ * Contract (non-regression): `resolved = sessionDirIfPopulated ??
+ * cwdDirIfPopulated ?? sessionDirDefault`. Before this fix the session-keyed
+ * dir never existed, so for every session whose state already lives under
+ * `cwdCacheDir` the FIRST branch is always empty and resolution falls through
+ * to `cwdCacheDir` — byte-identical to the pre-fix value. Only a session with
+ * NO state anywhere (today's silent-fail-open case, e.g. cwd drifted between
+ * `SubagentStart` and the write) diverges, anchoring on the session dir
+ * instead of silently missing the flag. Read and write always resolve through
+ * this same function against the same two inputs, so they can never target
+ * different locations mid-session.
+ * @param sessionId - The hook event's session id (`NormalizedEvent.sessionId`).
+ * @param cwdCacheDir - The legacy, cwd-derived cache dir (`projectLayout(cwd).cacheDir`).
+ * @param home - OS home override (tests only).
+ * @returns The cache dir to pass to the design flag/state/gate functions.
+ */
+export function resolveDesignCacheDir(sessionId: string, cwdCacheDir: string, home?: string): string {
+  const sid = sanitizeSessionId(sessionId);
+  if (!sid) return cwdCacheDir; // no stable session id -> unchanged legacy behavior
+  const sessDir = sessionCacheDir(sid, home);
+  if (hasDesignState(sessDir)) return sessDir;
+  if (hasDesignState(cwdCacheDir)) return cwdCacheDir;
+  return sessDir;
+}

package/src/runtime/design-content-gate.ts

@@ -0,0 +1,95 @@
+/**
+ * @module design-content-gate
+ * PRE content gate for design-system.md — the nominal path (validateDesignSystem
+ * used to run only behind the opt-in Gemini branch, so designSystemValid meant
+ * "a write happened", not "the content is valid"). Split out of
+ * `design-helpers.ts` to keep both files within the SOLID size budget (SRP).
+ * @packageDocumentation
+ */
+import { readFileSync, existsSync } from "node:fs";
+import type { Prompt } from "../prompt/types";
+import type { DesignState } from "../policy/design/state";
+import { deny, validateDesignSystem } from "../policy/design/gates";
+import { citedCorpusRefs, citationJoinsReads } from "../policy/design/corpus";
+import { substituteLiteral } from "./design-files-gate";
+
+/** Inputs for {@link designSystemContentGate} — the PRE write event plus resolved corpus context. */
+interface ContentGateInput {
+  filePath: string;
+  tool: string;
+  content: string;
+  oldString?: string;
+  replaceAll: boolean;
+  state: DesignState;
+  corpusRoot: string;
+  corpusRequired: boolean;
+}
+
+/**
+ * Every content violation of a design-system.md text, GRANULAR (one entry per
+ * unmet requirement and per unread cited reference — so a worsening check can
+ * diff two violation sets): the four hard requirements, plus the citation↔read
+ * jointure when the corpus is delivered.
+ */
+export function designSystemProblems(content: string, reads: readonly string[], corpusRequired: boolean): string[] {
+  const problems = validateDesignSystem(content, corpusRequired);
+  if (corpusRequired) {
+    for (const ref of citedCorpusRefs(content)) {
+      if (!citationJoinsReads(ref, reads)) problems.push(`cited corpus reference never read: ${ref}`);
+    }
+  }
+  return problems;
+}
+
+/** Content check for a design-system.md already on disk (the Gemini create_frontend path). */
+export function checkDesignSystemContent(content: string, reads: readonly string[], corpusRequired: boolean): Prompt | null {
+  const problems = designSystemProblems(content, reads, corpusRequired);
+  return problems.length ? deny(`BLOCKED: design-system.md too generic. Missing: ${problems.join(", ")}.`) : null;
+}
+
+/**
+ * The content a Write/Edit would LEAVE in design-system.md, and the on-disk
+ * original when the file exists (for BOTH tools). Edit reconstructs via
+ * literal substitution (first occurrence, or all under replace_all — the Edit
+ * tool's own semantics, mirroring edit-outcome.ts). Null when unverifiable
+ * (unreadable file or stale old_string) — fail-closed, such an Edit fails at
+ * tool level anyway.
+ */
+function effectiveContents(i: ContentGateInput): { result: string; original: string | null } | null {
+  if (i.tool !== "Edit") {
+    let original: string | null = null;
+    try {
+      if (existsSync(i.filePath)) original = readFileSync(i.filePath, "utf8");
+    } catch {
+      original = null;
+    }
+    return { result: i.content, original };
+  }
+  let disk: string;
+  try {
+    disk = readFileSync(i.filePath, "utf8");
+  } catch {
+    return null;
+  }
+  if (!i.oldString || !disk.includes(i.oldString)) return null;
+  return { result: substituteLiteral(disk, i.oldString, i.content, i.replaceAll), original: disk };
+}
+
+/**
+ * Block only the violations the change INTRODUCES (`problems(result) ⊄
+ * problems(original)`): a legacy design-system.md that predates the doctrine
+ * stays editable — and rewritable — including byte-identically or toward
+ * conformance; a change that adds a NEW problem (or writes an invalid file
+ * from scratch) is blocked.
+ */
+export function designSystemContentGate(i: ContentGateInput): Prompt | null {
+  if (!i.filePath.endsWith("design-system.md")) return null;
+  const pair = effectiveContents(i);
+  if (pair === null) return deny("BLOCKED: cannot verify the edit result (unreadable file or stale old_string). RECOVERY: re-read design-system.md, then retry.");
+  const result = designSystemProblems(pair.result, i.state.corpusReads, i.corpusRequired);
+  if (!result.length) return null;
+  const original = pair.original !== null ? designSystemProblems(pair.original, i.state.corpusReads, i.corpusRequired) : [];
+  const introduced = result.filter((p) => !original.includes(p));
+  if (!introduced.length) return null;
+  return deny(`BLOCKED: design-system.md too generic. Missing: ${introduced.join(", ")}. RECOVERY: fix the content (read cited refs-design references with the Read tool), then retry.`);
+}

package/src/runtime/design-files-gate.ts

@@ -0,0 +1,114 @@
+/**
+ * @module design-files-gate
+ * Gates for multi-file write primitives (Codex `apply_patch`, fanned into
+ * `event.files` by normalize.ts): apply_patch IS the Write tool under Codex,
+ * so the design pipeline must see it. Per op, because `content` means
+ * different things (apply-patch.ts:10-15):
+ *  - add:    content IS the full new document — content-gated like a Write;
+ *  - update: content is the hunk's new side, APPROXIMATE, never the document —
+ *            only content-independent gates run (path, state-file, phase/quota).
+ *            No BLOCKING or DEGRADING validation on this path — promote-only:
+ *            the POST re-reads the real file, a clean content promotes to
+ *            phase 3, a dirty one changes nothing. And it would not bite
+ *            anyway: designSystemValid is consumed ONLY under
+ *            FUSE_DESIGN_GEMINI=1 (off by default — an informational flag),
+ *            and designSystemExists is never read after init;
+ *  - delete: skipped (parity with the sibling applyPatchGate).
+ * One violating file blocks the whole envelope. `htmlCssOnlyGate` NOW applies
+ * here too (owner D2 revised): the two write paths must not diverge on what
+ * the design agent may write — an `apply_patch` `.tsx`/`.astro`/etc. add or
+ * update is just as much a framework-file write as the same content via
+ * `Write`/`Edit`, and letting it through only on this path was an unintended
+ * apply_patch-shaped bypass, not a deliberate relaxation. `uiDesignSkillGate`
+ * and the Gemini create_frontend precondition NO LONGER bypass apply_patch
+ * (fixed): the skill gate is wired in `design.ts` on `event.files` (same
+ * any-agent scope as its Write/Edit call site, before the agentId
+ * early-return); the Gemini precondition is ported into this function,
+ * right below `htmlCssOnlyGate`, gated the same way (opt-in,
+ * FUSE_DESIGN_GEMINI, state.geminiCalls === 0). REMAINING KNOWN GAPS
+ * (documented, still out of scope):
+ * `Design-System.md` (case) escapes every endsWith check, here and on
+ * Write — a real bypass on case-insensitive macOS, not widened now; and
+ * `*** Move to:` (apply-patch.ts:76-79) unconditionally OVERWRITES `cur.path`
+ * on ANY preceding op (`Add File`/`Update File`), so a `*** Update File: a.css`
+ * + `Move to: a.tsx` sequence surfaces here as `filePath` ending in `.tsx`
+ * (correctly blocked — NOT a bypass, verified against the parser). The
+ * un-verified direction is the reverse: `Add File: a.tsx` + `Move to: a.css`
+ * would surface only the PERMITTED destination extension while `f.content`
+ * is real framework code — the source path is never preserved anywhere, and
+ * this gate (like Write's htmlCssOnlyGate) checks only the extension, never
+ * the content's actual syntax. Whether Codex's real grammar allows Move-to
+ * after an Add (vs. Update-only) is unconfirmed; flagged, not fixed here.
+ * Also: the POST side still does NOT run `runDesignChecks` (tsx/jsx/css
+ * warnings) on an `apply_patch` file — `handle-post.ts` keeps `designGate` on
+ * the RAW, un-fanned envelope there (recordPost's apply_patch branch is
+ * promote-only and resolves `design-system.md` via `join(cwd, …)`; routing a
+ * fanned Write/Edit-shaped event through it instead would read `filePath`
+ * UNRESOLVED and risk degrading the state — a real regression, not a
+ * hypothetical one). Restoring the tsx/jsx/css warning would require
+ * resolving relative apply_patch paths AND preserving the promote-only
+ * doctrine inside `recordPost` at the same time — out of scope here, owner
+ * decision.
+ * @packageDocumentation
+ */
+import type { Prompt } from "../prompt/types";
+import type { NormalizedFile } from "./normalize";
+import type { DesignState } from "../policy/design/state";
+import { pluginsWriteGuard } from "../policy/design/corpus";
+import { htmlCssOnlyGate, stateFileGate, geminiEnabled } from "../policy/design/gates";
+import { designSystemWriteGate, htmlCssPipelineGate } from "../policy/design/gates-pipeline";
+import { designSystemContentGate } from "./design-content-gate";
+
+/**
+ * Literal substitution, first occurrence or all — NEVER String.replace's
+ * replacement-string semantics: an agent-controlled new_string of `$&`, `` $` ``,
+ * `$'` or `$$` must be written (and validated) literally, not interpreted as
+ * the matched text (that made the gate validate a document the tool would
+ * never write — the `$&` bypass). Used on both sides: PRE reconstruction and
+ * POST reverse-reconstruction.
+ */
+export function substituteLiteral(s: string, from: string, to: string, all: boolean): string {
+  return all ? s.split(from).join(to) : s.replace(from, () => to);
+}
+
+/**
+ * Gate every file of a multi-file write primitive; the first violation blocks
+ * the envelope. `designSystemFileExists` is caller-computed (`findDesignSystem`
+ * lives in `design-helpers.ts`, which itself imports `substituteLiteral` from
+ * THIS module — importing it back here would cycle) so both write paths
+ * (Write/Edit in `design.ts`, apply_patch here) consume the SAME disk read.
+ */
+export function designFilesGate(
+  files: readonly NormalizedFile[],
+  state: DesignState,
+  pluginsRoot: string,
+  corpusRoot: string,
+  corpusRequired: boolean,
+  cwd: string,
+  designSystemFileExists: boolean,
+): Prompt | null {
+  for (const f of files) {
+    const hit = pluginsWriteGuard(f.filePath, pluginsRoot, cwd) ?? stateFileGate(f.filePath);
+    if (hit) return hit;
+    if (f.op === "delete") continue;
+    const htmlCssHit = htmlCssOnlyGate(f.filePath);
+    if (htmlCssHit) return htmlCssHit;
+    // Parity with design.ts's htmlCssPipelineGate call: SAME verdict for the
+    // SAME file+state on both write paths (Write/Edit vs apply_patch).
+    const pipelineHit = htmlCssPipelineGate(f.filePath, state, designSystemFileExists);
+    if (pipelineHit) return pipelineHit;
+    // apply_patch parity for the Gemini precondition (design.ts:72-74, D2 gap):
+    // same condition, same Prompt shape as the Write/Edit branch — opt-in via
+    // FUSE_DESIGN_GEMINI (OFF by default), so a no-op when Gemini is disabled.
+    if (geminiEnabled() && state.geminiCalls === 0 && /\.(html|css)$/.test(f.filePath)) {
+      return { kind: "block", title: "Design pipeline", reason: "BLOCKED: generate the frontend via create_frontend before hand-writing HTML/CSS.", actions: ["Call mcp__gemini-design__create_frontend first"] };
+    }
+    if (!f.filePath.endsWith("design-system.md")) continue;
+    const gate = designSystemWriteGate(f.filePath, state, corpusRequired)
+      ?? (f.op === "add"
+        ? designSystemContentGate({ filePath: f.filePath, tool: "Write", content: f.content, oldString: undefined, replaceAll: false, state, corpusRoot, corpusRequired })
+        : null);
+    if (gate) return gate;
+  }
+  return null;
+}

package/src/runtime/design-helpers.ts

@@ -0,0 +1,93 @@
+/**
+ * @module design-helpers
+ * Effectful helpers for the design pipeline gate: locate design-system.md and
+ * apply PostToolUse fuse-browser transitions to the design state. Split out of
+ * `design.ts` to keep that file within the SOLID size budget (SRP).
+ * @packageDocumentation
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import type { NormalizedEvent } from "./normalize";
+import { type DesignState, saveDesignState } from "../policy/design/state";
+import { recordNavigate, recordScroll, recordScreenshot, recordValidDesignSystem } from "../policy/design/transitions";
+import { SHOT_TOOLS } from "../policy/design/screenshot-tools";
+import { designSystemProblems } from "./design-content-gate";
+import { substituteLiteral } from "./design-files-gate";
+import { creditRead, creditShellReads } from "./design-read-credit";
+
+export { designSystemContentGate } from "./design-content-gate";
+
+const NAV = "mcp__fuse-browser__browser_navigate";
+const SCROLL = "mcp__fuse-browser__browser_scroll";
+const GEMINI = "mcp__gemini-design__create_frontend";
+
+/** Read design-system.md walking up to 6 parents from `cwd` ("" if absent/unreadable). */
+export function findDesignSystem(cwd: string): string {
+  let dir = cwd;
+  for (let i = 0; i < 6; i++) {
+    const p = join(dir, "design-system.md");
+    if (existsSync(p)) {
+      try {
+        return readFileSync(p, "utf8");
+      } catch {
+        return "";
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "";
+}
+
+/** Apply a PostToolUse fuse-browser transition to the design state. */
+export function recordPost(event: NormalizedEvent, cacheDir: string, state: DesignState, corpusRoot = "", corpusRequired = false, cwd = ""): void {
+  if (SHOT_TOOLS.has(event.tool)) saveDesignState(cacheDir, recordScreenshot(state, corpusRequired));
+  else if (event.tool === NAV) saveDesignState(cacheDir, recordNavigate(state));
+  else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
+  else if (event.tool === GEMINI) saveDesignState(cacheDir, { ...state, geminiCalls: state.geminiCalls + 1 });
+  else if (event.tool === "Read") creditRead(cacheDir, state, corpusRoot, corpusRequired, event.filePath ?? "");
+  // Codex Code Mode exec (`exec_command`, canonicalized to "Bash" by codex-shell-tool.ts).
+  else if (event.tool === "Bash" && event.command) creditShellReads(cacheDir, state, corpusRoot, corpusRequired, event.command);
+  else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) {
+    // Write access ≠ validity, same rule both sides: POST validates only a
+    // zero-problem content and DEGRADES only what PRE would have blocked.
+    const fp = event.filePath ?? "";
+    let content: string;
+    try {
+      content = readFileSync(fp, "utf8");
+    } catch {
+      return;
+    }
+    const problems = designSystemProblems(content, state.corpusReads, corpusRequired);
+    if (!problems.length) {
+      saveDesignState(cacheDir, recordValidDesignSystem(state));
+      return;
+    }
+    // Edit: degrade only on problems the edit INTRODUCED (original reverse-rebuilt
+    // with LITERAL substitution; a deletion edit is not reconstructable — D5).
+    if (event.tool === "Edit" && event.oldString && event.content && content.includes(event.content)) {
+      const original = substituteLiteral(content, event.content, event.oldString, event.input.replace_all === true);
+      const introduced = problems.filter((p) => !designSystemProblems(original, state.corpusReads, corpusRequired).includes(p));
+      if (introduced.length) saveDesignState(cacheDir, { ...state, designSystemValid: false });
+    }
+    // Write / unreconstructable Edit: the PRE gate enforced not-worsening — never degrade here.
+  } else if (event.files) {
+    // Codex apply_patch: PROMOTE-ONLY, never blocking nor degrading — the POST
+    // re-reads the REAL file (the hunk is never the document): clean → phase 3,
+    // dirty → nothing. designSystemValid is only consumed under FUSE_DESIGN_GEMINI.
+    const ds = event.files.find((f) => f.op !== "delete" && f.filePath.endsWith("design-system.md"));
+    if (ds) {
+      const abs = isAbsolute(ds.filePath) ? ds.filePath : join(cwd, ds.filePath);
+      let content: string;
+      try {
+        content = readFileSync(abs, "utf8");
+      } catch {
+        return;
+      }
+      if (!designSystemProblems(content, state.corpusReads, corpusRequired).length) {
+        saveDesignState(cacheDir, recordValidDesignSystem(state));
+      }
+    }
+  }
+}

package/src/runtime/design-lifecycle.ts

@@ -0,0 +1,39 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { detectMode } from "../policy/design/transitions";
+import { initDesignState, saveDesignState, cleanupDesignStates } from "../policy/design/state";
+import { setActiveDesignAgent, clearActiveDesignAgent, activeDesignAgent } from "../policy/design/flag";
+import { promptText } from "./prompt-text";
+
+/**
+ * Handle the design-agent SubagentStart/Stop lifecycle: init the pipeline state +
+ * raise the active flag on start, archive/cleanup + clear the flag on stop.
+ * Returns true when it handled the event (caller should respond and stop).
+ *
+ * `SubagentStop` clears the flag whenever `agent_id` matches the currently
+ * active one, INDEPENDENTLY of `agent_type` on the stop payload — a stop event
+ * is not guaranteed to echo the same `agent_type` string the start event used,
+ * and gating the clear on it left the flag stuck (blocking every subsequent
+ * top-level Write/Edit in the session — see MEMORY/LESSON.md).
+ */
+export function designLifecycle(payload: Record<string, unknown>, cacheDir: string, cwd: string, stamp: string, now: number): boolean {
+  const event = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+  const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+  if (event === "SubagentStop") {
+    if (!agentId || agentId !== activeDesignAgent(cacheDir)) return false;
+    cleanupDesignStates(cacheDir, agentId, stamp, now);
+    clearActiveDesignAgent(cacheDir);
+    return true;
+  }
+  const agentType = typeof payload.agent_type === "string" ? payload.agent_type : "";
+  if (!agentType.includes("design")) return false;
+  if (event === "SubagentStart") {
+    if (!agentId) return false;
+    const dsExists = existsSync(join(cwd, "design-system.md"));
+    const prompt = promptText(payload.prompt);
+    saveDesignState(cacheDir, initDesignState(agentId, detectMode(prompt, dsExists), dsExists));
+    setActiveDesignAgent(cacheDir, agentId);
+    return true;
+  }
+  return false;
+}

package/src/runtime/design-read-credit.ts

@@ -0,0 +1,28 @@
+/**
+ * @module design-read-credit
+ * Shared credit path for a design-corpus/ref read, reused by both the native
+ * `Read` branch and the shell-read branch (Codex Code Mode `exec_command`,
+ * canonicalized to `"Bash"` by `codex-shell-tool.ts`) in
+ * `design-helpers.ts::recordPost`. Split out to keep that file within the
+ * SOLID size budget — zero new parser, zero new store: both callers hit the
+ * SAME `recordCorpusRead`/`recordRead` transitions.
+ * @packageDocumentation
+ */
+import { existsSync } from "node:fs";
+import type { DesignState } from "../policy/design/state";
+import { saveDesignState } from "../policy/design/state";
+import { recordCorpusRead, recordRead } from "../policy/design/transitions";
+import { classifyCorpusRead } from "../policy/design/corpus";
+import { shellReadRefPaths } from "../policy/shell-read-refs";
+
+/** Credit one read path as a corpus read (anchored + on-disk) or a plain ref read. */
+export function creditRead(cacheDir: string, state: DesignState, corpusRoot: string, corpusRequired: boolean, fp: string): void {
+  if (classifyCorpusRead(fp, corpusRoot) && existsSync(fp)) {
+    saveDesignState(cacheDir, recordCorpusRead(state, fp.slice(corpusRoot.length + 1), corpusRequired));
+  } else saveDesignState(cacheDir, recordRead(state, fp, corpusRequired));
+}
+
+/** Credit every `.md` path a read-only shell `command` targets, same path as {@link creditRead}. */
+export function creditShellReads(cacheDir: string, state: DesignState, corpusRoot: string, corpusRequired: boolean, command: string): void {
+  for (const fp of shellReadRefPaths(command)) creditRead(cacheDir, state, corpusRoot, corpusRequired, fp);
+}