@fusengine/harness 0.1.89 → 0.1.91

package/src/runtime/pre-allow.ts

@@ -0,0 +1,97 @@
+/**
+ * PreToolUse ALLOW-path response assembly. Reached only after every gate
+ * allowed (a deny/ask already returned upstream), so nothing here can block nor
+ * override a decision. Combines the Python-parity pass notice (systemMessage)
+ * with the single most-specific decision-time lesson (additionalContext), plus
+ * a compact "evidence fresh" compliance notice on the first APEX-scoped code
+ * Write/Edit that clears the freshness gate.
+ */
+import { designPassNotice } from "../policy/design/gates";
+import { resolveCorpusRoot } from "../policy/design/corpus";
+import { lessonFor } from "../policy/lessons/lesson-gate";
+import { lessonsFileFor } from "./lifecycle/lessons/state";
+import { projectRoot } from "../util/project-root";
+import { oncePerWindow } from "./inject-dedup";
+import { defaultStateDir } from "./paths";
+import { isApexScoped } from "./gate-helpers";
+import { REQUIRED_AGENTS, DEFAULT_WINDOW_MS } from "./gate";
+import { agentsFreshInTrack } from "../freshness/agent-evidence-record";
+import { loadTrack } from "../tracking/store";
+import { evidenceFreshNotice } from "./notices";
+import { respond } from "./respond";
+import type { NormalizedEvent } from "./normalize";
+import type { HandleOutcome } from "./handle";
+import type { Prompt } from "../prompt/types";
+
+/** Session-track + clock inputs the "evidence fresh" notice needs (absent = feature off, e.g. no caller-provided track file). */
+export interface EvidenceCheck {
+  /** Session track file path (same one the gate chain reads/writes). */
+  trackFile: string;
+  /** APEX freshness window in ms (defaults to {@link DEFAULT_WINDOW_MS}). */
+  windowMs?: number;
+  /** Event clock. */
+  now: number;
+}
+
+/**
+ * `✓ evidence fresh (explore+research)` for the first APEX-scoped Write/Edit
+ * that finds explore-codebase + research-expert evidence still within the
+ * freshness window — the user-visible confirmation for a gate that, until now,
+ * only ever spoke up when it BLOCKED. Deduped once per freshness window per
+ * session (same window the gate itself re-validates on), so it reads as "just
+ * confirmed", not a notice on every edit. Returns null for anything but a
+ * Write/Edit on an APEX-scoped path, or when evidence isn't fresh.
+ */
+async function freshEvidenceNotice(event: NormalizedEvent, evidence: EvidenceCheck, cwd: string): Promise<string | null> {
+  if ((event.tool !== "Write" && event.tool !== "Edit") || !isApexScoped(event.filePath)) return null;
+  const windowMs = evidence.windowMs ?? DEFAULT_WINDOW_MS;
+  const track = await loadTrack(evidence.trackFile);
+  if (!agentsFreshInTrack(track, REQUIRED_AGENTS, windowMs, evidence.now)) return null;
+  if (!oncePerWindow(`evidence-fresh:${event.sessionId}`, windowMs, { now: evidence.now, dir: defaultStateDir(cwd) })) return null;
+  return evidenceFreshNotice();
+}
+
+/**
+ * Build the native outcome for a PreToolUse call that passed every gate: emit a
+ * user-visible pass notice (once per allowed call), the "evidence fresh"
+ * compliance notice when applicable, and, when its TRIGGERS match this call,
+ * the one cooldown-guarded decision-time lesson. All 3 channels ride a single
+ * response (lesson → additionalContext, notices → systemMessage).
+ * @param id - Harness id for {@link respond}.
+ * @param event - The normalized PreToolUse event.
+ * @param payload - The raw hook payload (for `agent_id`).
+ * @param mcpDir - MCP state dir backing the pass-notice throttle.
+ * @param cwd - Project root (lesson file + notice scope).
+ * @param evidence - Session track + clock for the "evidence fresh" notice (omit to disable it).
+ * @returns The native hook outcome (empty stdout when nothing to emit).
+ */
+export async function allowOutcome(
+  id: string,
+  event: NormalizedEvent,
+  payload: Record<string, unknown>,
+  mcpDir: string,
+  cwd: string,
+  evidence?: EvidenceCheck,
+  corpusRoot?: string,
+): Promise<HandleOutcome> {
+  const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+  const notice = designPassNotice({
+    agentId,
+    tool: event.tool, filePath: event.filePath ?? "", content: event.content ?? "",
+    url: typeof event.input.url === "string" ? event.input.url : "", phase: "pre",
+    corpusMissing: agentId !== "" && (corpusRoot ?? resolveCorpusRoot()) === "",
+  }, mcpDir);
+  const lesson = lessonFor(event.tool, event.input, { file: lessonsFileFor(projectRoot(cwd)), once: oncePerWindow });
+  const evidenceNotice = evidence ? await freshEvidenceNotice(event, evidence, cwd) : null;
+  if (lesson) {
+    const userMessage = [notice?.userMessage, evidenceNotice].filter(Boolean).join("\n") || undefined;
+    const merged = userMessage ? { ...lesson, userMessage } : lesson;
+    return { stdout: respond(id, merged, event.eventName ?? "PreToolUse"), exit: 0 };
+  }
+  if (evidenceNotice) {
+    const userMessage = [notice?.userMessage, evidenceNotice].filter(Boolean).join("\n");
+    const prompt: Prompt = notice ? { ...notice, userMessage } : { kind: "inform", title: "APEX freshness", reason: "", userMessage };
+    return { stdout: respond(id, prompt, event.eventName ?? "PreToolUse"), exit: 0 };
+  }
+  return { stdout: notice ? respond(id, notice, event.eventName ?? "PreToolUse") : "", exit: 0 };
+}

