@taicho-ai/framework 0.1.0

package/src/store/skills.ts

@@ -0,0 +1,89 @@
+/** Skill store: one file per skill at skills/<id>.md (YAML frontmatter = the skill minus `body`,
+ *  body = the procedure). Files are canon; the `skills` table is a rebuildable index. Mirrors
+ *  store/knowledge.ts + store/policy.ts. */
+import { YAML } from "bun";
+import type { Database } from "bun:sqlite";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { Skill } from "@taicho-ai/contracts/skill";
+import { paths } from "./files";
+import { log } from "../core/logger";
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+export function mkSkillId(): string {
+  return "skill_" + Math.random().toString(36).slice(2, 10);
+}
+
+export function serializeSkill(s: Skill): string {
+  const { body, ...meta } = s;
+  return `---\n${YAML.stringify(meta, null, 2)}\n---\n${body}\n`;
+}
+
+export function parseSkill(text: string): Skill {
+  const m = FRONTMATTER.exec(text);
+  if (!m) throw new Error("skill file missing YAML frontmatter");
+  const meta = YAML.parse(m[1]) as Record<string, unknown>;
+  return Skill.parse({ ...meta, body: m[2].trim() });
+}
+
+export function writeSkill(ws: string, db: Database, skill: Skill): void {
+  mkdirSync(paths.skillsDir(ws), { recursive: true });
+  writeFileSync(paths.skillFile(ws, skill.id), serializeSkill(skill));
+  indexSkill(db, skill);
+}
+
+export function readSkill(ws: string, id: string): Skill | null {
+  const f = paths.skillFile(ws, id);
+  if (!existsSync(f)) return null;
+  try { return parseSkill(readFileSync(f, "utf8")); } catch { return null; }
+}
+
+export function listSkills(ws: string): Skill[] {
+  const dir = paths.skillsDir(ws);
+  if (!existsSync(dir)) return [];
+  const out: Skill[] = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".md")) continue;
+    try { out.push(parseSkill(readFileSync(join(dir, f), "utf8"))); }
+    catch (e) { log.warn(`skipping skill ${f}`, e); }
+  }
+  return out;
+}
+
+export function deleteSkill(ws: string, db: Database, id: string): boolean {
+  const f = paths.skillFile(ws, id);
+  const existed = existsSync(f);
+  if (existed) rmSync(f);
+  db.query("DELETE FROM skills WHERE id = ?").run(id);
+  return existed;
+}
+
+export function indexSkill(db: Database, s: Skill): void {
+  db.query(
+    `INSERT INTO skills (id, name, description, tags, status, body, updated)
+     VALUES (?, ?, ?, ?, ?, ?, unixepoch())
+     ON CONFLICT(id) DO UPDATE SET
+       name=excluded.name, description=excluded.description, tags=excluded.tags,
+       status=excluded.status, body=excluded.body, updated=unixepoch()`,
+  ).run(s.id, s.name, s.description, JSON.stringify(s.tags), s.status, s.body);
+}
+
+export interface SkillRow { id: string; name: string; description: string; tags: string[]; status: string; body: string }
+
+export function getActiveSkills(db: Database): SkillRow[] {
+  const rows = db.query("SELECT id, name, description, tags, status, body FROM skills WHERE status = 'active' ORDER BY id")
+    .all() as { id: string; name: string; description: string; tags: string | null; status: string; body: string }[];
+  return rows.map((r) => ({ ...r, tags: r.tags ? (JSON.parse(r.tags) as string[]) : [] }));
+}
+
+/** Rebuild the skills index from the canonical files (proves files-are-canon). */
+export function reindexSkills(ws: string, db: Database): void {
+  db.exec("DELETE FROM skills");
+  const seen = new Map<string, string>(); // name -> id, to warn on duplicate names
+  for (const s of listSkills(ws)) {
+    if (seen.has(s.name)) log.warn(`duplicate skill name "${s.name}" (${seen.get(s.name)} and ${s.id}); use_skill resolves the first match`);
+    seen.set(s.name, s.id);
+    indexSkill(db, s);
+  }
+}

package/src/store/sources.ts

