@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/solid-file-size-gate.ts

@@ -0,0 +1,58 @@
+/**
+ * PreToolUse file-size deny for the solid scope — the same SOLID ceiling the
+ * core gate chain enforces (`policy/evaluate.ts`), extracted so
+ * `harness hook <id> solid` blocks oversized Write/Edit WITHOUT the core-only
+ * APEX freshness gates (they require explore/research agents that not every
+ * harness runs). Pure and read-only (on-disk read via {@link existingLineCounts},
+ * no session state), so the sibling-plugin fan-out stays idempotent.
+ */
+import { countLines, evaluateFileSize } from "../policy/file-size";
+import { isFileSizeScoped, resolveSolidRefFramework } from "../policy/file-size-scope";
+import { computeEditResultLines } from "../policy/edit-outcome";
+import { resolveMaxLines } from "../config/limits";
+import { existingLineCounts } from "./gate-helpers";
+import type { Prompt } from "../prompt/types";
+
+/**
+ * Deny a Write/Edit whose resulting file would exceed the SOLID line ceiling.
+ * Mirrors `policy/evaluate.ts` exactly: a computable Edit outcome passes when
+ * the result is compliant OR strictly shrinks an already-oversized file; the
+ * block message reports the pre-existing on-disk count for a Write.
+ * @param tool - The tool name (only "Write"/"Edit" are checked).
+ * @param filePath - The written file's absolute path.
+ * @param content - Write: the full new content; Edit: the `new_string` snippet.
+ * @param oldString - Edit only: the `old_string` being replaced.
+ * @param isReplaceAll - Edit only: whether every occurrence is replaced.
+ * @param agentType - Subagent type, when known (Explore/Plan are exempt).
+ * @returns The blocking prompt, or null when compliant or out of scope.
+ */
+export function solidFileSizeGate(
+  tool: string,
+  filePath: string | undefined,
+  content: string | undefined,
+  oldString?: string,
+  isReplaceAll: boolean = false,
+  agentType?: string,
+): Prompt | null {
+  if (tool !== "Write" && tool !== "Edit") return null;
+  if (!filePath || !isFileSizeScoped(filePath)) return null;
+  if (agentType === "Explore" || agentType === "Plan") return null;
+  const { raw: existingLines, content: existingContent } = existingLineCounts(filePath);
+  const incoming = content !== undefined ? countLines(content) : 0;
+  const existing = existingLines ?? 0;
+  const max = resolveMaxLines();
+  const editResult = tool === "Edit" && existingContent !== undefined && content !== undefined
+    ? computeEditResultLines(existingContent, oldString, content, isReplaceAll)
+    : null;
+  if (editResult !== null && (editResult <= max || editResult < existing)) return null;
+  const lines = tool === "Edit" ? (editResult ?? Math.max(incoming, existing)) : incoming || existing;
+  const displayLines = tool === "Write" ? (existingLines ?? lines) : lines;
+  const verdict = evaluateFileSize(lines, max, filePath, resolveSolidRefFramework(filePath), displayLines);
+  if (lines === 0 || verdict.ok) return null;
+  return {
+    kind: "block",
+    title: "SOLID file-size limit",
+    reason: verdict.message ?? "",
+    actions: [`Split into modules under ${verdict.max} lines (Single Responsibility)`, "Then re-run the write"],
+  };
+}

package/src/runtime/solid-pre.ts