package/src/runtime/precommit.ts

@@ -0,0 +1,60 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Prompt } from "../prompt/types";
+
+const TIMEOUT_MS = 30_000;
+const ESLINT_CONFIGS: readonly string[] = [".eslintrc.json", ".eslintrc.js", "eslint.config.js", "eslint.config.mjs", "eslint.config.ts"];
+const PRETTIER_CONFIGS: readonly string[] = [".prettierrc", ".prettierrc.json", "prettier.config.js"];
+
+/** Run a linter; returns its error output, or "" if it passed / spawn-failed / timed out (fail-open). */
+function runLinter(file: string, args: string[], label: string, cwd: string): string {
+  try {
+    execFileSync(file, args, { cwd, timeout: TIMEOUT_MS, stdio: ["ignore", "pipe", "pipe"] });
+    return "";
+  } catch (e: unknown) {
+    const err = e as { status?: number | null; stdout?: Buffer; stderr?: Buffer };
+    if (err.status === undefined || err.status === null) return "";
+    const out = (err.stdout?.toString() ?? err.stderr?.toString() ?? "").trim();
+    return out ? `[${label}]\n${out}` : "";
+  }
+}
+
+/** Run the applicable linters in `cwd`, returning a block of errors per failing tool. */
+function collectErrors(cwd: string): string[] {
+  const has = (f: string): boolean => existsSync(join(cwd, f));
+  const errors: string[] = [];
+  if (has("package.json")) {
+    if (ESLINT_CONFIGS.some(has)) {
+      const m = runLinter("bunx", ["eslint", ".", "--max-warnings", "0"], "ESLint", cwd);
+      if (m) errors.push(m);
+    }
+    if (has("tsconfig.json")) {
+      const m = runLinter("bunx", ["tsc", "--noEmit"], "TypeScript", cwd);
+      if (m) errors.push(m);
+    }
+    if (PRETTIER_CONFIGS.some(has)) {
+      const m = runLinter("bunx", ["prettier", "--check", "."], "Prettier", cwd);
+      if (m) errors.push(m);
+    }
+  }
+  if (has("requirements.txt") || has("pyproject.toml")) {
+    const m = runLinter("ruff", ["check", "."], "Ruff", cwd);
+    if (m) errors.push(m);
+  }
+  return errors;
+}
+
+/** Block a `git commit` when linters fail (effectful: runs eslint/tsc/prettier/ruff, never auto-fixes). */
+export function preCommitGate(tool: string, command: string | undefined, cwd: string | undefined): Prompt | null {
+  if (tool !== "Bash" || !command || !cwd) return null;
+  if (!command.startsWith("git") || !command.includes("commit")) return null;
+  const errors = collectErrors(cwd);
+  if (!errors.length) return null;
+  return {
+    kind: "block",
+    title: "Pre-commit checks failed",
+    reason: `COMMIT BLOCKED — fix then retry:\n\n${errors.join("\n\n")}`,
+    actions: ["Fix the linter/type errors above", "Re-run the commit"],
+  };
+}

