@taicho-ai/framework 0.1.0

package/src/core/auth/refresh.ts

@@ -0,0 +1,57 @@
+/** Access-token refresh + single-flight coalescing. A failed/revoked refresh -> AuthExpiredError. */
+import { OPENAI_CODEX_AUTH } from "./constants";
+import type { AuthProfile } from "./profile";
+
+export class AuthExpiredError extends Error {
+  constructor(message = "ChatGPT session expired — run /login openai") {
+    super(message);
+    this.name = "AuthExpiredError";
+  }
+}
+
+interface RefreshResponse { access_token: string; refresh_token?: string; expires_in: number; }
+
+export async function refreshToken(
+  profile: AuthProfile,
+  fetchImpl: typeof fetch = fetch,
+  now: () => number = Date.now,
+): Promise<AuthProfile> {
+  const res = await fetchImpl(OPENAI_CODEX_AUTH.tokenUrl, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: profile.refresh_token,
+      client_id: OPENAI_CODEX_AUTH.clientId,
+    }),
+  });
+  if (!res.ok) throw new AuthExpiredError();
+  const t = (await res.json()) as RefreshResponse;
+  return {
+    ...profile,
+    access_token: t.access_token,
+    refresh_token: t.refresh_token ?? profile.refresh_token,
+    expires_at: now() + t.expires_in * 1000,
+  };
+}
+
+/** Returns a refresh() that shares one in-flight refresh across concurrent callers. */
+export function createRefresher(opts: {
+  load: () => AuthProfile | null;
+  save: (p: AuthProfile) => void;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+}): () => Promise<AuthProfile> {
+  let inFlight: Promise<AuthProfile> | null = null;
+  return () => {
+    if (inFlight) return inFlight;
+    inFlight = (async () => {
+      const current = opts.load();
+      if (!current) throw new AuthExpiredError();
+      const refreshed = await refreshToken(current, opts.fetchImpl ?? fetch, opts.now ?? Date.now);
+      opts.save(refreshed);
+      return refreshed;
+    })().finally(() => { inFlight = null; });
+    return inFlight;
+  };
+}

package/src/core/auth/status.ts

@@ -0,0 +1,26 @@
+/** Pure presentation helpers for auth status / onboarding lines (unit-tested).
+ *  No I/O, no token material — safe to call from the REPL render path. */
+import type { AuthSource } from "../../store/config";
+
+export function formatAuthStatus(source: AuthSource): string {
+  switch (source.kind) {
+    case "env": return `env:${source.provider} (${source.model})`;
+    case "oauth-openai-codex": {
+      const when = new Date(source.expiresAt).toISOString();
+      return `oauth:openai-codex (expires ${when})`;
+    }
+    case "none": return "none — set an API key or run /login openai";
+  }
+}
+
+export function noCredentialLines(): string[] {
+  return [
+    "taicho — no credentials configured.",
+    "Either set ANTHROPIC_API_KEY / OPENAI_API_KEY and relaunch,",
+    "or run /login openai to sign in with your ChatGPT subscription (no API key needed).",
+  ];
+}
+
+export function authExpiredMessage(): string {
+  return "ChatGPT session expired — run /login openai to sign in again.";
+}

package/src/core/command-guard.ts