@@ -0,0 +1,58 @@
+/** Source-document discovery + hash tracking. Files in kb/sources/ are admin-authored inputs; each
+ *  is hashed so the librarian re-extracts only what changed. Mirrors store/knowledge.ts (files canon,
+ *  kb_sources = derived index of last-synced hashes). */
+import type { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { paths } from "./files";
+import { log } from "../core/logger";
+
+const SOURCE_EXT = /\.(md|txt)$/i;
+
+export function hashContent(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 12);
+}
+
+export interface DiscoveredSource { path: string; content: string; hash: string }
+
+export function listSourceFiles(ws: string): DiscoveredSource[] {
+  const dir = paths.kbSourceDir(ws);
+  if (!existsSync(dir)) return [];
+  const out: DiscoveredSource[] = [];
+  for (const name of readdirSync(dir)) {
+    if (!SOURCE_EXT.test(name)) continue;
+    try {
+      const content = readFileSync(join(dir, name), "utf8");
+      out.push({ path: `sources/${name}`, content, hash: hashContent(content) });
+    } catch (e) { log.warn(`skipping source ${name}`, e); }
+  }
+  return out;
+}
+
+export function readTrackedSources(db: Database): Map<string, string> {
+  const rows = db.query("SELECT path, hash FROM kb_sources").all() as { path: string; hash: string }[];
+  return new Map(rows.map((r) => [r.path, r.hash]));
+}
+
+export function upsertSourceHash(db: Database, path: string, hash: string): void {
+  db.query(
+    "INSERT INTO kb_sources (path, hash, updated) VALUES (?, ?, unixepoch()) " +
+    "ON CONFLICT(path) DO UPDATE SET hash = excluded.hash, updated = unixepoch()",
+  ).run(path, hash);
+}
+
+export function deleteSourceHash(db: Database, path: string): void {
+  db.query("DELETE FROM kb_sources WHERE path = ?").run(path);
+}
+
+export interface SourceDiff { changed: DiscoveredSource[]; deleted: string[] }
+
+export function diffSources(ws: string, db: Database): SourceDiff {
+  const tracked = readTrackedSources(db);
+  const onDisk = listSourceFiles(ws);
+  const seen = new Set(onDisk.map((s) => s.path));
+  const changed = onDisk.filter((s) => tracked.get(s.path) !== s.hash);
+  const deleted = [...tracked.keys()].filter((p) => !seen.has(p));
+  return { changed, deleted };
+}

package/src/store/spend-ledger.ts