package/src/runtime/prompt-text.ts

@@ -0,0 +1,38 @@
+/**
+ * Normalizes a hook payload's `prompt` field across harness shapes: a plain
+ * string (Claude Code, Codex) or an array of content blocks (Kimi 0.31.1 —
+ * captured live: `[{"type":"text","text":"..."}]` on `UserPromptSubmit`).
+ * Never throws: this runs inside a hook, where an exception breaks the harness.
+ */
+
+/** A Kimi-shaped prompt content block: any object carrying a `text` string. */
+interface PromptTextBlock {
+  text: string;
+}
+
+/** True for an object whose `text` property is a string (the only field this reads). */
+function hasTextField(value: unknown): value is PromptTextBlock {
+  return typeof value === "object" && value !== null && typeof (value as { text?: unknown }).text === "string";
+}
+
+/**
+ * Coerce a hook payload's `prompt` field to plain text.
+ *
+ * - A string is returned AS-IS (same reference, no trim/normalize) — this is
+ *   the identity branch that guarantees zero regression on Claude Code/Codex,
+ *   whose `prompt` is already a string.
+ * - An array (Kimi's content-block shape) is flattened: every element with a
+ *   string `.text` is kept, joined with `"\n"` — one block per line, since
+ *   downstream consumers ({@link detectCreationIntent}, {@link detectMode})
+ *   only run `\b`-anchored regexes with no line-start/end assumption, so a
+ *   newline join is safe and reads like the multi-turn/multi-block source.
+ * - Anything else (`undefined`, `null`, a number, a plain object) yields `""`.
+ *
+ * @param value - The raw `prompt` field from a hook payload (unknown shape).
+ * @returns The prompt text, or `""` when it cannot be recovered.
+ */
+export function promptText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.filter(hasTextField).map((b) => b.text).join("\n");
+  return "";
+}

package/src/runtime/receipt-capture.ts

@@ -0,0 +1,34 @@
+/**
+ * Bash verification-receipt extraction for PostToolUse: a `tsc`/`bun test`
+ * run is parsed (exit code + output) into a signed receipt the TaskCompleted
+ * gate later demands. Structured responses ONLY: Kimi Code CLI sends
+ * `tool_output` as a truncated STRING (no exit_code, no stdout/stderr
+ * channels) — parsing it would forge a success receipt (`exit 0`, empty
+ * output) for possibly-failed runs, so a non-object source is skipped.
+ */
+import { captureReceipt } from "../tracking/receipts";
+
+/**
+ * Record a verification receipt for a Bash run when the response is structured.
+ * @param file - Session track file.
+ * @param tool - The tool name (only "Bash" receipts exist).
+ * @param command - The executed command.
+ * @param toolResult - `payload.tool_result` (preferred), when present.
+ * @param response - `payload.tool_response ?? payload.tool_output` fallback.
+ * @param now - Clock.
+ */
+export async function captureBashReceipt(
+  file: string,
+  tool: string,
+  command: string | undefined,
+  toolResult: unknown,
+  response: unknown,
+  now: number,
+): Promise<void> {
+  if (tool !== "Bash" || !command) return;
+  const r = (toolResult ?? response) as { exit_code?: unknown; stdout?: unknown; stderr?: unknown } | undefined;
+  if (!r || typeof r !== "object") return;
+  const out = `${typeof r.stdout === "string" ? r.stdout : ""}\n${typeof r.stderr === "string" ? r.stderr : ""}`;
+  const exit = Number(r.exit_code ?? 0);
+  await captureReceipt(file, command, out, Number.isFinite(exit) ? exit : 0, now);
+}

