@hegemonart/get-design-done 1.19.6 → 1.21.0

package/hooks/context-exhaustion.ts

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * context-exhaustion.ts — PostToolUse hook
+ *
+ * Phase 20 Plan 20-13 rewrite of the original context-exhaustion.js.
+ * Behavior is byte-equivalent: when tool_response reports context
+ * consumption at or above THRESHOLD (default 0.85), the hook writes a
+ * <paused> resumption block into .design/STATE.md so the next session
+ * can resume with full context. Only writes once per session — if a
+ * <paused> block from the same trigger already exists, the hook exits
+ * silently.
+ *
+ * Phase 20 addition: every decision (ok / warn) fires a hook.fired
+ * event to .design/telemetry/events.jsonl via appendEvent() (Plan 20-06).
+ *
+ * Hook type: PostToolUse (any tool)
+ * Input:  JSON on stdin { tool_name, tool_input, tool_response }
+ * Output: JSON on stdout { continue, suppressOutput, message } or nothing
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import { appendEvent } from '../scripts/lib/event-stream/index.ts';
+import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface ToolResponseMeta {
+  context_usage?: number | string;
+  contextUsage?: number | string;
+}
+interface ToolResponse {
+  context_usage?: number | string;
+  contextUsage?: number | string;
+  metadata?: ToolResponseMeta;
+  meta?: ToolResponseMeta;
+  [key: string]: unknown;
+}
+
+interface HookStdin {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_response?: ToolResponse;
+  [key: string]: unknown;
+}
+
+interface HookOutput {
+  continue: boolean;
+  suppressOutput?: boolean;
+  message?: string;
+}
+
+/** Hook decision emitted on the event stream. */
+export type HookDecision = 'ok' | 'warn';
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+/**
+ * Context-usage fraction above which the hook paints a <paused> block.
+ * Override via GDD_CONTEXT_THRESHOLD env var (float in [0,1]).
+ */
+export const THRESHOLD: number = (() => {
+  const raw = process.env['GDD_CONTEXT_THRESHOLD'];
+  const parsed = raw !== undefined ? Number.parseFloat(raw) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : 0.85;
+})();
+
+const STATE_PATH = join(process.cwd(), '.design', 'STATE.md');
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Claude Code injects context usage in several shapes across versions.
+ * Try direct fields, then metadata.meta alias, then string forms
+ * (fraction or percentage). Returns null when no usage data is present.
+ */
+export function extractContextUsage(
+  toolResponse: ToolResponse | null | undefined,
+): number | null {
+  if (typeof toolResponse !== 'object' || toolResponse === null) return null;
+
+  if (typeof toolResponse.context_usage === 'number') return toolResponse.context_usage;
+  if (typeof toolResponse.contextUsage === 'number') return toolResponse.contextUsage;
+
+  const meta: ToolResponseMeta =
+    toolResponse.metadata ?? toolResponse.meta ?? {};
+  if (typeof meta.context_usage === 'number') return meta.context_usage;
+  if (typeof meta.contextUsage === 'number') return meta.contextUsage;
+
+  const raw =
+    toolResponse.context_usage ??
+    toolResponse.contextUsage ??
+    meta.context_usage ??
+    meta.contextUsage;
+  if (typeof raw === 'string') {
+    if (raw.endsWith('%')) return Number.parseFloat(raw) / 100;
+    const n = Number.parseFloat(raw);
+    if (Number.isFinite(n)) return n > 1 ? n / 100 : n;
+  }
+  return null;
+}
+
+export function buildPausedBlock(toolName: string, usage: number): string {
+  const pct = Math.round(usage * 100);
+  const thresholdPct = Math.round(THRESHOLD * 100);
+  return `
+<paused>
+recorded: ${now()}
+trigger: context-exhaustion-hook
+context_usage: ${pct}%
+last_tool: ${toolName}
+
+## Resumption instructions
+
+Context reached ${pct}% during the previous session (threshold: ${thresholdPct}%).
+The session was auto-paused to preserve quality.
+
+To resume:
+1. Run \`/gdd:resume\` — it will read this block and restore working context
+2. If mid-plan: check .design/STATE.md for the last completed task
+3. Re-read the active PLAN.md to orient before continuing
+
+Intel store status at pause time:
+  ls .design/intel/files.json 2>/dev/null && echo "present" || echo "missing"
+</paused>
+`;
+}
+
+export function stateFileHasPausedBlock(): boolean {
+  if (!existsSync(STATE_PATH)) return false;
+  const content = readFileSync(STATE_PATH, 'utf8');
+  return (
+    content.includes('<paused>') &&
+    content.includes('context-exhaustion-hook')
+  );
+}
+
+function appendPausedBlock(block: string): void {
+  if (!existsSync(dirname(STATE_PATH))) {
+    mkdirSync(dirname(STATE_PATH), { recursive: true });
+  }
+  if (!existsSync(STATE_PATH)) {
+    writeFileSync(STATE_PATH, '# Design State\n\n', 'utf8');
+  }
+  appendFileSync(STATE_PATH, block, 'utf8');
+}
+
+// ── event-stream emitter ────────────────────────────────────────────────────
+
+let CACHED_SESSION_ID: string | null = null;
+function getSessionId(): string {
+  if (CACHED_SESSION_ID === null) {
+    const iso = new Date().toISOString().replace(/[:.]/g, '-');
+    CACHED_SESSION_ID = `gdd-hook-${iso}-${process.pid}`;
+  }
+  return CACHED_SESSION_ID;
+}
+
+function emitHookFired(decision: HookDecision): void {
+  const ev: HookFiredEvent = {
+    type: 'hook.fired',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    payload: { hook: 'context-exhaustion', decision },
+  };
+  try {
+    appendEvent(ev);
+  } catch {
+    // Fail open — event-stream errors must never block the hook.
+  }
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+async function readStdin(): Promise<string> {
+  const rl = createInterface({ input: process.stdin });
+  let data = '';
+  for await (const line of rl) data += line + '\n';
+  return data;
+}
+
+export async function main(): Promise<void> {
+  const inputData = await readStdin();
+
+  let parsed: HookStdin;
+  try {
+    parsed = JSON.parse(inputData) as HookStdin;
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName =
+    typeof parsed.tool_name === 'string' && parsed.tool_name.length > 0
+      ? parsed.tool_name
+      : 'unknown';
+  const toolResponse: ToolResponse = parsed.tool_response ?? {};
+
+  const usage = extractContextUsage(toolResponse);
+
+  // No usage data — cannot act. Do not emit a hook.fired event; this
+  // is a non-decision, not an "ok" outcome.
+  if (usage === null) process.exit(0);
+
+  // Below threshold — explicit "ok" decision.
+  if (usage < THRESHOLD) {
+    emitHookFired('ok');
+    process.exit(0);
+  }
+
+  // At or above threshold but block already present — emit ok (we did
+  // the right thing earlier) and bail.
+  if (stateFileHasPausedBlock()) {
+    emitHookFired('ok');
+    process.exit(0);
+  }
+
+  const block = buildPausedBlock(toolName, usage);
+  appendPausedBlock(block);
+  emitHookFired('warn');
+
+  const response: HookOutput = {
+    continue: true,
+    suppressOutput: false,
+    message: `gdd-context-exhaustion: Context at ${Math.round(usage * 100)}% — auto-recorded <paused> block in .design/STATE.md. Run /gdd:resume in the next session to continue.`,
+  };
+  process.stdout.write(JSON.stringify(response));
+}
+
+const isDirectInvocation =
+  process.argv[1] !== undefined &&
+  /context-exhaustion\.ts$/.test(process.argv[1]);
+
+if (isDirectInvocation) {
+  main().catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`context-exhaustion hook error: ${msg}\n`);
+    process.exit(0);
+  });
+}