@@ -0,0 +1,114 @@
+/** Plan 09 + Plan 19: rolling spend ceilings, at two scopes. The agent loop is the one meter (tokens +
+ *  advisory USD); this is the durable rolling counter it reads/commits against so ceilings SPAN SESSIONS.
+ *
+ *  Counters are keyed by scope × UTC day (YYYY-MM-DD) / ISO week (YYYY-Www): when the day/week rolls over
+ *  the key changes and the new period naturally reads 0 — no explicit reset. Files/traces stay canon for
+ *  reporting (`/costs`); this table is a fast, purpose-built enforcement counter, not a second ledger of
+ *  record. USD is only ever accumulated for PRICED runs — a subscription/unpriced call commits 0 USD (its
+ *  tokens still count), so a USD ceiling never fabricates spend it cannot measure.
+ *
+ *  A run on a team is metered against BOTH scopes in one transaction: the team's ceiling and the squad's.
+ *  A team ceiling can therefore stop a run the squad ceiling would happily have allowed. */
+import type { Database } from "bun:sqlite";
+import { DEFAULT_TEAM_ID } from "@taicho-ai/contracts/team";
+import {
+  SQUAD_SCOPE, teamScope, hasCeilings,
+  type SpendScope, type SpendCeilings, type SpendTotals, type SpendLedger,
+} from "@taicho-ai/agent";
+export {
+  SQUAD_SCOPE, teamScope, hasCeilings, ceilingHit, exhaustionMessage,
+  type SpendScope, type SpendCeilings, type SpendTotals, type SpendLedger,
+} from "@taicho-ai/agent";
+
+/** The scopes a run by an agent on these teams is metered against (Plan 22: an agent may be on several).
+ *  Every explicit team the agent belongs to gets its own ceiling, plus the always-present squad. The
+ *  implicit `default` team is dropped — it IS the squad, so metering it separately would double-count.
+ *  Order matters only for which exhaustion message the captain sees first, and the narrower (team) ones
+ *  come before the squad because they are more actionable. */
+export function scopesFor(teams?: string[] | string | null): SpendScope[] {
+  const list = teams == null ? [] : Array.isArray(teams) ? teams : [teams];
+  const explicit = [...new Set(list.filter((t) => t && t !== DEFAULT_TEAM_ID))];
+  return [...explicit.map(teamScope), SQUAD_SCOPE];
+}
+
+/** Every ceiling this session enforces: the squad's, and each configured team's. */
+export interface CeilingConfig {
+  squad?: SpendCeilings;
+  teams?: Record<string, SpendCeilings | undefined>;
+}
+
+/** The seam the loop enforces against: read a scope's running total, commit a call's spend to every
+ *  scope it belongs to. Bound to the DB + configured ceilings so the loop stays provider-agnostic. */
+/** True when at least one ceiling is configured — callers skip building a ledger (and its per-call
+ *  DB reads) entirely when there's nothing to enforce, preserving pre-Plan-09 behavior. */
+/** True when the squad OR any team has a ceiling. With none, the whole subsystem stays off. */
+export function hasAnyCeilings(c: CeilingConfig): boolean {
+  return hasCeilings(c.squad) || Object.values(c.teams ?? {}).some((t) => hasCeilings(t));
+}
+
+/** Which ceiling (if any) the current running total has already reached — a human message, else null.
+ *  Uses `>=` so it refuses the NEXT call once a limit is met, mirroring the per-run cap check. */
+/** UTC calendar day key — matches trace.ts's dateStamp so /runs and the ledger agree on "today". */
+export function dayKey(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+/** ISO-8601 week key (YYYY-Www). The week's year is decided by its Thursday, so late-December /
+ *  early-January days land in the correct ISO year — the standard algorithm. */
+export function isoWeekKey(date: Date): string {
+  const d = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  const dayNum = (d.getUTCDay() + 6) % 7; // Mon=0 … Sun=6
+  d.setUTCDate(d.getUTCDate() - dayNum + 3); // move to this week's Thursday
+  const thursday = d.getTime();
+  const firstThursday = new Date(Date.UTC(d.getUTCFullYear(), 0, 4));
+  const firstDayNum = (firstThursday.getUTCDay() + 6) % 7;
+  firstThursday.setUTCDate(firstThursday.getUTCDate() - firstDayNum + 3);
+  const week = 1 + Math.round((thursday - firstThursday.getTime()) / (7 * 86_400_000));
+  return `${d.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+function readPeriod(db: Database, scope: SpendScope, kind: "day" | "week", key: string): { tokens: number; cost: number } {
+  const r = db
+    .query("SELECT tokens, cost_usd FROM squad_spend WHERE scope = ? AND period_kind = ? AND period_key = ?")
+    .get(scope, kind, key) as { tokens: number; cost_usd: number } | null;
+  return { tokens: r?.tokens ?? 0, cost: r?.cost_usd ?? 0 };
+}
+
+/** Read a scope's current day + week running totals without building a full ledger (used by /costs'
+ *  header and tests). Reflects only spend committed while a ceiling was configured. */
+export function readSpendTotals(db: Database, now: () => Date = () => new Date(), scope: SpendScope = SQUAD_SCOPE): SpendTotals {
+  const d = now();
+  const day = readPeriod(db, scope, "day", dayKey(d));
+  const week = readPeriod(db, scope, "week", isoWeekKey(d));
+  return { dayTokens: day.tokens, weekTokens: week.tokens, dayCostUsd: day.cost, weekCostUsd: week.cost };
+}
+
+/** A DB-backed spend ledger. `now` is injectable so tests can cross day/week boundaries deterministically. */
+export function makeSpendLedger(db: Database, config: CeilingConfig, now: () => Date = () => new Date()): SpendLedger {
+  const upsert = db.query(
+    `INSERT INTO squad_spend (scope, period_kind, period_key, tokens, cost_usd, updated)
+     VALUES (?, ?, ?, ?, ?, unixepoch())
+     ON CONFLICT(scope, period_kind, period_key) DO UPDATE SET
+       tokens = tokens + excluded.tokens,
+       cost_usd = cost_usd + excluded.cost_usd,
+       updated = unixepoch()`,
+  );
+  return {
+    ceilings: (scope) => {
+      const c = scope === SQUAD_SCOPE ? config.squad : config.teams?.[scope.slice("team:".length)];
+      return hasCeilings(c) ? c : undefined;
+    },
+    current: (scope) => readSpendTotals(db, now, scope),
+    add: (scopes, { tokens, costUsd }) => {
+      if ((tokens === 0 && costUsd === 0) || !scopes.length) return;
+      const d = now();
+      // One transaction across every scope: a crash must not leave the team charged and the squad not.
+      db.transaction(() => {
+        for (const scope of scopes) {
+          upsert.run(scope, "day", dayKey(d), tokens, costUsd);
+          upsert.run(scope, "week", isoWeekKey(d), tokens, costUsd);
+        }
+      })();
+    },
+  };
+}

package/src/store/task-state.ts

@@ -0,0 +1,267 @@
+/** Task state separates "the model replied" from "the requested work is actually done".
+ *
+ *  Plan 04 promotes this from a write-only per-turn audit record into a persistent TASK QUEUE:
+ *  a task can outlive the turn that created it (a background `dispatch_task`), survives a restart
+ *  (files under tasks/ are canon; a rebuildable SQLite `tasks` table is the query index), and is
+ *  listable/cancellable via `/tasks`. A synchronous chat turn is just a task the captain watches. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import type { Database } from "bun:sqlite";
+import { paths } from "./files";
+import type { RunTrace, VerificationVerdict } from "@taicho-ai/contracts/trace";
+
+export type TaskStepStatus = "not_started" | "running" | "completed" | "failed" | "blocked" | "interrupted" | "verified";
+/** Task lifecycle. `queued` (dispatched, awaiting a concurrency slot) and `cancelled` are Plan 04
+ *  additions for background tasks; the rest are shared with the watched-turn (chat) path. */
+export type TaskStatus =
+  | "requested" | "queued" | "running" | "completed" | "partial"
+  | "failed" | "blocked" | "interrupted" | "cancelled";
+
+/** A criteria→verdict record surfaced from a delegation's independent check (Plan 06). Replaces the
+ *  never-populated `verifiedClaims`: this field is populated from trace.verification (root + children). */
+export interface TaskVerification {
+  criteria: string;
+  verdict: VerificationVerdict;
+  runId: string;      // the checked child run
+  retried: boolean;
+}
+
+export type TaskKind = "chat" | "background";
+
+/** The canonical set of TERMINAL task statuses — a settled task whose outcome must not be overwritten.
+ *  Single source of truth so the cancel guard (cancelTaskState) and the await guard (App's awaitTask)
+ *  can never drift: cancelling an already-`blocked`/`interrupted`/`partial` task must be a no-op, not
+ *  an outcome-erasing overwrite. Non-terminal = requested | queued | running. */
+export const TERMINAL_TASK_STATUS = new Set<TaskStatus>([
+  "completed", "partial", "failed", "blocked", "interrupted", "cancelled",
+]);
+
+export interface TaskState {
+  taskId: string;
+  title: string;
+  status: TaskStatus;
+  created: string;
+  updated: string;
+  rootRunId: string;
+  userTurnId?: string;
+  kind?: TaskKind;         // "chat" (a turn the captain watches) | "background" (dispatch_task); default chat
+  agent?: string;          // the agent this task runs on (target of a dispatch)
+  goal?: string;           // the dispatched goal (background tasks); chat tasks use `title`
+  resultRef?: string;      // hand-off BY REFERENCE: an artifact handle (id@vN) or the root run id
+  summary?: string;        // short settle summary (truncated); check_task returns this, never a payload
+  steps: { name: string; status: TaskStepStatus; runId?: string; details?: string }[];
+  verifications: TaskVerification[];
+}
+
+const SUMMARY_CAP = 500;
+
+function taskFile(ws: string, taskId: string): string {
+  return join(paths.taskDir(ws), `${taskId}.json`);
+}
+
+export function taskIdForRun(runId: string): string {
+  return `task_${runId.replace("/", "_")}`;
+}
+
+/** A fresh id for a background task — created before its run reserves a runId (dispatch returns the
+ *  taskId immediately), so it can't derive from the runId the way a watched-turn task does. */
+export function mkTaskId(): string {
+  return `task_bg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function writeTask(ws: string, task: TaskState, db?: Database): void {
+  mkdirSync(paths.taskDir(ws), { recursive: true });
+  // Plan 20: temp + rename (atomic on POSIX) — a crash mid-write used to truncate the .json, which
+  // reindexTasks then silently skipped (the record vanished from the index). The temp suffix isn't
+  // .json, so a leftover from a crashed write is ignored by the readdir filters. Mirrors schedules.ts.
+  const dest = taskFile(ws, task.taskId);
+  const tmp = `${dest}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(task, null, 2));
+  renameSync(tmp, dest);
+  if (db) indexTask(db, task);
+}
+
+// ── SQLite index (rebuildable from files; the query surface for /tasks) ──────────────────────────
+
+export function indexTask(db: Database, task: TaskState): void {
+  db.query(
+    `INSERT INTO tasks (id, agent, goal, status, kind, root_run_id, result_ref, summary, created, updated)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       agent=excluded.agent, goal=excluded.goal, status=excluded.status, kind=excluded.kind,
+       root_run_id=excluded.root_run_id, result_ref=excluded.result_ref, summary=excluded.summary,
+       updated=excluded.updated`,
+  ).run(
+    task.taskId, task.agent ?? null, task.goal ?? task.title, task.status, task.kind ?? "chat",
+    task.rootRunId || null, task.resultRef ?? null, task.summary ?? null, task.created, task.updated,
+  );
+}
+
+export interface TaskIndexRow {
+  id: string; agent: string | null; goal: string | null; status: TaskStatus;
+  kind: TaskKind; root_run_id: string | null; result_ref: string | null;
+  summary: string | null; created: string | null; updated: string | null;
+}
+
+/** List indexed tasks, newest-updated first. `activeOrBackground` (the `/tasks` default view) hides
+ *  the noise of completed watched turns: only background tasks + any non-terminal task show. */
+export function listTaskIndex(db: Database, opts: { activeOrBackground?: boolean } = {}): TaskIndexRow[] {
+  const rows = opts.activeOrBackground
+    ? db.query<TaskIndexRow, []>(
+        `SELECT * FROM tasks WHERE kind = 'background' OR status IN ('queued','running','interrupted','requested')
+         ORDER BY updated DESC`,
+      ).all()
+    : db.query<TaskIndexRow, []>(`SELECT * FROM tasks ORDER BY updated DESC`).all();
+  return rows;
+}
+
+/** Rebuild the tasks index from the canonical tasks/*.json files (files are truth; DB is a cache). */
+export function reindexTasks(ws: string, db: Database): number {
+  db.query("DELETE FROM tasks").run();
+  const dir = paths.taskDir(ws);
+  if (!existsSync(dir)) return 0;
+  let n = 0;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const task = JSON.parse(readFileSync(join(dir, f), "utf8")) as TaskState;
+      indexTask(db, task);
+      n++;
+    } catch { /* skip an unparseable/partial task file */ }
+  }
+  return n;
+}
+
+// ── lifecycle ────────────────────────────────────────────────────────────────────────────────────
+
+export function createTaskState(ws: string, input: { runId: string; title: string; userTurnId?: string }, db?: Database): TaskState {
+  const now = new Date().toISOString();
+  const task: TaskState = {
+    taskId: taskIdForRun(input.runId),
+    title: input.title,
+    status: "running",
+    created: now,
+    updated: now,
+    rootRunId: input.runId,
+    userTurnId: input.userTurnId,
+    kind: "chat",
+    agent: input.runId.split("/")[0],
+    goal: input.title,
+    steps: [{ name: "root_run", status: "running", runId: input.runId }],
+    verifications: [],
+  };
+  writeTask(ws, task, db);
+  return task;
+}
+
+/** Create a persistent BACKGROUND task record (Plan 04) in status `queued`. rootRunId is unknown
+ *  until the detached run reserves it — patched in later via setTaskFields. */
+export function createBackgroundTask(ws: string, db: Database, input: { taskId: string; agent: string; goal: string }): TaskState {
+  const now = new Date().toISOString();
+  const task: TaskState = {
+    taskId: input.taskId,
+    title: input.goal,
+    status: "queued",
+    created: now,
+    updated: now,
+    rootRunId: "",
+    kind: "background",
+    agent: input.agent,
+    goal: input.goal,
+    steps: [{ name: "root_run", status: "not_started" }],
+    verifications: [],
+  };
+  writeTask(ws, task, db);
+  return task;
+}
+
+export function readTaskState(ws: string, taskId: string): TaskState | null {
+  const f = taskFile(ws, taskId);
+  if (!existsSync(f)) return null;
+  return JSON.parse(readFileSync(f, "utf8")) as TaskState;
+}
+
+/** Patch a task's mutable fields (status/rootRunId/result/summary) on the file AND the index. */
+export function setTaskFields(
+  ws: string,
+  db: Database,
+  taskId: string,
+  patch: Partial<Pick<TaskState, "status" | "rootRunId" | "resultRef" | "summary">> & { stepStatus?: TaskStepStatus },
+): TaskState | null {
+  const task = readTaskState(ws, taskId);
+  if (!task) return null;
+  if (patch.status) task.status = patch.status;
+  if (patch.rootRunId !== undefined) {
+    task.rootRunId = patch.rootRunId;
+    if (task.steps[0]) task.steps[0].runId = patch.rootRunId;
+  }
+  if (patch.resultRef !== undefined) task.resultRef = patch.resultRef;
+  if (patch.summary !== undefined) task.summary = patch.summary.slice(0, SUMMARY_CAP);
+  if (patch.stepStatus && task.steps[0]) task.steps[0].status = patch.stepStatus;
+  task.updated = new Date().toISOString();
+  writeTask(ws, task, db);
+  return task;
+}
+
+/** Mark a task cancelled (the caller aborts the live run separately). No-op if already terminal —
+ *  cancelling a settled task (completed/partial/failed/blocked/interrupted/cancelled) must NOT erase
+ *  its recorded outcome. Guard aligned with TERMINAL_TASK_STATUS (was too narrow, dropping
+ *  blocked/interrupted/partial). */
+export function cancelTaskState(ws: string, db: Database, taskId: string): TaskState | null {
+  const task = readTaskState(ws, taskId);
+  if (!task) return null;
+  if (TERMINAL_TASK_STATUS.has(task.status)) return task;
+  task.status = "cancelled";
+  task.updated = new Date().toISOString();
+  writeTask(ws, task, db);
+  return task;
+}
+
+/** Boot reconciliation (Plan 04 Phase 5): a task left `running`/`queued` means the process died
+ *  mid-flight — mark it `interrupted`. Returns the reconciled tasks so the captain can be told
+ *  (report-and-ask; auto-resume is deferred per the closed Phase 0 decision). */
+export function reconcileTasks(ws: string, db: Database): TaskState[] {
+  const dir = paths.taskDir(ws);
+  if (!existsSync(dir)) return [];
+  const reconciled: TaskState[] = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    let task: TaskState;
+    try { task = JSON.parse(readFileSync(join(dir, f), "utf8")) as TaskState; }
+    catch { continue; }
+    if (task.status === "running" || task.status === "queued") {
+      task.status = "interrupted";
+      if (task.steps[0] && task.steps[0].status === "running") task.steps[0].status = "interrupted";
+      task.updated = new Date().toISOString();
+      writeTask(ws, task, db);
+      reconciled.push(task);
+    } else {
+      indexTask(db, task); // keep the index consistent with every file, reconciled or not
+    }
+  }
+  return reconciled;
+}
+
+export function updateTaskFromTrace(ws: string, taskId: string, trace: RunTrace, children: RunTrace[] = [], db?: Database): TaskState | null {
+  const task = readTaskState(ws, taskId);
+  if (!task) return null;
+  const outcomeToStep = (outcome: RunTrace["outcome"]): TaskStepStatus => outcome === "completed" ? "completed" : outcome;
+  task.updated = new Date().toISOString();
+  task.rootRunId = task.rootRunId || trace.id;
+  task.steps = task.steps.filter((s) => s.name === "root_run");
+  task.steps[0] = { name: "root_run", status: outcomeToStep(trace.outcome), runId: trace.id };
+  for (const child of children) {
+    task.steps.push({ name: `child:${child.agent}`, status: outcomeToStep(child.outcome), runId: child.id, details: child.task });
+  }
+  // Populate the verification record from the checks this run (and its children) actually ran.
+  task.verifications = [trace, ...children].flatMap((t) =>
+    (t.verification ?? []).map((v) => ({ criteria: v.criteria, verdict: v.verdict, runId: v.runId, retried: v.retried })),
+  );
+  if (trace.outcome === "completed" && children.every((c) => c.outcome === "completed")) task.status = "completed";
+  else if (trace.outcome === "blocked" || children.some((c) => c.outcome === "blocked")) task.status = "blocked";
+  else if (trace.outcome === "interrupted" || children.some((c) => c.outcome === "interrupted")) task.status = "interrupted";
+  else if (trace.outcome === "failed" || children.some((c) => c.outcome === "failed")) task.status = "failed";
+  else task.status = "partial";
+  writeTask(ws, task, db);
+  return task;
+}