package/src/runtime/record.ts

@@ -0,0 +1,26 @@
+import { dirname } from "node:path";
+import { withTrack } from "../tracking/store";
+import { recordAgent, recordDoc, recordRefRead, type AgentQuality } from "../tracking/session-state";
+import { appendRefRead } from "../freshness/ref-journal";
+
+/** A unit of session activity to record (discriminated union on `kind`). */
+export type Activity =
+  | { kind: "agent"; name: string; ts: number; quality?: AgentQuality }
+  | { kind: "doc"; framework: string; sessionId: string; source: string; ts?: number }
+  | { kind: "ref"; path: string; ts?: number };
+
+/** Apply an activity to a session's track and persist it (PostToolUse path). */
+export async function recordActivity(file: string, activity: Activity): Promise<void> {
+  await withTrack(file, (track) =>
+    activity.kind === "agent"
+      ? recordAgent(track, activity.name, activity.ts, activity.quality)
+      : activity.kind === "doc"
+        ? recordDoc(track, activity.framework, activity.sessionId, activity.source, activity.ts)
+        : recordRefRead(track, activity.path, activity.ts),
+  );
+  // Mirror a `.md` ref read into the append-only journal: the racy load→save above
+  // loses a lone write under the hook fan-out, and a teammate's read has not yet
+  // flushed to the platform transcript at edit time (multi-minute lag > TTL) — the
+  // journal is the fresh, race-immune source the gate folds back (see ref-journal.ts).
+  if (activity.kind === "ref") appendRefRead(dirname(file), activity.path, activity.ts ?? Date.now());
+}

package/src/runtime/respond.ts

