catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/tree-path.ts

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { CatherdError } from "../domain/errors.ts";
+import type { Run } from "./run-store.ts";
+
+/** `<run dir>/trees/<m>`: where milestone `m` of a base run works. */
+export const treeDir = (run: Run, m: string): string => join(run.dir, "trees", m);
+
+/** The marker beside the tree, never inside it, that Setup: finished. */
+export const readyFile = (run: Run, m: string): string => join(run.dir, "trees", `${m}.ready`);
+
+/**
+ * Where milestone `m` works: its worktree in a base run once it exists, else the repo (a run without base, the
+ * run itself, a milestone not claimed yet). A claimed milestone whose folder is gone is an error, never the repo:
+ * its commits, checks and merge would land in the owner's own checkout. Kept apart from milestone-tree.ts so the services that only ask
+ * where a milestone works do not import the claiming code, which imports them.
+ */
+export function treeOf(run: Run, m: string | null): string {
+  if (!run.meta.base || m === null) return run.meta.repo;
+  const tree = treeDir(run, m);
+  if (existsSync(tree)) return tree;
+  if (existsSync(readyFile(run, m)))
+    throw new CatherdError("E_TREE", `the worktree of ${m} is gone: ${tree}`, {
+      fix: "restore the tree (git worktree add it back on the milestone's branch) or cancel the run",
+    });
+  return run.meta.repo;
+}

package/src/services/verifier-brief.ts

@@ -0,0 +1,23 @@
+import { withGateNotes } from "../domain/gate-brief.ts";
+import { gateEnvLines, readGateEnv } from "./gate-env.ts";
+import { recordedItems } from "./gate-service.ts";
+import type { Run } from "./run-store.ts";
+
+// Plan 23: a dispatched verifier's brief ends with the gate's rules and the run's facts: the milestone's
+// recorded items (reuse their names), the failed ones (a re-check runs them first, each command capped), and
+// the repo's gate environment.
+
+/** The milestone a verifier dispatch checks: the first `M<n>` its name names as a word (verifier-M1 → M1). */
+export const milestoneOfName = (name: string): string | null =>
+  /(?:^|[^A-Za-z0-9])(M\d+)(?=$|[-._\s])/.exec(name)?.[1] ?? null;
+
+/** A verifier's brief with the gate notes, once; any other role's brief as it is. */
+export async function verifierBrief(run: Run, role: string, name: string, brief: string): Promise<string> {
+  if (role !== "verifier") return brief;
+  const milestone = milestoneOfName(name);
+  return withGateNotes(brief, {
+    milestone,
+    recorded: milestone ? await recordedItems(run, milestone) : [],
+    env: gateEnvLines(await readGateEnv(run.meta.repo)),
+  });
+}

package/src/services/verifier-step.ts

@@ -0,0 +1,48 @@
+import { liveSessionFile, readSessionFiles, type SessionFile } from "../infra/claude-session.ts";
+import { readJsonl } from "../infra/store.ts";
+import { gatesFile, latestVerifierStep, type VerifierStep } from "./gate-service.ts";
+import { readAgentRuns, readRecords, type Run } from "./run-store.ts";
+import { runOwner } from "./sessions.ts";
+
+/** What ended a verifier step (plan 22: a step nothing ends shows as live forever). */
+export type StepClosedBy = "gate_pass" | "agent-run" | "record" | "owner-gone";
+
+export interface VerifierStepView extends VerifierStep {
+  /** seconds since the step began */
+  secs: number;
+  open: boolean;
+  closedBy: StepClosedBy | null;
+}
+
+/**
+ * Plan 22: the verifier's latest step with its age, closed by the first evidence after it: a `gate_pass` of its
+ * item in this run, a native verifier's `record_agent_run`, a verifier dispatch's record, or its owner session
+ * gone (another session took the run since, or the owner's Claude Code session no longer runs). A Codex owner
+ * that still holds the run has no liveness to read: its step stays open until other evidence ends it.
+ */
+export function verifierStepView(
+  run: Run,
+  now: number,
+  files: () => SessionFile[] = readSessionFiles,
+): VerifierStepView | null {
+  const step = latestVerifierStep(run);
+  if (!step) return null;
+  const at = Date.parse(step.at) || 0;
+  const after = (t: string | undefined) => (Date.parse(t ?? "") || 0) >= at;
+  const passed = readJsonl<{ run?: unknown; item?: unknown; at?: string }>(
+    gatesFile(run.meta.repo),
+  ).rows.some((p) => p?.run === run.id && p.item === step.item && after(p.at));
+  const owner = runOwner(run);
+  const closedBy: StepClosedBy | null = passed
+    ? "gate_pass"
+    : readAgentRuns(run).some((a) => a.role === "verifier" && after(a.at))
+      ? "agent-run"
+      : readRecords(run).records.some((r) => r.role === "verifier" && after(r.endedAt))
+        ? "record"
+        : owner &&
+            ((Date.parse(owner.since) || 0) > at ||
+              (owner.host === "claude-code" && liveSessionFile(owner.sessionId, files()) === null))
+          ? "owner-gone"
+          : null;
+  return { ...step, secs: Math.max(0, Math.floor((now - at) / 1000)), open: closedBy === null, closedBy };
+}