@@ -0,0 +1,53 @@
+/**
+ * Solid-scope PreToolUse outcome: the file-size deny ({@link solidFileSizeGate})
+ * first — rendered via {@link respond} so every harness gets its native shape
+ * (Kimi finally receives a real `hookSpecificOutput` deny instead of a leaked
+ * Claude envelope) — then the ported Go/Python interface-location check
+ * ({@link validateSolidGate}, kept byte-identical for claude-code/codex).
+ * Owns the whole solid-scope branch so `handle-pre` stays a dispatcher and the
+ * branch NEVER falls through to the core APEX/SOLID gate chain: core-guards
+ * owns it, so falling through would run `gate()` twice per edit when both
+ * plugins wire PreToolUse Write|Edit (duplicate denies + added latency). For
+ * the same reason the file-size gate itself ABSTAINS when core-guards is
+ * installed ({@link coreGuardsWired}): one tool-call, one deny, whoever fires.
+ */
+import { dirname } from "node:path";
+import { withDenyNotice } from "./deny-notice";
+import { respond } from "./respond";
+import { validateSolidGate } from "./lifecycle";
+import { solidFileSizeGate } from "./solid-file-size-gate";
+import { coreGuardsWired } from "./core-guards-wired";
+import type { NormalizedEvent } from "./normalize";
+import type { HandleOutcome } from "./handle-types";
+
+/**
+ * Run the solid-scope PreToolUse gates and render the native hook outcome.
+ * @param id - Harness id (selects the response shape via {@link respond}).
+ * @param event - The normalized hook event.
+ * @param file - Session track file (the deny-notice state derives from its dir).
+ * @param now - Current time in ms.
+ * @param env - Environment for the core-guards wiring probe (injectable).
+ * @returns The hook outcome: file-size deny, Go/Python deny, or allow.
+ */
+export function solidScopeOutcome(
+  id: string,
+  event: NormalizedEvent,
+  file: string,
+  now: number,
+  env: Record<string, string | undefined> = process.env,
+): HandleOutcome {
+  const prompt = coreGuardsWired(id, env)
+    ? null
+    : solidFileSizeGate(
+      event.tool,
+      event.filePath,
+      event.content,
+      event.oldString,
+      event.input.replace_all === true,
+      event.agentType,
+    );
+  if (prompt) {
+    return { stdout: withDenyNotice(id, respond(id, prompt), prompt, event.sessionId, dirname(file), now), exit: 0 };
+  }
+  return { stdout: validateSolidGate(event.tool, event.filePath ?? "", event.content ?? ""), exit: 0 };
+}

package/src/runtime/storage.ts

@@ -0,0 +1,9 @@
+import { projectLayout } from "../config/layout";
+
+/**
+ * The project's single state dir (`<root>/.harness`) — neutral + harness-agnostic,
+ * derived from {@link projectLayout}. (Was the per-harness `.claude/harness`.)
+ */
+export function harnessStateDir(root: string): string {
+  return projectLayout(root).stateDir;
+}

package/src/statusline/colors.ts

@@ -0,0 +1,31 @@
+import { COLOR_THRESHOLDS } from "./constants";
+
+/** A text-decorating function. */
+export type ColorFn = (text: string) => string;
+
+const ansi = (code: string): ColorFn => (text) => `\x1b[${code}m${text}\x1b[0m`;
+const ansi256 = (code: number): ColorFn => (text) => `\x1b[38;5;${code}m${text}\x1b[0m`;
+
+/** Forced ANSI palette (every entry is a colorizer, plus reset + support flag). */
+export interface Palette {
+  blue: ColorFn; cyan: ColorFn; green: ColorFn; yellow: ColorFn; red: ColorFn;
+  magenta: ColorFn; white: ColorFn; gray: ColorFn; purple: ColorFn; orange: ColorFn;
+  brightRed: ColorFn; brightYellow: ColorFn; brightGreen: ColorFn;
+  bold: ColorFn; dim: ColorFn; reset: string; isSupported: boolean;
+}
+
+/** Forced ANSI color helpers (ignore TTY detection). */
+export const colors: Palette = {
+  blue: ansi("0;34"), cyan: ansi("0;36"), green: ansi("0;32"),
+  yellow: ansi("0;33"), red: ansi("0;31"), magenta: ansi("0;35"),
+  white: ansi("0;37"), gray: ansi256(240), purple: ansi256(135), orange: ansi256(208),
+  brightRed: ansi("1;91"), brightYellow: ansi("1;93"), brightGreen: ansi("1;92"),
+  bold: ansi("1"), dim: ansi("2"), reset: "\x1b[0m", isSupported: true,
+};
+
+/** Color `text` by threshold: green < WARNING <= yellow < CRITICAL <= red. */
+export function progressiveColor(value: number, text: string): string {
+  if (value >= COLOR_THRESHOLDS.CRITICAL) return colors.brightRed(text);
+  if (value >= COLOR_THRESHOLDS.WARNING) return colors.brightYellow(text);
+  return colors.green(text);
+}