package/hooks/gdd-read-injection-scanner.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * gdd-read-injection-scanner.ts — PostToolUse hook (matcher: Read)
+ *
+ * Phase 20 Plan 20-13 rewrite of the original
+ * gdd-read-injection-scanner.js. Scans Read tool output for common
+ * prompt-injection patterns and warns (does not block) when suspicious
+ * content is found in a read file. Advisory-only — output is a JSON
+ * response containing a `message` field the user / agent can act on.
+ *
+ * Injection patterns come from scripts/injection-patterns.cjs (Tier-2;
+ * not TypeScript-converted per Plan 20-00's policy). We require-load
+ * them through Node's CJS interop using `createRequire()` — this works
+ * under --experimental-strip-types without `package.json "type":"module"`
+ * changes and keeps the .cjs module shared with
+ * scripts/run-injection-scanner-ci.cjs unchanged.
+ *
+ * Phase 20 addition: every decision (block / allow) fires a hook.fired
+ * event via appendEvent() (Plan 20-06). "block" is used for the
+ * warning-emission path even though the hook itself never hard-blocks
+ * — it signals the advisory decision to downstream consumers.
+ *
+ * Hook type: PostToolUse (matcher: Read)
+ * Input:  JSON on stdin { tool_name, tool_input, tool_response }
+ * Output: JSON on stdout { continue, suppressOutput, message } or nothing
+ */
+
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+import { appendEvent } from '../scripts/lib/event-stream/index.ts';
+import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+
+// ── require-bridge to the shared .cjs pattern file ──────────────────────────
+
+/**
+ * Load injection-patterns.cjs through Node's CJS require even though
+ * this TS file runs under --experimental-strip-types (which auto-detects
+ * ES-module mode). createRequire() can be anchored on any absolute
+ * filesystem path (or a `file://` URL string) — we deliberately avoid
+ * `import.meta.url` so this module stays compatible with the `Node16`
+ * tsconfig module setting without forcing `"type":"module"` in
+ * package.json (which would break the Tier-2 .cjs tests per Plan 20-00).
+ *
+ * Path resolution: when Claude Code invokes the hook, it passes the
+ * absolute path as argv[1]. We anchor against that (so the .cjs
+ * resolves relative to this file's own directory). Falls back to
+ * process.cwd() — scripts/injection-patterns.cjs lives under the
+ * package root, which is cwd in both CI and npm script contexts.
+ */
+function loadPatterns(): readonly RegExp[] {
+  const hookPath =
+    typeof process.argv[1] === 'string' && process.argv[1].length > 0
+      ? isAbsolute(process.argv[1])
+        ? process.argv[1]
+        : resolve(process.argv[1])
+      : resolve('hooks/gdd-read-injection-scanner.ts');
+  const require = createRequire(hookPath);
+  const candidatePaths: string[] = [
+    join(dirname(hookPath), '..', 'scripts', 'injection-patterns.cjs'),
+    join(process.cwd(), 'scripts', 'injection-patterns.cjs'),
+  ];
+  let lastErr: unknown = null;
+  for (const p of candidatePaths) {
+    try {
+      const mod = require(p) as {
+        INJECTION_PATTERNS: Array<{ name: string; re: RegExp }>;
+      };
+      return mod.INJECTION_PATTERNS.map((entry) => entry.re);
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  const msg =
+    lastErr instanceof Error ? lastErr.message : String(lastErr);
+  throw new Error(
+    `gdd-read-injection-scanner: failed to load injection-patterns.cjs (${msg})`,
+  );
+}
+
+const INJECTION_PATTERNS: readonly RegExp[] = loadPatterns();
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface HookStdin {
+  tool_name?: string;
+  tool_input?: { file_path?: string };
+  tool_response?: { content?: string };
+  [key: string]: unknown;
+}
+
+interface HookOutput {
+  continue: boolean;
+  suppressOutput?: boolean;
+  message?: string;
+}
+
+/** Hook decision tag for the event stream. */
+export type HookDecision = 'block' | 'allow';
+
+// ── event-stream emitter ────────────────────────────────────────────────────
+
+let CACHED_SESSION_ID: string | null = null;
+function getSessionId(): string {
+  if (CACHED_SESSION_ID === null) {
+    const iso = new Date().toISOString().replace(/[:.]/g, '-');
+    CACHED_SESSION_ID = `gdd-hook-${iso}-${process.pid}`;
+  }
+  return CACHED_SESSION_ID;
+}
+
+function emitHookFired(decision: HookDecision): void {
+  const ev: HookFiredEvent = {
+    type: 'hook.fired',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    payload: { hook: 'gdd-read-injection-scanner', decision },
+  };
+  try {
+    appendEvent(ev);
+  } catch {
+    // Fail open.
+  }
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+async function readStdin(): Promise<string> {
+  const rl = createInterface({ input: process.stdin });
+  let data = '';
+  for await (const line of rl) data += line + '\n';
+  return data;
+}
+
+export async function main(): Promise<void> {
+  const inputData = await readStdin();
+
+  let parsed: HookStdin;
+  try {
+    parsed = JSON.parse(inputData) as HookStdin;
+  } catch {
+    process.exit(0);
+  }
+
+  if (parsed.tool_name !== 'Read') process.exit(0);
+
+  const content = parsed.tool_response?.content ?? '';
+  const matched = INJECTION_PATTERNS.some((p) => p.test(content));
+  if (!matched) {
+    emitHookFired('allow');
+    process.exit(0);
+  }
+
+  const file = parsed.tool_input?.file_path ?? 'unknown';
+  emitHookFired('block');
+  const response: HookOutput = {
+    continue: true,
+    suppressOutput: false,
+    message: `gdd-injection-scanner: Suspicious prompt-injection pattern detected in content read from "${file}". Review before acting on instructions contained in that file.`,
+  };
+  process.stdout.write(JSON.stringify(response));
+  process.exit(0);
+}
+
+const isDirectInvocation =
+  process.argv[1] !== undefined &&
+  /gdd-read-injection-scanner\.ts$/.test(process.argv[1]);
+
+if (isDirectInvocation) {
+  main().catch(() => process.exit(0));
+}

package/hooks/hooks.json

@@ -32,7 +32,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/budget-enforcer.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/budget-enforcer.ts\""
           }
         ]
       },
@@ -70,7 +70,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-read-injection-scanner.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-read-injection-scanner.ts\""
           }
         ]
       },