@@ -0,0 +1,126 @@
+/** The command guard: decide whether a shell command is safe to auto-run (allow) or needs the
+ *  captain's approval (block), by delegating to the external `dcg` binary. Fail SAFE — if dcg is
+ *  absent or errors, we block (→ ask the human). runShell executes an approved/allowed command with
+ *  output caps + a timeout; runSandboxed executes it CONFINED (Plan 08 sandbox-then-escalate). */
+import { tmpdir } from "node:os";
+import { realpathSync } from "node:fs";
+import { resolve, isAbsolute, dirname, basename, join, sep } from "node:path";
+
+export interface Verdict { decision: "allow" | "block"; reason?: string }
+
+/** Default runner: spawn `dcg --robot test <command>`. Throws if dcg isn't installed (caught below). */
+function dcgTest(command: string): { code: number; stdout: string } {
+  const p = Bun.spawnSync({ cmd: ["dcg", "--robot", "test", command] });
+  return { code: p.exitCode ?? 1, stdout: p.stdout.toString() };
+}
+
+export function classifyCommand(
+  command: string,
+  run: (command: string) => { code: number; stdout: string } = dcgTest,
+): Verdict {
+  try {
+    const { code, stdout } = run(command);
+    if (code === 0) return { decision: "allow" };
+    let reason: string | undefined;
+    try { reason = (JSON.parse(stdout) as { reason?: string }).reason; } catch { /* not JSON */ }
+    return { decision: "block", reason: reason ?? "flagged by the command guard" };
+  } catch {
+    return { decision: "block", reason: "command guard (dcg) unavailable — approve manually" };
+  }
+}
+
+const CAP = 10_000;
+const cap = (b: { toString(): string }): string => { const s = b.toString(); return s.length > CAP ? s.slice(0, CAP) + "\n…(truncated)" : s; };
+
+export function runShell(command: string, cwd: string): { exitCode: number; stdout: string; stderr: string } {
+  try {
+    const p = Bun.spawnSync({ cmd: ["bash", "-lc", command], cwd, timeout: 60_000 });
+    return { exitCode: p.exitCode ?? -1, stdout: cap(p.stdout), stderr: cap(p.stderr) };
+  } catch (e) {
+    return { exitCode: -1, stdout: "", stderr: `failed to run: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+/** Result of a sandbox attempt. `enforced` is the honesty flag: TRUE means the command actually ran
+ *  inside an OS-level sandbox (confined); FALSE means no sandbox mechanism was available on this host
+ *  and the command was NOT run (we never silently drop confinement — the caller must escalate to an
+ *  approved unsandboxed run). */
+export interface SandboxResult { exitCode: number; stdout: string; stderr: string; enforced: boolean }
+
+const realish = (p: string): string => { try { return realpathSync(p); } catch { return p; } };
+const esc = (p: string): string => p.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+
+/** Realpath the deepest EXISTING ancestor of `p` (following symlinks), then re-append the
+ *  not-yet-created tail. A leaf that doesn't exist yet can't itself be a symlink, but any of its
+ *  existing ancestors could be — so we resolve as far down as the filesystem lets us. */
+function resolveDeepest(p: string): string {
+  let cur = resolve(p);
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      const base = realpathSync(cur);
+      return tail.length ? join(base, ...tail) : base;
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return tail.length ? join(cur, ...tail) : cur; // hit the fs root, nothing more to resolve
+      tail.unshift(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+/** True iff `target` resolves to a path INSIDE (or equal to) `root`, following symlinks so a
+ *  symlinked cwd — or a symlinked ancestor of it — can't smuggle the effective directory outside the
+ *  workspace. A relative `target` is resolved against `root`. This is the containment gate that keeps
+ *  run_command's MODEL-SUPPLIED cwd from widening the sandbox's writable set beyond ctx.ws. */
+export function isInsideWorkspace(root: string, target: string): boolean {
+  const rootReal = resolveDeepest(root);
+  const targetReal = resolveDeepest(isAbsolute(target) ? target : resolve(root, target));
+  return targetReal === rootReal || targetReal.startsWith(rootReal + sep);
+}
+
+/** A Seatbelt (macOS `sandbox-exec`) profile: deny-by-default, allow reads + process spawn, allow
+ *  writes ONLY under the given paths (workspace + temp), and — by deny-default — deny all network. */
+function seatbeltProfile(writable: string[]): string {
+  const writes = writable.map((p) => `(allow file-write* (subpath "${esc(p)}"))`).join("");
+  return [
+    "(version 1)",
+    "(deny default)",
+    "(allow process-fork)(allow process-exec)",
+    "(allow file-read*)",
+    "(allow sysctl-read)",
+    '(allow file-write-data (path "/dev/null") (path "/dev/stdout") (path "/dev/stderr") (path "/dev/tty"))',
+    writes,
+  ].join("");
+}
+
+/** Run a command CONFINED (Plan 08 sandbox-then-escalate).
+ *
+ *  ENFORCED on macOS via Seatbelt (`sandbox-exec`): no outbound network, filesystem writes confined
+ *  to the workspace + temp dirs, reads allowed. Returns `enforced: true` with the real captured
+ *  output.
+ *
+ *  On any OTHER platform (or if `sandbox-exec` is missing/errors), there is NO enforced sandbox here:
+ *  we return `enforced: false` and do NOT run the command — the caller escalates to a human-approved
+ *  unsandboxed run. This keeps the enforcement claim HONEST (we never fake confinement).
+ *
+ *  SECURITY: the Seatbelt writable set is anchored to `writableRoot` (the WORKSPACE, ctx.ws) + scratch
+ *  temp dirs ONLY — NEVER the model-supplied `cwd`. `cwd` is where the command RUNS, not what it may
+ *  write to; the caller (run_command) separately rejects/escalates a cwd that escapes ctx.ws, so a
+ *  model can't self-authorize writes outside the workspace by choosing its own cwd. `writableRoot`
+ *  defaults to `cwd` only for back-compat callers that already pass a trusted, contained directory. */
+export function runSandboxed(command: string, cwd: string, writableRoot: string = cwd): SandboxResult {
+  if (process.platform !== "darwin")
+    return { exitCode: -1, stdout: "", stderr: `no OS sandbox on this host (${process.platform}) — sandbox enforced on macOS only`, enforced: false };
+  try {
+    const writable = [...new Set([realish(writableRoot), realish(tmpdir()), "/tmp", "/private/tmp"])];
+    const profile = seatbeltProfile(writable);
+    const p = Bun.spawnSync({ cmd: ["sandbox-exec", "-p", profile, "bash", "-lc", command], cwd, timeout: 60_000 });
+    // Strip Seatbelt's own deprecation notice so it doesn't masquerade as command output.
+    const stderr = cap(p.stderr).replace(/^.*sandbox-exec.*deprecated.*$\n?/im, "");
+    return { exitCode: p.exitCode ?? -1, stdout: cap(p.stdout), stderr, enforced: true };
+  } catch (e) {
+    // sandbox-exec not found / spawn failure → NOT enforced; command NOT run (no fake confinement).
+    return { exitCode: -1, stdout: "", stderr: `sandbox unavailable: ${e instanceof Error ? e.message : String(e)}`, enforced: false };
+  }
+}

package/src/core/conversation-artifacts.ts

@@ -0,0 +1,40 @@
+/** Plan 15 — gather all artifacts produced by a conversation's run tree (root + delegated children).
+ *  Walks the delegation subtree, collects artifact handles from each run's trace.artifacts and
+ *  trace.outputArtifacts, de-dups by id (keep latest version), and returns them ordered by created
+ *  desc (latest first). Returns the artifact envelopes (resolved via readArtifact), not the bodies.
+ *
+ *  (Extracted from the retired trace-tree.ts when the /trace waterfall was removed — Plan 17. This is
+ *  the artifact BROWSER's data source, not tracing; trace visualization is OpenTelemetry's job now.) */
+import { readTrace } from "../store/trace";
+import { readArtifact } from "../store/artifacts";
+import { artifactHandle, type Artifact } from "@taicho-ai/contracts/artifact";
+
+export function gatherConversationArtifacts(ws: string, rootRunId: string): Artifact[] {
+  const handles = new Set<string>();
+  const seen = new Set<string>();
+
+  function walk(runId: string) {
+    if (seen.has(runId)) return;
+    seen.add(runId);
+    const trace = readTrace(ws, runId);
+    if (!trace) return;
+    // Collect from both artifacts (produced) and outputArtifacts (handed up).
+    for (const h of trace.artifacts) handles.add(typeof h === "string" ? h : artifactHandle(h));
+    for (const h of trace.outputArtifacts) handles.add(typeof h === "string" ? h : artifactHandle(h));
+    // Recurse into delegated children.
+    for (const childId of trace.delegatedOut) walk(childId);
+  }
+
+  walk(rootRunId);
+
+  // Resolve handles to envelopes, de-dup by id (keep latest version), order by created desc.
+  const byId = new Map<string, Artifact>();
+  for (const h of handles) {
+    const a = readArtifact(ws, h);
+    if (!a) continue;
+    const existing = byId.get(a.id);
+    if (!existing || a.version > existing.version) byId.set(a.id, a);
+  }
+
+  return [...byId.values()].sort((x, y) => y.created.localeCompare(x.created));
+}

package/src/core/conversation-replay.ts

@@ -0,0 +1,160 @@
+/** Plan 05 Phase 3 — cross-turn (boot-replay) compaction, unblocked by Plan 01 Phase 5's seam.
+ *
+ *  Plan 05 Phase 2 bounds context growth WITHIN a run; this bounds it ACROSS turns. `thread.jsonl`
+ *  replayed EVERY completed turn at boot, forever — a long-lived squad accumulated conversation
+ *  history until the assembled prompt no longer fit. Boot replay now becomes a rolling conversation
+ *  SUMMARY (older turns, folded deterministically) + the recent-K turns kept VERBATIM.
+ *
+ *  Two invariants, both load-bearing:
+ *   1. The LEDGER (`conversations/<agent>/ledger.jsonl`) is append-only TRUTH — compaction changes
+ *      what REPLAYS, never what is RECORDED. `thread.jsonl` is a DERIVED cache, REBUILT from the
+ *      ledger's INCLUDED turns each time a completed turn is recorded through the seam (so it is
+ *      deterministic — the same ledger always yields the same replay; no drift).
+ *   2. Replay carries artifact HANDLES + summaries, never inlined BODIES (Plan 01 Phase 5) — each
+ *      produced handle is resolved to `[id@vN] title — summary` via `readArtifact` (envelope only;
+ *      `readArtifactBody` is never called on the replay path), so payloads can't re-enter context.
+ *
+ *  Reuses the Plan 05 in-run machinery where it fits: the `estimateTokens` estimator and the
+ *  marker-led summary shape mirror `core/compaction.ts` (a `[…COMPACTION]` marker keeps the fold
+ *  VISIBLE in the replayed prompt). The FOLD itself is turn-aware (a conversation is user/assistant
+ *  pairs, not tool round-trips), so it does not reuse `compactMessages`' round-trip grouping. */
+import type { ModelMessage } from "ai";
+import { loadContext, loadLedger } from "../store/conversation";
+import { writeThread } from "../store/thread";
+import { readArtifact } from "../store/artifacts";
+import { artifactHandle } from "@taicho-ai/contracts/artifact";
+import { estimateTokens } from "@taicho-ai/agent";
+import { log } from "./logger";
+
+/** How many recent conversation turns (a turn = one user message) replay VERBATIM; older ones fold
+ *  into the rolling summary. Config disposes via `defaults.replayKeepTurns`; model never supplies it. */
+export const DEFAULT_REPLAY_KEEP_TURNS = 6;
+
+const SUMMARY_MARKER = "[CONVERSATION COMPACTION]";
+const MAX_SUMMARY_CHARS = 2000;
+const TURN_GIST_CHARS = 220;
+// Headroom reserved (chars) for the header + a possible one-line elision note, so the character budget
+// below never truncates either of them mid-string.
+const SUMMARY_RESERVE_CHARS = 140;
+
+export interface ReplayCompaction {
+  messages: ModelMessage[];   // [summary message?] + recent-K turns VERBATIM
+  summaryText?: string;       // the rolling summary body (also the head message content); undefined ⇒ nothing folded
+  foldedTurns: number;        // how many user-turns collapsed into the summary
+}
+
+function contentToText(content: unknown): string {
+  return typeof content === "string" ? content : JSON.stringify(content ?? "");
+}
+
+/** A one-line, deterministic gist of a message's text (whitespace-collapsed, capped). */
+function gist(content: unknown): string {
+  return contentToText(content).replace(/\s+/g, " ").trim().slice(0, TURN_GIST_CHARS);
+}
+
+/** Build the visible, deterministic rolling-summary body from the folded (older) messages. No model
+ *  call — pure extraction, mirroring core/compaction.ts's marker-led shape. Pairs each folded user
+ *  message with the assistant reply that follows it.
+ *
+ *  Bounded by CHARACTERS (not a fixed line count), filling from the MOST RECENT folded turns — the ones
+ *  closest to the kept verbatim tail, so most relevant for continuity. Any older overflow is NOTED with
+ *  an explicit elision line, never silently dropped. (Plan 05 Ph3 follow-up: the old code capped at the
+ *  OLDEST ~39 gists and lost every folded turn after them — the more-recent, more-relevant folded turns
+ *  vanished without a trace. Now every folded turn is either gisted or accounted for in the count.) */
+function buildReplaySummary(folded: ModelMessage[], foldedTurns: number): string {
+  const header =
+    `${SUMMARY_MARKER} Folded ${foldedTurns} earlier turn${foldedTurns === 1 ? "" : "s"} of this ` +
+    `conversation. The recent turns replay verbatim below; the ledger keeps the full record. ` +
+    `Any artifacts are referenced by handle (read_artifact for the body).`;
+  // One gist line per folded USER turn (paired with the assistant reply that followed it), oldest→newest.
+  const gists: string[] = [];
+  for (let i = 0; i < folded.length; i++) {
+    const m = folded[i];
+    if (m.role !== "user") continue;
+    const you = gist(m.content);
+    const next = folded[i + 1];
+    const reply = next && next.role === "assistant" ? gist(next.content) : "";
+    gists.push(reply ? `· you: ${you}  →  ${reply}` : `· you: ${you}`);
+  }
+  // Fill from the newest folded gist backwards while the character budget (minus header/elision reserve)
+  // holds; whatever doesn't fit is the OLDEST overflow and is reported, not lost.
+  const kept: string[] = [];
+  let used = header.length + SUMMARY_RESERVE_CHARS;
+  for (let i = gists.length - 1; i >= 0; i--) {
+    if (used + gists[i]!.length + 1 > MAX_SUMMARY_CHARS) break;
+    kept.unshift(gists[i]!);
+    used += gists[i]!.length + 1;
+  }
+  const elided = gists.length - kept.length;
+  const lines = [header];
+  if (elided > 0) {
+    lines.push(`· (… ${elided} older folded turn${elided === 1 ? "" : "s"} elided — full record in the ledger …)`);
+  }
+  lines.push(...kept);
+  return lines.join("\n");
+}
+
+/** Deterministically fold the OLDEST turns into ONE rolling-summary message; keep the recent
+ *  `keepRecentTurns` turns (counted by user message) VERBATIM. Returns the input unchanged (folded
+ *  0) when there are not more turns than the kept tail. Pure — no I/O, no model call. */
+export function compactReplay(messages: ModelMessage[], keepRecentTurns: number): ReplayCompaction {
+  const keep = Math.max(0, keepRecentTurns);
+  const userIdxs = messages.map((m, i) => (m.role === "user" ? i : -1)).filter((i) => i >= 0);
+  if (userIdxs.length <= keep) return { messages, foldedTurns: 0 };
+  const cut = keep === 0 ? messages.length : userIdxs[userIdxs.length - keep];
+  const older = messages.slice(0, cut);
+  const tail = messages.slice(cut);
+  const foldedTurns = userIdxs.length - keep;
+  const summaryText = buildReplaySummary(older, foldedTurns);
+  const summaryMsg: ModelMessage = { role: "user", content: summaryText };
+  return { messages: [summaryMsg, ...tail], summaryText, foldedTurns };
+}
+
+/** Resolve produced handles to a compact `[id@vN] title — summary` reference string. Reads the
+ *  ENVELOPE only (readArtifact) — the body is never inlined, which is the whole point of Plan 01. */
+function artifactRefs(ws: string, handles: string[]): string {
+  const parts: string[] = [];
+  for (const h of handles) {
+    const a = readArtifact(ws, h);
+    if (!a) { parts.push(`[${h}] (unavailable)`); continue; }
+    parts.push(`[${artifactHandle(a)}] ${a.title}${a.summary ? " — " + a.summary : ""}`);
+  }
+  return parts.join("; ");
+}
+
+/** Reconstruct the replay message list from the ledger's INCLUDED turns (Plan 01 Ph5 decision C:
+ *  ledger = truth, context.json = which turns are safe to replay). An assistant turn that produced
+ *  artifacts gets a by-reference handle+summary block appended — handles, never bodies. */
+export function buildReplayMessages(ws: string, agent: string): ModelMessage[] {
+  const included = new Set(loadContext(ws, agent).includedTurns.map((t) => t.turnId));
+  const messages: ModelMessage[] = [];
+  for (const turn of loadLedger(ws, agent)) {
+    if (!included.has(turn.turnId)) continue;
+    if (turn.role !== "user" && turn.role !== "assistant") continue;
+    let content = contentToText(turn.content);
+    if (turn.role === "assistant" && turn.artifacts?.length) {
+      const refs = artifactRefs(ws, turn.artifacts);
+      if (refs) content = `${content}\n\n[artifacts produced — by reference, read_artifact for the body] ${refs}`;
+    }
+    messages.push({ role: turn.role, content });
+  }
+  return messages;
+}
+
+/** Rebuild the DERIVED boot-replay cache (`thread.jsonl`) from the ledger, compacting older turns
+ *  into the rolling summary. Called through the `recordTurnOutcome` seam (Plan 05 Ph3): the summary
+ *  is written HERE, not recorded in the ledger — the ledger stays append-only truth. Returns the
+ *  compaction so the caller can surface it. */
+export function rebuildReplayCache(ws: string, agent: string, opts?: { keepRecentTurns?: number }): ReplayCompaction {
+  const keep = opts?.keepRecentTurns != null && opts.keepRecentTurns >= 0 ? opts.keepRecentTurns : DEFAULT_REPLAY_KEEP_TURNS;
+  const full = buildReplayMessages(ws, agent);
+  const compacted = compactReplay(full, keep);
+  writeThread(ws, agent, compacted.messages);
+  if (compacted.foldedTurns > 0) {
+    log.debug(
+      `conversation replay compacted for ${agent}: folded ${compacted.foldedTurns} turn(s), ` +
+        `${estimateTokens(contentToText(compacted.summaryText ?? ""))} summary tok, ${keep} kept verbatim`,
+    );
+  }
+  return compacted;
+}

package/src/core/costs.ts

@@ -0,0 +1,97 @@
+/** Plan 09: cross-session cost rollup for `/costs`. Reads run TRACES (the same source /runs and
+ *  /trace use) and aggregates each run's OWN spend by agent, day, and model — never trace.aggregate
+ *  (which folds in child runs, so summing across the list would double-count). Each run's OWN spend =
+ *  its primary loop (tokens/costUsd) PLUS its delegation-checker (verifierTokens/verifierCostUsd): the
+ *  verifier makes real, metered model calls but writes NO child trace, so adding its spend here counts
+ *  it exactly once. HONESTY RULE: a subscription run records costUsd:null (unmeasurable) — its TOKENS
+ *  (loop + verifier) are always reported, and it is NEVER counted as $0 nor mixed into a USD total.
+ *  Tokens are the hard, always-honest number; USD is a supplement shown only where genuinely priced.
+ *  SCOPE: /costs covers RUN TRACES — the agent loop and its delegation verifier. The `/teach` coaching
+ *  distiller (src/coaching/teach.ts) runs OUTSIDE any run and produces no trace; its spend IS metered
+ *  against the squad ceiling (spend-ledger.ts) but is not itemized here (there is no trace to attach it to). */
+import type { RunTrace } from "@taicho-ai/contracts/trace";
+
+export interface CostGroup {
+  key: string;
+  runs: number;
+  tokens: number;
+  costUsd: number;            // sum over PRICED runs only (costUsd is a finite number)
+  subscriptionRuns: number;   // runs with costUsd:null — USD unmeasurable, reported as tokens
+}
+
+export interface CostRollup {
+  totals: CostGroup;
+  byAgent: CostGroup[];
+  byDay: CostGroup[];
+  byModel: CostGroup[];
+}
+
+function blank(key: string): CostGroup {
+  return { key, runs: 0, tokens: 0, costUsd: 0, subscriptionRuns: 0 };
+}
+
+function accrue(g: CostGroup, t: RunTrace): void {
+  g.runs += 1;
+  // Own spend = primary loop + this run's delegation verifier (no child trace holds the verifier's
+  // spend, so it's counted exactly once here).
+  g.tokens += t.tokens + t.verifierTokens;
+  if (t.costUsd == null) g.subscriptionRuns += 1; // subscription/unmeasurable — tokens only, never a $0
+  else g.costUsd += t.costUsd + t.verifierCostUsd; // priced run ⇒ include the verifier's USD too
+}
+
+/** The "by provider" dimension. We record the resolved model id in the trace; group by it, falling
+ *  back to the costNote (subscription) or "unknown" for pre-Plan-09 / headless traces without one. */
+function modelKey(t: RunTrace): string {
+  return t.model ?? (t.costNote === "subscription" ? "subscription" : "unknown");
+}
+
+function groupBy(traces: RunTrace[], keyOf: (t: RunTrace) => string): CostGroup[] {
+  const map = new Map<string, CostGroup>();
+  for (const t of traces) {
+    const k = keyOf(t);
+    let g = map.get(k);
+    if (!g) { g = blank(k); map.set(k, g); }
+    accrue(g, t);
+  }
+  // Highest-spend first (by tokens — the always-present number).
+  return [...map.values()].sort((a, b) => b.tokens - a.tokens);
+}
+
+export function rollupCosts(traces: RunTrace[]): CostRollup {
+  const totals = blank("total");
+  for (const t of traces) accrue(totals, t);
+  return {
+    totals,
+    byAgent: groupBy(traces, (t) => t.agent),
+    byDay: groupBy(traces, (t) => t.started.slice(0, 10)),
+    byModel: groupBy(traces, modelKey),
+  };
+}
+
+/** Render one group line: always tokens; USD only when some priced spend exists; a subscription note
+ *  when any run in the group was unmeasurable. Never prints "$0.00" as if it were a real measured cost. */
+function fmtGroup(g: CostGroup, pad: number): string {
+  const usd = g.costUsd > 0 ? ` · $${g.costUsd.toFixed(4)}` : "";
+  const sub = g.subscriptionRuns > 0 ? ` · ${g.subscriptionRuns} subscription run(s) (tokens only)` : "";
+  return `    ${g.key.padEnd(pad)}  ${g.runs} run(s) · ${g.tokens.toLocaleString()} tok${usd}${sub}`;
+}
+
+function section(title: string, groups: CostGroup[]): string[] {
+  if (!groups.length) return [];
+  const pad = Math.min(28, Math.max(...groups.map((g) => g.key.length)));
+  return [`  ${title}:`, ...groups.map((g) => fmtGroup(g, pad))];
+}
+
+/** Format the rollup into REPL lines. Leads with the honest total (tokens), then by agent/day/model. */
+export function formatCostRollup(r: CostRollup): string[] {
+  if (r.totals.runs === 0) return ["  (no runs yet — nothing to cost)"];
+  const t = r.totals;
+  const usd = t.costUsd > 0 ? `, $${t.costUsd.toFixed(4)} priced` : "";
+  const sub = t.subscriptionRuns > 0 ? `, ${t.subscriptionRuns} subscription run(s) (tokens only — no USD)` : "";
+  return [
+    `  total: ${t.runs} run(s), ${t.tokens.toLocaleString()} tok${usd}${sub}`,
+    ...section("by agent", r.byAgent),
+    ...section("by day", r.byDay),
+    ...section("by model", r.byModel),
+  ];
+}

package/src/core/discovery.ts

@@ -0,0 +1,22 @@
+/** Keyword discovery over the registry index — scales to large rosters via one SQL scan upstream.
+ *  Semantic embeddings (store/vectors.ts) are a deferred upgrade. */
+import type { RegistryRow } from "../store/roster";
+
+export interface AgentHit { id: string; role: string; score: number; }
+
+const tokenize = (s: string): string[] => s.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+
+export function rankAgents(rows: RegistryRow[], query: string, k: number): AgentHit[] {
+  const q = new Set(tokenize(query));
+  if (q.size === 0) return [];
+  const scored: AgentHit[] = [];
+  for (const r of rows) {
+    if (r.is_root) continue;
+    const terms = tokenize(`${r.id} ${r.role}`);
+    let overlap = 0;
+    for (const t of terms) if (q.has(t)) overlap++;
+    if (overlap > 0) scored.push({ id: r.id, role: r.role, score: overlap });
+  }
+  scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  return scored.slice(0, k);
+}

package/src/core/draft.ts

@@ -0,0 +1,6 @@
+/** Merge a proposal card's edited field strings over the original draft (non-empty overrides only). */
+export function mergeDraft<T extends Record<string, unknown>>(original: T, edits: Record<string, string>): T {
+  const out: Record<string, unknown> = { ...original };
+  for (const [k, v] of Object.entries(edits)) if (v != null && v !== "") out[k] = v;
+  return out as T;
+}