package/src/services/workspace-admission.ts

@@ -0,0 +1,259 @@
+import { existsSync, readFileSync } from "node:fs";
+import { budgetStatus, formatBudget, type BudgetStatus, type Spend } from "../domain/budget.ts";
+import { CatherdError, errorMessage, isCatherdError } from "../domain/errors.ts";
+import type { Workspace, WorkspaceStep } from "../domain/workspace.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { gitToplevel, isAncestor } from "../infra/git.ts";
+import { writeTextAtomic } from "../infra/store.ts";
+import { spendOf } from "./budget.ts";
+import { pendingDispatches } from "./dispatches.ts";
+import { landedCommitOf, landedMilestones } from "./milestones.ts";
+import { readRecords, type Run, runPaths } from "./run-store.ts";
+import {
+  findWorkspace,
+  saveWorkspace,
+  WORKSPACE_LOCK_WAIT_MS,
+  workspaceChildren,
+  workspaceDirectory,
+  workspacePaths,
+} from "./workspace-store.ts";
+
+/**
+ * Count each recorded or unrecorded dispatch once; elapsed minutes belong to the parent and start at its first
+ * child (#43 finding 4), none before one. With `warnings`, a child whose cost evidence cannot be read is
+ * skipped and named there (status); without, it throws E_RUN_CORRUPT (admission against a cap, which cannot
+ * prove the cap holds without it).
+ */
+export async function workspaceSpend(
+  workspace: Workspace,
+  now: number,
+  children = workspaceChildren(workspace),
+  warnings?: string[],
+): Promise<Spend> {
+  const first = Math.min(...children.map((c) => Date.parse(c.meta.createdAt)).filter(Number.isFinite));
+  const total: Spend = {
+    minutes: Number.isFinite(first) ? Math.max(0, (now - first) / 60_000) : 0,
+    tokens: 0,
+    usd: 0,
+  };
+  for (const child of children) {
+    try {
+      const spent = await withFileLock(runPaths(child.dir).runs, () => {
+        const { records, corrupt } = readRecords(child);
+        if (corrupt) throw new CatherdError("E_RUN_CORRUPT", `run ${child.id} has unreadable cost records`);
+        return spendOf(child, records, pendingDispatches(child, now, records, true), now, true);
+      });
+      total.tokens += spent.tokens;
+      total.usd += spent.usd;
+    } catch (e) {
+      if (!warnings || !isCatherdError(e) || e.code !== "E_RUN_CORRUPT") throw e;
+      warnings.push(`spend leaves out ${child.id}: ${errorMessage(e)}`);
+    }
+  }
+  return total;
+}
+
+/** The workspace budget a child run's routing sees; a child whose evidence is unreadable counts nothing. */
+export async function workspaceBudget(run: Run, now: number): Promise<BudgetStatus | null> {
+  if (!run.meta.workspace) return null;
+  const workspace = findWorkspace(run.meta.workspace.id);
+  return budgetStatus(await workspaceSpend(workspace, now, undefined, []), workspace.budget);
+}
+
+/** Why a dependency keeps a step waiting: the dependency's step id and the reason, in words. */
+export interface Blocker {
+  step: string;
+  why: string;
+}
+
+/** The dependency's uncollected dispatches, read under its records lock: a reason, or null when none. */
+async function uncollected(child: Run, now: number): Promise<string | null> {
+  const step = child.meta.workspace?.step ?? child.id;
+  try {
+    const pending = await withFileLock(runPaths(child.dir).runs, () => {
+      const { records, corrupt } = readRecords(child);
+      if (corrupt) throw new CatherdError("E_RUN_CORRUPT", `run ${child.id} has unreadable dispatch records`);
+      return pendingDispatches(child, now, records, true);
+    });
+    return pending.length
+      ? `${step} has ${pending.length} dispatch(es) not collected (${pending.map((d) => d.admit.name).join(", ")})`
+      : null;
+  } catch (e) {
+    if (isCatherdError(e) && e.code === "E_RUN_CORRUPT") return `${step} cannot be read: ${e.message}`;
+    throw e;
+  }
+}
+
+/** A landed milestone that differs from the step's only by case: `m1` for `M1` (#43 finding 7). */
+const caseTwin = (landed: string[], milestone: string): string | undefined =>
+  landed.find((m) => m !== milestone && m.toLowerCase() === milestone.toLowerCase());
+
+/**
+ * #43 finding 8: the one dependency rule admission, child start and status share. A dependency releases its
+ * dependents once its child has landed the dependency's milestone and every dispatch it admitted is
+ * collected. Reads only the dependencies' own evidence (#43 finding 2); an unreadable one blocks, named.
+ */
+export async function dependencyBlockers(
+  workspace: Workspace,
+  step: WorkspaceStep,
+  children: Run[],
+  now: number,
+  o: { merge?: boolean } = {},
+): Promise<Blocker[]> {
+  const out: Blocker[] = [];
+  for (const id of step.dependsOn) {
+    const before = workspace.steps.find((s) => s.id === id);
+    const child = children.find((c) => c.meta.workspace?.step === id);
+    if (!before || !child) {
+      out.push({ step: id, why: `${id} has not started` });
+      continue;
+    }
+    const landed = landedMilestones(child);
+    if (!landed.includes(before.milestone)) {
+      const twin = caseTwin(landed, before.milestone);
+      out.push({
+        step: id,
+        why: `${id} has not landed ${before.milestone}${twin ? ` (it landed ${twin}: the step completes on ${before.milestone})` : ""}`,
+      });
+      continue;
+    }
+    const why = (await uncollected(child, now)) ?? (o.merge ? await unmerged(before, child) : null);
+    if (why) out.push({ step: id, why });
+  }
+  return out;
+}
+
+/**
+ * A `release: "merge"` step releases its dependents once its landed commit is an ancestor of its base ref
+ * (`git merge-base --is-ancestor`), in the repository as it stands: catherd never fetches or polls.
+ */
+async function unmerged(step: WorkspaceStep, child: Run): Promise<string | null> {
+  if (step.release !== "merge" || !step.base) return null;
+  const commit = landedCommitOf(child, step.milestone);
+  if (!commit) return `${step.id} has no landed commit for ${step.milestone} in its ledger`;
+  const merged = await isAncestor(child.meta.repo, commit, step.base);
+  if (merged === true) return null;
+  if (merged === false)
+    return `${step.id}'s ${step.milestone} (${commit.slice(0, 7)}) is not merged into ${step.base} yet: merge it, git fetch, then ask again`;
+  return `${step.id}: git cannot tell whether ${commit.slice(0, 7)} is in ${step.base} (does the ref exist in ${child.meta.repo}?)`;
+}
+
+export function withRunAdmission<T>(run: Run, now: () => number, admit: () => Promise<T>): Promise<T> {
+  return withWorkspaceAdmission(run, now, () => withFileLock(runPaths(run.dir).admission, admit));
+}
+
+/** Parent → child admission → child records; siblings share the actual admission boundary. */
+export async function withWorkspaceAdmission<T>(
+  run: Run,
+  clock: number | (() => number),
+  admit: () => Promise<T>,
+): Promise<T> {
+  const link = run.meta.workspace;
+  if (!link) return admit();
+  const workspace = findWorkspace(link.id);
+  // git outside the workspace lock (#43 finding 5): the checkout check needs no sibling to wait
+  if ((await gitToplevel(run.meta.repo)) !== run.meta.repo)
+    throw new CatherdError(
+      "E_IO_PATH",
+      `workspace repository of ${link.step} is no longer the captured git root`,
+    );
+  return withFileLock(
+    workspacePaths(workspaceDirectory(workspace.id)).admission,
+    async () => {
+      const now = typeof clock === "function" ? clock() : clock;
+      const children = workspaceChildren(workspace);
+      const step = workspace.steps.find((s) => s.id === link.step);
+      if (!step || !children.some((c) => c.id === run.id))
+        throw new CatherdError("E_INPUT_INVALID", "the run is not a member of this workspace execution", {
+          fix: "start the child with workspace_child_start",
+        });
+      // #43 finding 7: a landed step's child admits again (a post-land fix); its dependents wait for it
+      const blockers = await dependencyBlockers(workspace, step, children, now);
+      if (blockers.length)
+        throw new CatherdError(
+          "E_INPUT_INVALID",
+          `${step.id} is waiting: ${blockers.map((b) => b.why).join("; ")}`,
+          {
+            fix: "land the dependency's completion milestone and collect its finished dispatches first",
+          },
+        );
+      await assertWorkspaceBudget(workspace, now, children);
+      return admit();
+    },
+    { timeoutMs: WORKSPACE_LOCK_WAIT_MS },
+  );
+}
+
+/** Whether the budget caps anything: without a cap, no sibling's evidence is read (#43 finding 2). */
+const capped = (workspace: Workspace): boolean =>
+  Object.values(workspace.budget).some((v) => typeof v === "number");
+
+/** Refuses E_RUN_BUDGET once a capped workspace budget is spent; reads every child only when capped. */
+export async function assertWorkspaceBudget(
+  workspace: Workspace,
+  now: number,
+  children: Run[],
+): Promise<void> {
+  if (!capped(workspace)) return;
+  const budget = budgetStatus(await workspaceSpend(workspace, now, children), workspace.budget);
+  if (budget && budget.fraction >= 1)
+    throw new CatherdError("E_RUN_BUDGET", `the workspace budget is spent: ${formatBudget(budget)}`, {
+      fix: `finish with the work already admitted, or raise it: workspace_budget(${workspace.id}, …)`,
+    });
+}
+
+/**
+ * `workspace_budget`: sets the caps given (a number) or removes them (null), keeping the others; the owner's
+ * way to raise a spent budget without a new workspace (#43 finding 4). Returns the budget and its status.
+ */
+export async function setWorkspaceBudget(
+  deps: { now: () => number },
+  i: { workspace: string; minutes?: number | null; tokens?: number | null; usd?: number | null },
+): Promise<{ budget: Workspace["budget"]; spend: Spend; status: BudgetStatus | null }> {
+  const workspace = findWorkspace(i.workspace);
+  return withFileLock(
+    workspacePaths(workspaceDirectory(workspace.id)).admission,
+    async () => {
+      const budget: Workspace["budget"] = { ...findWorkspace(workspace.id).budget };
+      for (const key of ["minutes", "tokens", "usd"] as const) {
+        const v = i[key];
+        if (v === null) delete budget[key];
+        else if (v !== undefined) budget[key] = v;
+      }
+      const saved = saveWorkspace({ ...findWorkspace(workspace.id), budget });
+      const spend = await workspaceSpend(saved, deps.now(), undefined, []);
+      return { budget: saved.budget, spend, status: budgetStatus(spend, saved.budget) };
+    },
+    { timeoutMs: WORKSPACE_LOCK_WAIT_MS },
+  );
+}
+
+/** The shared contract is frozen when the first child starts, then copied into child dossiers. */
+export async function workspaceContract(i: {
+  workspace: string;
+  content?: string;
+}): Promise<{ path: string; content: string }> {
+  const workspace = findWorkspace(i.workspace);
+  const paths = workspacePaths(workspaceDirectory(workspace.id));
+  if (i.content === undefined)
+    return {
+      path: paths.contract,
+      content: existsSync(paths.contract) ? readFileSync(paths.contract, "utf8") : "",
+    };
+  return withFileLock(
+    paths.admission,
+    () => {
+      if (workspaceChildren(workspace).length)
+        throw new CatherdError(
+          "E_INPUT_INVALID",
+          "the workspace contract is frozen because a child has started",
+          {
+            fix: "start a new workspace execution to change the shared contract",
+          },
+        );
+      writeTextAtomic(paths.contract, i.content as string);
+      return { path: paths.contract, content: i.content as string };
+    },
+    { timeoutMs: WORKSPACE_LOCK_WAIT_MS },
+  );
+}