package/src/statusline/constants.ts

@@ -0,0 +1,17 @@
+/** Time interval constants (ms). */
+export const TIME_INTERVALS = { MINUTE_MS: 60_000, HOUR_MS: 3_600_000 } as const;
+
+/** Percentage thresholds for progressive coloring. */
+export const COLOR_THRESHOLDS = { WARNING: 70, CRITICAL: 90 } as const;
+
+/** Fill/empty glyphs per progress-bar style. */
+export const PROGRESS_CHARS = {
+  blocks: { fill: "█", empty: "░" },
+  bars: { fill: "▰", empty: "▱" },
+} as const;
+
+/** Defaults for {@link generateProgressBar}. */
+export const PROGRESS_BAR_DEFAULTS = { STYLE: "blocks", LENGTH: 10 } as const;
+
+/** 9 gradient blocks from empty to full. */
+export const GRADIENT_BLOCKS = [" ", "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"] as const;

package/src/statusline/formatters.ts

@@ -0,0 +1,54 @@
+import { basename } from "node:path";
+import { TIME_INTERVALS } from "./constants";
+
+/** Format a path: truncated (default), full, relative (~), or basename. */
+export function formatPath(
+  path: string,
+  style: "truncated" | "full" | "relative" | "basename" = "truncated",
+): string {
+  const home = process.env.HOME || "";
+  const isUnderHome = home !== "" && path.startsWith(home);
+  const withTilde = isUnderHome ? path.replace(home, "~") : path;
+  const parts = withTilde.split("/").filter(Boolean);
+  const name = parts[parts.length - 1] || withTilde;
+  switch (style) {
+    case "full": return path;
+    case "basename": return name;
+    case "relative": return withTilde;
+    default:
+      if (isUnderHome && parts.length > 2) return `~/../${name}`;
+      if (isUnderHome) return withTilde;
+      if (parts.length > 3) return `/../${name}`;
+      return withTilde;
+  }
+}
+
+/** Basename of a path. */
+export function formatBasename(path: string): string {
+  return basename(path);
+}
+
+/** Humanize a remaining duration in ms (e.g. "2h - 5m"). */
+export function formatTimeLeft(ms: number): string {
+  if (ms <= 0) return "0m";
+  const dayMs = TIME_INTERVALS.HOUR_MS * 24;
+  const days = Math.floor(ms / dayMs);
+  const hours = Math.floor((ms % dayMs) / TIME_INTERVALS.HOUR_MS);
+  const minutes = Math.floor((ms % TIME_INTERVALS.HOUR_MS) / TIME_INTERVALS.MINUTE_MS);
+  if (days > 0 && hours > 0) return `${days}d - ${hours}h`;
+  if (days > 0) return `${days}d`;
+  if (hours > 0 && minutes > 0) return `${hours}h - ${minutes}m`;
+  if (hours > 0) return `${hours}h`;
+  return `${minutes}m`;
+}
+
+/** Format a token count as "12K" (or "12.3K" with decimals). */
+export function formatTokens(tokens: number, showDecimals = false): string {
+  const k = tokens / 1000;
+  return showDecimals ? `${k.toFixed(1)}K` : `${Math.round(k)}K`;
+}
+
+/** Format a cost as "$1.23". */
+export function formatCost(cost: number, decimals = 2): string {
+  return `$${cost.toFixed(decimals)}`;
+}

package/src/statusline/index.ts

@@ -0,0 +1,4 @@
+export * from "./constants";
+export * from "./colors";
+export * from "./formatters";
+export * from "./progress-bar";