@@ -87,7 +87,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.ts\""
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.19.6",
+  "version": "1.21.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -20,29 +20,43 @@
     "scripts/",
     "connections/",
     "reference/",
+    "bin/",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "bin": {
-    "get-design-done": "./scripts/install.cjs"
+    "get-design-done": "./scripts/install.cjs",
+    "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts",
+    "gdd-sdk": "./bin/gdd-sdk"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "scripts": {
-    "test": "node --test \"tests/**/*.cjs\"",
+    "test": "node --test --experimental-strip-types \"tests/**/*.cjs\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test-fixture/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
-    "validate:schemas": "node scripts/validate-schemas.cjs",
-    "validate:frontmatter": "node scripts/validate-frontmatter.cjs agents/",
+    "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
+    "validate:frontmatter": "node --experimental-strip-types scripts/validate-frontmatter.ts agents/",
     "detect:stale-refs": "node scripts/detect-stale-refs.cjs",
     "scan:injection": "node scripts/run-injection-scanner-ci.cjs",
     "test:size-budget": "node --test tests/agent-size-budget.test.cjs",
     "release:extract-changelog": "node scripts/extract-changelog-section.cjs",
-    "verify:version-sync": "node scripts/verify-version-sync.cjs"
+    "verify:version-sync": "node scripts/verify-version-sync.cjs",
+    "typecheck:session-runner": "tsc --noEmit",
+    "gdd-sdk": "node --experimental-strip-types scripts/lib/cli/index.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "ajv-cli": "^5.0.0",
+    "ajv-formats": "^3.0.1",
+    "json-schema-to-typescript": "^15.0.0",
+    "typescript": "^5.5.0"
   },
   "keywords": [
     "claude",
@@ -55,53 +69,20 @@
     "reflection",
     "tested",
     "ci",
-    "iconography",
-    "brand-voice",
-    "performance-budget",
-    "framer-motion",
-    "motion-design",
-    "micro-polish",
-    "surfaces",
-    "make-interfaces-feel-better",
-    "palette-catalog",
-    "style-vocabulary",
-    "industry-palettes",
-    "ui-style-vocabulary",
-    "variable-fonts",
-    "container-queries",
-    "view-transitions",
-    "motion-vocabulary",
-    "motion-easings",
-    "transition-taxonomy",
-    "gesture-mechanics",
-    "clip-path-animation",
-    "component-specs",
-    "design-system-benchmarks",
-    "i18n",
-    "user-research",
-    "information-architecture",
-    "form-patterns",
-    "data-viz",
-    "platforms",
-    "cross-cycle-memory",
-    "fts5",
-    "checkpoints",
-    "experience-archive",
-    "recall",
-    "relevance-counter",
-    "record-contract",
-    "first-principles",
-    "emotional-design",
-    "component-authoring",
-    "disney-12-principles",
-    "peak-end-rule",
-    "loss-aversion",
-    "cognitive-load",
-    "doherty-threshold",
-    "rams-lens"
+    "headless",
+    "cli",
+    "codex",
+    "gemini",
+    "mcp",
+    "parallel-agents",
+    "agent-sdk"
   ],
   "skills": [
     "SKILL.md"
   ],
-  "hooks": "hooks/hooks.json"
+  "hooks": "hooks/hooks.json",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.119",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
 }