package/src/services/workspace-service.ts

@@ -0,0 +1,259 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { type Budget, budgetStatus } from "../domain/budget.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { WORKSPACE_LIMIT, WorkspaceIdSchema, WorkspaceSchema, type Workspace } from "../domain/workspace.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { gitToplevel } from "../infra/git.ts";
+import { indexPath } from "../infra/paths.ts";
+import { readIndexFile } from "../infra/slopalytics.ts";
+import { readVersioned, writeTextAtomic } from "../infra/store.ts";
+import { writeRunIndex } from "./catalog-service.ts";
+import { listDispatches } from "./dispatches.ts";
+import { landedCommits, landedMilestones } from "./milestones.ts";
+import { assertNotPaused, pausesOver } from "./pause.ts";
+import { writePin } from "./run-pin.ts";
+import type { Deps } from "./ports.ts";
+import { createRun, readRecords, type Run } from "./run-store.ts";
+import { claimRun, currentSession } from "./sessions.ts";
+import { refreshState } from "./state.ts";
+import { summarizeRun } from "./summary.ts";
+import { assertWorkspaceBudget, dependencyBlockers, workspaceSpend } from "./workspace-admission.ts";
+import {
+  createWorkspace,
+  findWorkspace,
+  unreadableWarning,
+  WORKSPACE_LOCK_WAIT_MS,
+  workspaceChildren,
+  workspaceDirectory,
+  workspaceListing,
+  workspacePaths,
+} from "./workspace-store.ts";
+
+const ManifestSchema = z.strictObject({
+  schema: z.literal(1),
+  repos: z
+    .record(WorkspaceIdSchema, z.string().min(1))
+    .refine((repos) => Object.keys(repos).length <= WORKSPACE_LIMIT),
+});
+const invalid = (message: string) => new CatherdError("E_INPUT_INVALID", message);
+
+function registry(root: string, repos?: Record<string, string>): Record<string, string> {
+  if (repos !== undefined) {
+    const parsed = ManifestSchema.safeParse({ schema: 1, repos });
+    if (!parsed.success) throw invalid("workspace repositories require safe aliases and nonempty paths");
+    return parsed.data.repos;
+  }
+  return readVersioned(join(root, "catherd.workspace.json"), ManifestSchema, 1).repos;
+}
+
+function workspaceRoot(root: string): string {
+  try {
+    const real = realpathSync(root);
+    if (!statSync(real).isDirectory()) throw new Error("not a directory");
+    return real;
+  } catch {
+    throw new CatherdError("E_IO_PATH", `workspace root is not an existing directory: ${root}`);
+  }
+}
+
+/** No repository discovery scan: paths are an explicit registry, relative to the workspace root. */
+export async function inspectWorkspace(
+  root: string,
+  repos?: Record<string, string>,
+): Promise<{ root: string; repos: Record<string, string> }> {
+  root = workspaceRoot(root);
+  const declared = registry(root, repos);
+  if (!Object.keys(declared).length) throw invalid("workspace requires at least one repository");
+  const canonical: Record<string, string> = {};
+  for (const [alias, path] of Object.entries(declared)) {
+    const top = await gitToplevel(resolve(root, path));
+    if (!top)
+      throw new CatherdError(
+        "E_IO_PATH",
+        `workspace repository ${alias} is not inside a git repository: ${path}`,
+      );
+    const real = realpathSync(top);
+    if (Object.values(canonical).includes(real))
+      throw invalid(`workspace repository ${alias} duplicates a canonical git root`);
+    canonical[alias] = real;
+  }
+  return { root, repos: canonical };
+}
+
+export async function startWorkspace(
+  deps: Deps,
+  input: {
+    root: string;
+    title: string;
+    aLines: string[];
+    repos?: Record<string, string>;
+    steps: Array<{
+      id: string;
+      repo: string;
+      title: string;
+      aLines: string[];
+      dependsOn?: string[];
+      milestone?: string;
+      release?: "land" | "merge";
+      base?: string;
+    }>;
+    budget?: Budget;
+  },
+): Promise<{ workspace: Workspace; dir: string }> {
+  const root = workspaceRoot(input.root);
+  const declared = registry(root, input.repos);
+  // Only selected repositories are captured. An unused unavailable checkout cannot block this task.
+  const selected: Record<string, string> = {};
+  for (const step of input.steps) {
+    if (!Object.hasOwn(declared, step.repo)) throw invalid(`unknown workspace repository ${step.repo}`);
+    selected[step.repo] = declared[step.repo]!;
+  }
+  const snapshot = WorkspaceSchema.safeParse({
+    schema: 1,
+    id: "validation",
+    root,
+    title: input.title,
+    aLines: input.aLines,
+    createdAt: new Date(deps.now()).toISOString(),
+    repos: selected,
+    steps: input.steps,
+    // #43 finding 4: no cap unless the owner sets one; each child keeps its own profile budget
+    budget: input.budget ?? {},
+  });
+  if (!snapshot.success)
+    throw invalid(
+      `workspace requires unique step ids, ordered repository reuse, valid budget, and an acyclic dependency graph: ${snapshot.error.issues[0]?.message ?? "invalid"}`,
+    );
+  const canonical = await inspectWorkspace(root, selected);
+  const workspace = createWorkspace({ ...snapshot.data, repos: canonical.repos }, new Date(deps.now()));
+  return { workspace, dir: workspaceDirectory(workspace.id) };
+}
+
+/** Whether a child still has dispatches nobody collected; null when its records cannot be read. */
+function ownPending(run: Run): boolean | null {
+  const { records, corrupt } = readRecords(run);
+  if (corrupt) return null;
+  const recorded = new Set(records.map((r) => r.dispatchId));
+  try {
+    return listDispatches(run, true).some((d) => !recorded.has(d.admit.dispatchId));
+  } catch {
+    return null;
+  }
+}
+
+export async function startWorkspaceChild(
+  deps: Deps,
+  input: { workspace: string; step: string },
+): Promise<{ run: string; dir: string; contract: string | null }> {
+  const workspace = findWorkspace(input.workspace);
+  const paths = workspacePaths(workspaceDirectory(workspace.id));
+  const step = workspace.steps.find((s) => s.id === input.step);
+  if (!step) throw invalid(`unknown workspace step ${input.step}`);
+  // Recovery must validate the checkout too; stored status remains readable without it. The git work runs
+  // outside the workspace lock (#43 finding 5).
+  const repo = workspace.repos[step.repo]!;
+  if ((await gitToplevel(repo)) !== repo)
+    throw new CatherdError(
+      "E_IO_PATH",
+      `workspace repository ${step.repo} is no longer the captured git root`,
+    );
+  const run = await withFileLock(
+    paths.admission,
+    () => childFor(deps, workspace, step, repo, paths.contract),
+    { timeoutMs: WORKSPACE_LOCK_WAIT_MS },
+  );
+  const contract = existsSync(paths.contract) ? join(run.dir, "workspace-contract.md") : null;
+  await claimRun(deps, run);
+  await refreshState(run);
+  return { run: run.id, dir: run.dir, contract };
+}
+
+/** Under the workspace lock: the step's child, created once its dependencies release it. */
+async function childFor(
+  deps: Deps,
+  workspace: Workspace,
+  step: Workspace["steps"][number],
+  repo: string,
+  contractFile: string,
+): Promise<Run> {
+  const children = workspaceChildren(workspace);
+  let run = children.find((r) => r.meta.workspace?.step === step.id);
+  if (!run) {
+    assertNotPaused({ meta: { workspace: { id: workspace.id, step: step.id } } });
+    const blockers = await dependencyBlockers(workspace, step, children, deps.now(), { merge: true });
+    if (blockers.length)
+      throw invalid(`workspace step ${step.id} waits: ${blockers.map((b) => b.why).join("; ")}`);
+    await assertWorkspaceBudget(workspace, deps.now(), children);
+    run = createRun({
+      repo,
+      title: step.title,
+      aLines: step.aLines,
+      version: deps.version,
+      now: new Date(deps.now()),
+      startedBy: currentSession(deps),
+      workspace: { id: workspace.id, step: step.id },
+    });
+    writePin(deps, run);
+    // pinned like startRun does, so a pair the machine index drops later never breaks the child midway
+    writeRunIndex(run.dir, readIndexFile(indexPath()));
+  }
+  const contract = existsSync(contractFile) ? join(run.dir, "workspace-contract.md") : null;
+  if (contract && !existsSync(contract)) writeTextAtomic(contract, readFileSync(contractFile, "utf8"));
+  return run;
+}
+
+export async function workspaceStatus(deps: Deps, id: string) {
+  const workspace = findWorkspace(id);
+  const { children, unreadable } = workspaceListing(workspace);
+  // #43 finding 2: a corrupt child is a warning here, never a failed status
+  const warnings = unreadable.map(unreadableWarning);
+  const steps = [];
+  for (const step of workspace.steps) {
+    const child = children.find((r) => r.meta.workspace?.step === step.id);
+    const summary = child ? summarizeRun(deps, child) : null;
+    const landed = child ? landedMilestones(child) : [];
+    const pending = child ? ownPending(child) : false;
+    if (child && pending === null)
+      warnings.push(`${step.id}: run ${child.id} has unreadable dispatch records`);
+    // #43 finding 7: a milestone that differs only by case never releases the dependents
+    const twin = landed.find((m) => m !== step.milestone && m.toLowerCase() === step.milestone.toLowerCase());
+    if (twin && !landed.includes(step.milestone))
+      warnings.push(`${step.id} completes on ${step.milestone}, but its run landed ${twin}`);
+    const blockers = await dependencyBlockers(workspace, step, children, deps.now(), { merge: true });
+    const state: "waiting" | "ready" | "active" | "landed" = child
+      ? landed.includes(step.milestone) && pending === false
+        ? "landed"
+        : "active"
+      : blockers.length
+        ? "waiting"
+        : "ready";
+    steps.push({
+      id: step.id,
+      repo: step.repo,
+      state,
+      run: child?.id ?? null,
+      blockedBy: blockers.map((b) => b.step),
+      waitingFor: blockers.map((b) => b.why),
+      landedMilestones: landed,
+      landedCommits: child ? landedCommits(child) : [],
+      failures: summary?.totals.notOk ?? [],
+      questions: summary?.questions ?? [],
+      live: summary?.live ?? [],
+      childBudget: summary?.budget ?? null,
+      warnings: summary?.warnings ?? [],
+    });
+  }
+  const spend = await workspaceSpend(workspace, deps.now(), children, warnings);
+  return {
+    // spec 1.5 "Group pause": a pause over the workspace comes first
+    paused: pausesOver([{ meta: { workspace: { id, step: workspace.steps[0]!.id } } }]),
+    workspace,
+    dir: workspaceDirectory(id),
+    steps,
+    spend,
+    budget: budgetStatus(spend, workspace.budget),
+    warnings,
+  };
+}