package/src/statusline/progress-bar.ts

@@ -0,0 +1,46 @@
+import { GRADIENT_BLOCKS, PROGRESS_BAR_DEFAULTS, PROGRESS_CHARS } from "./constants";
+import { progressiveColor } from "./colors";
+
+/** Options for {@link generateProgressBar}. */
+export interface ProgressBarOptions {
+  style?: keyof typeof PROGRESS_CHARS;
+  length?: number;
+  useProgressiveColor?: boolean;
+  showPercentage?: boolean;
+}
+
+const clampPct = (p: number): number => Math.max(0, Math.min(100, Number.isNaN(p) ? 0 : p));
+
+/** Render a fill/empty progress bar. */
+export function generateProgressBar(percentage: number, options: ProgressBarOptions = {}): string {
+  const {
+    style = PROGRESS_BAR_DEFAULTS.STYLE, length = PROGRESS_BAR_DEFAULTS.LENGTH,
+    useProgressiveColor = false, showPercentage = false,
+  } = options;
+  const pct = clampPct(percentage);
+  const filled = Math.round((pct / 100) * length);
+  const empty = Math.max(0, length - filled);
+  const chars = PROGRESS_CHARS[style];
+  let bar = chars.fill.repeat(filled) + chars.empty.repeat(empty);
+  if (useProgressiveColor) bar = progressiveColor(pct, bar);
+  if (showPercentage) {
+    const pctText = `${Math.round(pct)}%`;
+    bar += ` ${useProgressiveColor ? progressiveColor(pct, pctText) : pctText}`;
+  }
+  return bar;
+}
+
+/** Render a fine-grained gradient bar (sub-block resolution). */
+export function generateGradientBar(percentage: number, length = 10): string {
+  const pct = clampPct(percentage);
+  const exact = (pct / 100) * length;
+  const full = Math.floor(exact);
+  const remainder = exact - full;
+  let bar = GRADIENT_BLOCKS[8].repeat(full);
+  if (full < length && remainder > 0) {
+    bar += GRADIENT_BLOCKS[Math.floor(remainder * 8)] ?? "";
+  }
+  const remaining = length - bar.length;
+  if (remaining > 0) bar += " ".repeat(remaining);
+  return progressiveColor(pct, bar);
+}

package/src/tracking/codex-post-failure.ts