package/reference/codex-tools.md

@@ -0,0 +1,53 @@
+# Codex CLI Tool Map
+
+Last verified: 2026-04-24
+
+When a GDD skill references a Claude Code tool name, the Codex runtime
+translates to the equivalent below. Skills do NOT need to branch — the tool
+name in prose is authoritative; Codex resolves via this map.
+
+## Tool-name mapping
+
+| CC name | Codex name | Notes |
+| --- | --- | --- |
+| `Read` | `read_file` | Takes `path`; returns file content. |
+| `Write` | `apply_patch` (create mode) | Requires a diff-style patch; ensure tool call emits `{action:'create', path, content}`. |
+| `Edit` | `apply_patch` (update mode) | Emits `{action:'update', path, patch}` with unified diff. |
+| `Bash` | `shell` | Takes `{command: string, cwd?, timeout_sec?}`. |
+| `Grep` | `shell` | Compose a `rg` / `grep -rn` invocation; no native Codex grep tool. |
+| `Glob` | `shell` | Compose `ls` / `find`; no native Codex glob. |
+| `Task` | Sub-invocation via nested Codex | Codex spawns nested sessions via its own CLI, not a tool call. Skills requiring Task should prefer the MCP `gdd-state` tool layer instead. |
+| `WebSearch` | `web_search` | If enabled in Codex policy. |
+| `WebFetch` | `shell` (curl) or `web_search.open` | Prefer curl for deterministic output. |
+
+## MCP server `gdd-state`
+
+The gdd-state MCP server works unchanged on Codex. Configure Codex to load
+it by adding to `~/.codex/config.toml`:
+
+```toml
+[[mcp_servers]]
+name = "gdd-state"
+command = "node"
+args = ["--experimental-strip-types", "<pkg-root>/scripts/mcp-servers/gdd-state/server.ts"]
+```
+
+All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Codex.
+
+## Known gaps
+
+- `Task` spawning: Codex does not expose nested-session as a tool call. For
+  now, skills that rely on `Task` (parallel mappers in Plan 21-06, parallel
+  discussants in Plan 21-07) should invoke the gdd-sdk CLI as a shell
+  subprocess: `shell("npx gdd-sdk stage explore --parallel")`. This is
+  documented in AGENTS.md.
+- `apply_patch` diff format differs from CC's Edit: Codex expects unified
+  diff (`---`/`+++`/`@@` hunks), while CC's Edit takes `old_string`/`new_string`.
+  The plugin's skill prose uses Edit's semantics; on Codex the runtime must
+  generate the unified diff from the old/new pair. A helper lives at
+  `scripts/lib/harness/edit-to-patch.ts` (reserved for Phase 22 wiring).
+
+---
+
+Last verified: 2026-04-24 — tool surface re-checked against Codex CLI docs
+current to this date. Revisit whenever Codex ships a tool-vocabulary change.