@@ -0,0 +1,92 @@
+import { formatPrompt, type Prompt } from "../prompt/types";
+import { denyResponse, contextResponse, informResponse } from "../adapters/claude";
+import { toHermesResponse } from "../adapters/hermes";
+import { toKimiResponse } from "../adapters/kimi";
+import { toCursorResponse } from "../adapters/cursor/respond";
+
+/**
+ * Map a portable {@link Prompt} to a harness's native hook response, honoring
+ * all 3 prompt kinds (`block`/`ask`/`inform`) instead of collapsing `ask` and
+ * `inform` together. Reuses the Claude adapter's `denyResponse`/
+ * `contextResponse`/`informResponse` builders for claude-code/codex (same hook
+ * shape) to avoid duplicating the JSON.
+ * - claude-code/codex: `block` -> deny, `ask` -> interactive
+ *   `permissionDecision:"ask"`, `inform` -> non-blocking `additionalContext`.
+ * - gemini-cli/cline: their real hook schemas have no interactive "ask"
+ *   state (deny is the only blocking outcome), so `ask` and `inform` already
+ *   both resolve to non-blocking context injection — unchanged.
+ * - cursor: `ask` degrades to a native `permission:"deny"` because Cursor does
+ *   not reliably apply `ask` on `preToolUse`; `inform` stays non-blocking.
+ * - hermes: delegated to the adapter's `toHermesResponse` — `block` ->
+ *   `{decision:"block",reason}`; `ask`/`inform` degrade to non-blocking
+ *   `{context}` (Hermes has no interactive "ask" state).
+ * - kimi: delegated to the adapter's `toKimiResponse` — `block`/`ask` ->
+ *   `hookSpecificOutput.permissionDecision:"deny"` (Kimi Code CLI's hooks
+ *   contract documents only "deny"; `ask` downgrades with a prefix, mirroring
+ *   the codex branch above), `inform` -> raw text on stdout (Kimi appends
+ *   stdout to context on exit 0 — no `hookSpecificOutput` envelope documented
+ *   for non-blocking context injection).
+ *
+ * User-visible pass notices (`prompt.userMessage`, Python `hook_output.allow_pass`
+ * / `post_pass` parity), by harness:
+ * - claude-code/codex: top-level `systemMessage` ("warning message shown to the
+ *   user"); a pure notice (empty `reason`) emits `{systemMessage}` alone. Codex
+ *   consumes the Claude hook schema, so it rides the same field.
+ * - gemini-cli: common `systemMessage` output field ("displayed immediately to
+ *   the user in the terminal") — the notice rides there.
+ * - cursor: `user_message` is its user-visible channel (see case comment).
+ * - cline: NO user-visible channel (`cancel`/`contextModification`/
+ *   `errorMessage`-on-cancel only) — the notice is dropped silently (a pure
+ *   notice returns "" = plain allow).
+ * @param id - Harness id.
+ * @param prompt - The portable prompt to render.
+ * @param event - The firing hook event name for the claude-code/codex branch
+ * (defaults to `"PreToolUse"`, the only phase every existing caller but
+ * `handle-post.ts` renders) — a POST-phase caller MUST pass `"PostToolUse"`
+ * (or its real raw event name) so `hookEventName` matches the event that
+ * actually fired instead of a hardcoded, wrong `"PreToolUse"`.
+ */
+export function respond(id: string, prompt: Prompt, event: string = "PreToolUse"): string {
+  const message = formatPrompt(prompt);
+  const { kind, userMessage, reason } = prompt;
+  switch (id) {
+    case "claude-code":
+    case "codex":
+      if (kind === "block") return denyResponse(event, message);
+      if (kind === "inform") {
+        return userMessage ? informResponse(event, userMessage, reason ? message : "") : contextResponse(event, message);
+      }
+      // Codex parses but NEVER honors `permissionDecision: "ask"` (deny-only) — an
+      // `ask` would silently fail open. Downgrade it to an explicit deny so the
+      // gate still bites; the reason is prefixed so the honest limit is visible.
+      if (id === "codex") {
+        return denyResponse(event, `[downgraded from ask — Codex has no interactive approval]\n${message}`);
+      }
+      return JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: event,
+          permissionDecision: "ask",
+          permissionDecisionReason: message,
+        },
+      });
+    case "gemini-cli":
+      if (kind === "block") return JSON.stringify({ decision: "deny", reason: message });
+      if (userMessage) return JSON.stringify({ ...(reason ? { hookSpecificOutput: { additionalContext: message } } : {}), systemMessage: userMessage });
+      return JSON.stringify({ hookSpecificOutput: { additionalContext: message } });
+    case "cursor":
+      return toCursorResponse(prompt, event === "PreToolUse" ? "preToolUse" : event);
+    case "hermes":
+      // Single source of truth for the Hermes wire shape lives in the adapter
+      // (same JSON.stringify contract as the inline cases above).
+      return toHermesResponse(prompt);
+    case "kimi":
+      // Single source of truth for the Kimi wire shape lives in the adapter.
+      return toKimiResponse(prompt);
+    case "cline":
+      if (kind === "block") return JSON.stringify({ cancel: true, errorMessage: message });
+      if (userMessage && !reason) return ""; // pure notice: no user-visible channel — silent allow
+      return JSON.stringify({ contextModification: message });
+    default:
+      return "";
+  }
+}

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