@@ -0,0 +1,73 @@
+/**
+ * @module codex-post-failure
+ * Codex has no native `PostToolUseFailure` event (Claude Code's own failure
+ * signal, ported in `src/runtime/lifecycle/tool-failure.ts`'s `logToolFailure`)
+ * — every Codex tool outcome, success or failure, arrives on the SAME
+ * `PostToolUse` event. This infers a failure from the regular payload's
+ * `tool_result`/`tool_response` and journals it into the EXISTING one-shot
+ * failure tally ({@link recordFailure}) — no new store, no new gate.
+ *
+ * Design choice (fail-open): a payload this module cannot positively prove
+ * failed — `null`/`undefined`, a non-object shape, or any parse exception —
+ * classifies as `"success"` (ignored), NEVER `"failure"`. Many legitimate
+ * successful tool calls return no structured result at all (see
+ * `handle-post.ts`'s `spawn_agent` `tool_response: { nickname: "scout" }`),
+ * so treating "can't tell" as a failure would flood the tally with false
+ * positives. Only an EXPLICIT signal (non-zero exit, an error field) counts.
+ * @packageDocumentation
+ */
+import { recordFailure } from "./one-shot-failure";
+import type { OneShotOpts } from "./one-shot";
+
+/** Truthy interruption markers across harness result shapes (parity `tool-failure.ts`'s `is_interrupt`). */
+const INTERRUPT_KEYS = ["is_interrupt", "isInterrupted", "interrupted", "aborted", "cancelled", "canceled"];
+
+/** True when `result` carries any known interruption marker — an interruption is never a failure. */
+function isInterruption(result: Record<string, unknown>): boolean {
+  return INTERRUPT_KEYS.some((k) => result[k] === true);
+}
+
+/** True when `result` reports a non-zero exit code (Bash-shaped tool result). */
+function hasNonZeroExit(result: Record<string, unknown>): boolean {
+  const exit = result.exit_code ?? result.exitCode;
+  return typeof exit === "number" && exit !== 0;
+}
+
+/** True when `result` carries an explicit error signal (`error`, `is_error`/`isError`, or `success: false`). */
+function hasErrorField(result: Record<string, unknown>): boolean {
+  if (result.success === false) return true;
+  if (result.is_error === true || result.isError === true) return true;
+  const err = result.error;
+  return typeof err === "string" ? err.length > 0 : err !== undefined && err !== null;
+}
+
+/**
+ * Classify a Codex PostToolUse `tool_response`/`tool_result` payload.
+ * Fail-open (see module doc): unprovable shapes resolve to `"success"`,
+ * never `"failure"`, and this NEVER throws.
+ * @param result - The raw result value off the payload (any shape).
+ * @returns `"success"` | `"failure"` | `"interrupted"`.
+ */
+export function classifyCodexOutcome(result: unknown): "success" | "failure" | "interrupted" {
+  try {
+    if (result === null || typeof result !== "object" || Array.isArray(result)) return "success";
+    const r = result as Record<string, unknown>;
+    if (isInterruption(r)) return "interrupted";
+    if (hasNonZeroExit(r) || hasErrorField(r)) return "failure";
+    return "success";
+  } catch {
+    return "success";
+  }
+}
+
+/**
+ * Journal a Codex tool failure into the existing one-shot failure tally.
+ * No-op for `"success"`/`"interrupted"` — only a genuine failure is recorded.
+ * @param tool - The tool name.
+ * @param result - The raw PostToolUse result payload.
+ * @param opts - Clock + state dir (+ optional session id), forwarded as-is to {@link recordFailure}.
+ */
+export function recordCodexPostFailure(tool: string, result: unknown, opts: OneShotOpts): void {
+  if (classifyCodexOutcome(result) !== "failure") return;
+  recordFailure(tool, opts);
+}

package/src/tracking/index.ts

@@ -0,0 +1,2 @@
+export * from "./session-state";
+export * from "./store";

package/src/tracking/integrity.ts