package/reference/config-schema.md

@@ -185,7 +185,7 @@ If `.design/budget.json` is missing when any `/gdd:*` command runs, `scripts/boo
 
 ## .design/telemetry/costs.jsonl + .design/agent-metrics.json (Phase 10.1)
 
-Phase 10.1 introduces two measurement artifacts written by `hooks/budget-enforcer.js` (PreToolUse on `Agent` spawns) and `scripts/aggregate-agent-metrics.js` (detached child of the hook + refresh step of `/gdd:optimize`). Both files live under the gitignored `.design/` directory — they are local session state, not committed.
+Phase 10.1 introduces two measurement artifacts written by `hooks/budget-enforcer.js` (PreToolUse on `Agent` spawns) and `scripts/aggregate-agent-metrics.ts` (detached child of the hook + refresh step of `/gdd:optimize`). Both files live under the gitignored `.design/` directory — they are local session state, not committed.
 
 ### .design/telemetry/costs.jsonl
 
@@ -223,7 +223,7 @@ Append-only ledger. One JSON object per line. Written by `hooks/budget-enforcer.
 
 ### .design/agent-metrics.json
 
-Per-agent aggregate derived from `costs.jsonl` by `scripts/aggregate-agent-metrics.js`. Written atomically via tmp-file + rename. Overwritten in full on every refresh — not append-only. Consumers should treat it as a snapshot.
+Per-agent aggregate derived from `costs.jsonl` by `scripts/aggregate-agent-metrics.ts`. Written atomically via tmp-file + rename. Overwritten in full on every refresh — not append-only. Consumers should treat it as a snapshot.
 
 **Schema:**