@@ -0,0 +1,99 @@
+/**
+ * @module integrity
+ * HMAC-SHA256 tamper-evident wrapping for {@link SessionTrack}.
+ *
+ * Failure policy: ONLY a MAC mismatch causes fail-closed (returns null).
+ * The nonce is included in the signed payload and written to disk for advisory
+ * diagnostics, but is NOT checked during verification — concurrent hook
+ * invocations (PostToolUse, SubagentStop, …) legitimately load the same
+ * envelope after the nonce watermark advances; a monotonic check would trigger
+ * spurious fail-closed behaviour mid-session.
+ *
+ * The machine key is readable by the same agent process, so this deters naive
+ * out-of-band tampering — not a determined re-sign. Item B (transcript-grounded
+ * freshness) is the primary guarantee.
+ * @packageDocumentation
+ */
+import { createHmac, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fuseHarnessHome } from "../runtime/home-state";
+import type { SessionTrack } from "./session-state";
+
+const HARNESS_DIR = fuseHarnessHome();
+const KEY_PATH = join(HARNESS_DIR, ".key");
+const NONCE_PATH = join(HARNESS_DIR, ".nonce");
+
+/** Signed envelope wrapping a JSON-serialised {@link SessionTrack}. */
+export interface TrackEnvelope {
+  /** JSON-serialised SessionTrack. */
+  data: string;
+  /** Advisory timestamp (Date.now() at sign time); embedded in the MAC. */
+  nonce: number;
+  /** HMAC-SHA256 hex digest over `"${nonce}:${data}"`. */
+  mac: string;
+}
+
+/** Load (or create on first use) the per-machine HMAC key stored at mode 0600. */
+export function loadOrCreateKey(): string {
+  mkdirSync(HARNESS_DIR, { recursive: true });
+  if (existsSync(KEY_PATH)) return readFileSync(KEY_PATH, "utf8").trim();
+  // Race-tolerant creation ("wx" crowns ONE creator): before, N concurrent
+  // first-time processes (virgin home — CI) each signed with their OWN key.
+  const candidate = randomBytes(32).toString("hex");
+  try {
+    writeFileSync(KEY_PATH, candidate, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    return candidate;
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+  }
+  // The winner's 64-byte write is one write(2); bounded re-reads cover the gap.
+  for (let i = 0; i < 5; i++) {
+    const existing = readFileSync(KEY_PATH, "utf8").trim();
+    if (existing) return existing;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+  }
+  const key = readFileSync(KEY_PATH, "utf8").trim();
+  if (!key) throw new Error("fuse: empty .key after write contention");
+  return key;
+}
+
+/**
+ * Persist the last-seen nonce for advisory diagnostics (mode 0600).
+ * Never read during {@link verifyTrack} — see module JSDoc for rationale.
+ */
+export function writeLastNonce(nonce: number): void {
+  mkdirSync(HARNESS_DIR, { recursive: true });
+  writeFileSync(NONCE_PATH, String(nonce), { encoding: "utf8", mode: 0o600 });
+}
+
+/** Compute HMAC-SHA256 over `"${nonce}:${data}"` (nonce: envelope number or journal per-line string). */
+export function computeMac(key: string, data: string, nonce: number | string): string {
+  return createHmac("sha256", key).update(`${nonce}:${data}`).digest("hex");
+}
+
+/**
+ * Sign a {@link SessionTrack} into a tamper-evident envelope. The nonce
+ * (`Date.now()`) is embedded in the MAC to bind the timestamp to the payload.
+ */
+export function signTrack(track: SessionTrack): TrackEnvelope {
+  const key = loadOrCreateKey();
+  const data = JSON.stringify(track);
+  const nonce = Date.now();
+  return { data, nonce, mac: computeMac(key, data, nonce) };
+}
+
+/**
+ * Verify a {@link TrackEnvelope}. Returns the parsed {@link SessionTrack} on
+ * success, or `null` ONLY on MAC mismatch / parse failure (fail-closed on
+ * tampering). The nonce is NOT checked — see module JSDoc.
+ */
+export function verifyTrack(envelope: TrackEnvelope): SessionTrack | null {
+  try {
+    const key = loadOrCreateKey();
+    if (envelope.mac !== computeMac(key, envelope.data, envelope.nonce)) return null;
+    return JSON.parse(envelope.data) as SessionTrack;
+  } catch {
+    return null;
+  }
+}

package/src/tracking/one-shot-dedup.ts

@@ -0,0 +1,34 @@
+/**
+ * @module one-shot-dedup
+ * Burst-dedup guard for the one-shot metric ({@link module:one-shot}).
+ *
+ * ONE Claude tool event fans out to ~11 sibling plugin-hook processes, each
+ * calling {@link recordOneShot}; without this the metric would count a single
+ * deny/allow ~11×. Reuses the proven {@link oncePerWindow} cooldown sidecar:
+ * the FIRST process in the {@link module:burst-window} window mutates the
+ * metric, the rest skip. The dedup key includes the outcome KIND (deny-title vs
+ * allow) so a deny and its later fix — different kinds — are never folded into
+ * each other. No `sessionId` → always the first (mono-process + unit-test
+ * parity; a burst can only exist when a real session drives the fan-out).
+ * @packageDocumentation
+ */
+import { oncePerWindow } from "../runtime/inject-dedup";
+import { BURST_DEDUP_MS } from "../runtime/burst-window";
+
+/** Opts needed to decide + persist a burst claim (a structural subset of `OneShotOpts`). */
+export interface BurstOpts { now: number; dir: string; sessionId?: string; }
+
+/**
+ * True when this `(op, kind)` is the FIRST of its burst for the session — the
+ * process that should actually mutate the metric. Sibling processes firing the
+ * SAME event within {@link BURST_DEDUP_MS} return false and skip the write.
+ * @param op - Content-free operation key ({@link denyHash}("op", …)).
+ * @param kind - Outcome discriminator (`deny:<title>` or `allow`).
+ * @param opts - Clock + state dir + optional session id.
+ * @returns `true` to apply the record, `false` to skip (already counted).
+ */
+export function burstFirst(op: string, kind: string, opts: BurstOpts): boolean {
+  const sid = opts.sessionId?.trim();
+  if (!sid) return true;
+  return oncePerWindow(`oneshot:${sid}:${op}:${kind}`, BURST_DEDUP_MS, { now: opts.now, dir: opts.dir });
+}

package/src/tracking/one-shot-failure.ts

@@ -0,0 +1,42 @@
+/**
+ * @module one-shot-failure
+ * PostToolUseFailure tally for the one-shot sidecar. A pure per-tool counter
+ * ({@link applyFailure}) plus its burst-deduped IO writer ({@link recordFailure}),
+ * kept out of {@link module:one-shot-store} so that file stays under the SOLID
+ * size limit. Reuses the SAME sidecar, prune window, and burst-dedup as
+ * {@link module:one-shot} — failures never touch the deny/allow gate rate.
+ * @packageDocumentation
+ */
+import { join } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { pruneState, type OneShotState } from "./one-shot-store";
+import { SIDECAR, WINDOW_MS, loadState, type OneShotOpts } from "./one-shot";
+import { burstFirst } from "./one-shot-dedup";
+
+/**
+ * Bump the per-tool failure count. Orthogonal to gates/pending, so it can never
+ * distort the one-shot rate.
+ * @param s - Current state.
+ * @param tool - The failing tool name (`unknown` when absent).
+ * @param now - Clock.
+ * @returns The next state with `failures[tool]` incremented.
+ */
+export function applyFailure(s: OneShotState, tool: string, now: number): OneShotState {
+  return { ...s, failures: { ...(s.failures ?? {}), [tool]: (s.failures?.[tool] ?? 0) + 1 }, updatedAt: now };
+}
+
+/**
+ * Persist a PostToolUseFailure into the one-shot sidecar, burst-deduped across the
+ * ~11-process fan-out (same window/store as {@link recordOneShot}). Fail-safe: a
+ * write error never propagates out of the hook.
+ * @param tool - The failing tool name.
+ * @param opts - Clock + state dir + optional session id (arms the burst dedup).
+ */
+export function recordFailure(tool: string, opts: OneShotOpts): void {
+  try {
+    if (!burstFirst(`fail:${tool}`, "failure", opts)) return;
+    const path = join(opts.dir, SIDECAR);
+    const next = applyFailure(pruneState(loadState(path), opts.now, WINDOW_MS), tool, opts.now);
+    atomicWrite(path, JSON.stringify(next));
+  } catch { /* fail-safe: metrics never break the hook */ }
+}

package/src/tracking/one-shot-store.ts

@@ -0,0 +1,95 @@
+/**
+ * @module one-shot-store
+ * Pure, IO-free state model for the per-gate one-shot metric ({@link module:one-shot}).
+ *
+ * Measures the owner's "precision / one-shot" criterion: per gate (keyed by the
+ * block prompt's title) how many times it DENIED and how many were later cleared
+ * by an allow of the same operation (a fix). Globally: `firstTry` (a gateable op
+ * that passed with NO prior deny = one-shot) vs `corrected` (passed after a deny).
+ * The store ({@link module:one-shot}) loads, persists, and wires this into the gate.
+ * @packageDocumentation
+ */
+
+/** Per-gate tally: total denies, denies later fixed by an allow, last-seen clock. */
+export interface GateStat { denies: number; corrected: number; lastTs: number; }
+
+/** One open deny awaiting its fix: the blocking gate title and when it landed. */
+export interface Pending { title: string; ts: number; }
+
+/** Aggregate one-shot state (a sidecar JSON). `pending` links a deny to its later allow. */
+export interface OneShotState {
+  gates: Record<string, GateStat>;
+  firstTry: number;
+  corrected: number;
+  pending: Record<string, Pending>;
+  updatedAt: number;
+  /** Per-tool PostToolUseFailure tally. Optional — absent in pre-0.1.57 sidecars (additive, back-compatible). */
+  failures?: Record<string, number>;
+}
+
+/** A fresh, empty state — always spread (`{ ...EMPTY }`) so the const is never shared. */
+export const EMPTY: OneShotState = { gates: {}, firstTry: 0, corrected: 0, pending: {}, updatedAt: 0 };
+
+/**
+ * Drop stale data: whole-state idle reset past the window, else per-entry prune of
+ * gates/pending older than `windowMs`. Keeps the "7d" window honest, bounds size.
+ */
+export function pruneState(s: OneShotState, now: number, windowMs: number): OneShotState {
+  if (now - s.updatedAt >= windowMs) return { ...EMPTY };
+  const gates: Record<string, GateStat> = {};
+  for (const [k, g] of Object.entries(s.gates)) if (now - g.lastTs < windowMs) gates[k] = g;
+  const pending: Record<string, Pending> = {};
+  for (const [k, p] of Object.entries(s.pending)) if (now - p.ts < windowMs) pending[k] = p;
+  return { ...s, gates, pending };
+}
+
+/**
+ * Record a deny for gate `title` on operation `op` (content-free tool identity):
+ * bump the gate's deny count and mark `op` pending for a later fix.
+ */
+export function applyDeny(s: OneShotState, title: string, op: string, now: number): OneShotState {
+  const g = s.gates[title] ?? { denies: 0, corrected: 0, lastTs: 0 };
+  return {
+    ...s,
+    gates: { ...s.gates, [title]: { denies: g.denies + 1, corrected: g.corrected, lastTs: now } },
+    pending: { ...s.pending, [op]: { title, ts: now } },
+    updatedAt: now,
+  };
+}
+
+/**
+ * Record an allow for a gateable `op`. A non-gateable allow (Read/Task/MCP) leaves
+ * state untouched — it never counts and never clears a pending deny. Otherwise: a
+ * pending deny → `corrected` (a fix, credited to the blocking gate); no pending →
+ * `firstTry` (one-shot).
+ */
+export function applyAllow(s: OneShotState, op: string, now: number, gateable: boolean): OneShotState {
+  if (!gateable) return s;
+  const pend = s.pending[op];
+  if (pend) {
+    const g = s.gates[pend.title] ?? { denies: 0, corrected: 0, lastTs: 0 };
+    const { [op]: _drop, ...pending } = s.pending;
+    return {
+      ...s,
+      gates: { ...s.gates, [pend.title]: { ...g, corrected: g.corrected + 1, lastTs: now } },
+      corrected: s.corrected + 1, pending, updatedAt: now,
+    };
+  }
+  return gateable ? { ...s, firstTry: s.firstTry + 1, updatedAt: now } : s;
+}
+
+/**
+ * Compact injectable summary (one line); "" when there is nothing to report.
+ * @returns e.g. `gates 7d: 88% one-shot (44/50 clean); SOLID file-size limit 4den/3fix`.
+ */
+export function formatSummary(s: OneShotState): string {
+  const keys = Object.keys(s.gates);
+  const total = s.firstTry + s.corrected;
+  if (keys.length === 0 && total === 0) return "";
+  const head = total > 0 ? `${Math.round((s.firstTry / total) * 100)}% one-shot (${s.firstTry}/${total} clean)` : "no clean pass yet";
+  const parts = keys
+    .map((k) => ({ k, g: s.gates[k]! }))
+    .sort((a, b) => b.g.denies - a.g.denies)
+    .map(({ k, g }) => `${k} ${g.denies}den/${g.corrected}fix`);
+  return `gates 7d: ${head}${parts.length ? `; ${parts.join("; ")}` : ""}`;
+}