@app-vitals/agent-runtime 0.0.1 → 0.1.1

package/process-tree-kill.ts

@@ -0,0 +1,325 @@
+/**
+ * Process-tree termination for the spawned `claude` CLI.
+ *
+ * Why this exists: `Subprocess.kill()` signals exactly one process — the
+ * direct child. A Claude Code session routinely forks its own children
+ * (installs, builds, test runs, dev servers). When the agent's timeout /
+ * abort path signalled only the CLI, those grandchildren were reparented to
+ * init and kept running — burning CPU, holding ports and lockfiles, and
+ * occasionally outliving the agent process itself.
+ *
+ * Two strategies, chosen at runtime:
+ *
+ *  1. **cgroup v2 (preferred).** Each invocation gets its own cgroup
+ *     directory; `Bun.spawn`'s `cgroup` option puts the CLI inside it before
+ *     its first instruction, so everything it forks is a member too. Writing
+ *     `1` to the cgroup's `cgroup.kill` then SIGKILLs the entire membership
+ *     atomically, with no PID-reuse or reparenting races.
+ *
+ *  2. **procfs walk (fallback).** Container runtimes commonly mount
+ *     /sys/fs/cgroup read-only with no delegation — that is the case in this
+ *     project's own agent image (`oven/bun:1-slim` under a Kubernetes
+ *     securityContext with no privileged/cgroup-namespace grant: `mount`
+ *     reports `cgroup2 (ro,…)` and `mkdir` under it fails with EROFS). So
+ *     cgroup mode can never be assumed. When it is unavailable we snapshot
+ *     the descendant pids from `/proc/<pid>/task/<tid>/children` *before*
+ *     signalling the root (once the root dies, those parent→child links are
+ *     gone) and SIGKILL them individually. Known limitation, accepted: a
+ *     process that deliberately double-forks to detach *before* the kill has
+ *     already been reparented to init, so it no longer appears anywhere in
+ *     the tree and survives. Only cgroup membership catches that case; the
+ *     CLI's own children (installs, builds, test runs) do not double-fork.
+ *
+ * The choice is made by probing at runtime and caching the answer, rather
+ * than by a deploy-time flag — a container that does delegate cgroups gets
+ * the stronger guarantee for free, and one that doesn't degrades silently to
+ * the fallback. `scripts/verify-cgroup-delegation.ts` prints the
+ * resolved mode from inside the real built image on every CI build.
+ *
+ * Every entry point here is best-effort and never throws: a failure to clean
+ * up a child process must not take down the agent process that was trying to
+ * clean it up.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+/** Where the cgroup v2 unified hierarchy is mounted on Linux. */
+export const CGROUP_MOUNT_ROOT = "/sys/fs/cgroup";
+
+interface CgroupSupport {
+  usable: boolean;
+  /** The delegated directory new run-cgroups are created under. */
+  base?: string;
+  /** Human-readable explanation, surfaced by the CI verify script. */
+  reason: string;
+}
+
+interface KillableProcess {
+  readonly pid?: number;
+  kill: (signal?: number | NodeJS.Signals) => void;
+}
+
+/**
+ * The cgroup directory this process itself lives in, per the unified
+ * hierarchy line of /proc/self/cgroup (`0::<path>`). Run-cgroups are created
+ * as CHILDREN of it rather than at the mount root: that is the shape cgroup
+ * delegation actually grants (a container is handed its own subtree, not the
+ * whole hierarchy), so it's the only location that can work unprivileged.
+ */
+export function resolveCgroupBase(
+  mountRoot: string = CGROUP_MOUNT_ROOT,
+  procSelfCgroupPath = "/proc/self/cgroup",
+): string | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(procSelfCgroupPath, "utf8");
+  } catch {
+    return undefined;
+  }
+  const line = raw.split("\n").find((l) => l.startsWith("0::"));
+  // No `0::` line means a cgroup v1-only host — there is no cgroup.kill
+  // interface there, so the procfs fallback is the only option.
+  if (!line) return undefined;
+  const rel = line.slice(3).trim();
+  return rel === "" || rel === "/" ? mountRoot : join(mountRoot, rel);
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Probe, for real, whether we can create child cgroups. Creates a throwaway
+ * directory and removes it again — the only way to tell a delegated subtree
+ * from a read-only mount without guessing at securityContext.
+ */
+export function probeCgroupDelegation(base?: string): CgroupSupport {
+  if (process.platform !== "linux") {
+    return { usable: false, reason: `not linux (${process.platform})` };
+  }
+  const resolved = base ?? resolveCgroupBase();
+  if (!resolved) {
+    return {
+      usable: false,
+      reason: "no cgroup v2 unified hierarchy in /proc/self/cgroup",
+    };
+  }
+  // A directory without cgroup.procs isn't a cgroup at all (e.g. the mount is
+  // missing entirely, or points at a plain directory) — creating run dirs
+  // there would silently do nothing useful.
+  if (!existsSync(join(resolved, "cgroup.procs"))) {
+    return {
+      usable: false,
+      reason: `${resolved} is not a cgroup v2 directory (no cgroup.procs)`,
+    };
+  }
+  const probeDir = join(
+    resolved,
+    `shipwright-probe-${process.pid}-${Date.now()}`,
+  );
+  try {
+    mkdirSync(probeDir);
+  } catch (err) {
+    return {
+      usable: false,
+      reason: `cgroup delegation not writable at ${resolved}: ${describe(err)}`,
+    };
+  }
+  try {
+    rmdirSync(probeDir);
+  } catch {
+    // Leaving the probe dir behind is harmless; delegation clearly works.
+  }
+  return {
+    usable: true,
+    base: resolved,
+    reason: `cgroup v2 delegation writable at ${resolved}`,
+  };
+}
+
+let cachedSupport: CgroupSupport | undefined;
+let runCounter = 0;
+
+/** Probe once per process, then reuse the answer. */
+function cgroupSupport(base?: string): CgroupSupport {
+  cachedSupport ??= probeCgroupDelegation(base);
+  return cachedSupport;
+}
+
+/** Test seam, and the reset used after a transient probe failure. */
+export function resetCgroupSupportCache(): void {
+  cachedSupport = undefined;
+}
+
+/**
+ * Latch cgroup mode off for the rest of this process. Called when creating or
+ * joining a cgroup fails at runtime (delegation revoked, hierarchy moved), so
+ * later invocations go straight to the procfs fallback instead of retrying a
+ * syscall we already know fails.
+ */
+export function markCgroupUnavailable(reason: string): void {
+  cachedSupport = { usable: false, reason };
+}
+
+/**
+ * Create a dedicated cgroup for one invocation, or return undefined if this
+ * container doesn't delegate cgroups (the common case) — in which case the
+ * caller spawns normally and `killTree` uses the procfs fallback.
+ */
+export function createRunCgroup(base?: string): string | undefined {
+  const support = cgroupSupport(base);
+  if (!support.usable || !support.base) return undefined;
+  runCounter += 1;
+  const dir = join(
+    support.base,
+    `shipwright-run-${process.pid}-${runCounter}-${Date.now()}`,
+  );
+  try {
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  } catch (err) {
+    markCgroupUnavailable(
+      `run cgroup creation failed under ${support.base}: ${describe(err)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * SIGKILL every process in the cgroup, atomically. Returns false (never
+ * throws) when the write fails — the cgroup was already removed, the kernel
+ * is too old for cgroup.kill (< 5.14), or delegation went away — so callers
+ * can fall through to the per-process path.
+ */
+export function killCgroup(path: string): boolean {
+  try {
+    writeFileSync(join(path, "cgroup.kill"), "1");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Best-effort cleanup of a run cgroup once its process has exited. rmdir
+ * fails with EBUSY while members remain, so a failure is retried once after
+ * killing whatever is still inside — that leftover membership IS the process
+ * leak this module exists to prevent.
+ */
+export function removeRunCgroup(path: string): void {
+  try {
+    rmdirSync(path);
+    return;
+  } catch {
+    // Fall through to the kill-then-retry below.
+  }
+  killCgroup(path);
+  try {
+    rmdirSync(path);
+  } catch {
+    // Give up silently: an orphan cgroup directory is inert, and throwing
+    // from a cleanup path would surface as an unhandled rejection.
+  }
+}
+
+function readChildPids(pid: number, procRoot: string): number[] {
+  // Children are tracked per-THREAD, not per-process: a multi-threaded parent
+  // records each fork under the thread that made it, so every tid under
+  // /proc/<pid>/task must be read, not just the main one.
+  const taskDir = join(procRoot, String(pid), "task");
+  let tids: string[];
+  try {
+    tids = readdirSync(taskDir);
+  } catch {
+    return [];
+  }
+  const children: number[] = [];
+  for (const tid of tids) {
+    let raw: string;
+    try {
+      raw = readFileSync(join(taskDir, tid, "children"), "utf8");
+    } catch {
+      continue; // thread exited mid-walk
+    }
+    for (const token of raw.split(/\s+/)) {
+      const parsed = Number.parseInt(token, 10);
+      if (Number.isInteger(parsed) && parsed > 0) children.push(parsed);
+    }
+  }
+  return children;
+}
+
+/**
+ * Every transitive descendant of `pid`, breadth-first. A `seen` set guards
+ * against the (pathological, but cheap to rule out) case of a cycle from a
+ * recycled pid appearing in its own ancestor's children list.
+ */
+export function collectDescendantPids(
+  pid: number,
+  procRoot = "/proc",
+): number[] {
+  const descendants: number[] = [];
+  const seen = new Set<number>([pid]);
+  const queue: number[] = [pid];
+  while (queue.length > 0) {
+    const current = queue.shift() as number;
+    for (const child of readChildPids(current, procRoot)) {
+      if (seen.has(child)) continue;
+      seen.add(child);
+      descendants.push(child);
+      queue.push(child);
+    }
+  }
+  return descendants;
+}
+
+/**
+ * Terminate a spawned process and everything it spawned.
+ *
+ * Replaces a bare `proc.kill()` at every timeout/abort call site. Never
+ * throws: a process that already exited, a vanished cgroup, and a
+ * non-Linux/procfs-less host are all normal outcomes here.
+ */
+export function killTree(proc: KillableProcess, cgroupPath?: string): void {
+  try {
+    // cgroup.kill covers the CLI itself as well as its descendants, so an
+    // additional signal to the direct child would be redundant.
+    if (cgroupPath && killCgroup(cgroupPath)) return;
+
+    const pid =
+      typeof proc.pid === "number" && proc.pid > 0 ? proc.pid : undefined;
+    // Snapshot BEFORE signalling the root: the moment it exits, /proc/<pid>
+    // disappears and its children are reparented to init, erasing the only
+    // link back to them.
+    const descendants = pid ? collectDescendantPids(pid) : [];
+
+    try {
+      // Root gets the caller's default signal (SIGTERM) so the CLI can still
+      // flush and exit 143, preserving the existing timeout/abort semantics.
+      proc.kill();
+    } catch {
+      // Already exited — the descendants below are what matter now.
+    }
+
+    for (const descendant of descendants) {
+      try {
+        // SIGKILL, not SIGTERM: these are arbitrary orphaned build/install
+        // processes with no cleanup contract worth waiting on.
+        process.kill(descendant, "SIGKILL");
+      } catch {
+        // Already gone, or not ours to signal.
+      }
+    }
+  } catch {
+    // Defense in depth: nothing in a kill path may escape as an unhandled
+    // rejection and take down the agent.
+  }
+}

package/process-tree-kill.unit.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Tests for agent/src/runtime/process-tree-kill.ts
+ *
+ * Strategy: every function takes the cgroup base / procfs root as an injected
+ * parameter, so the probe/create/kill/cleanup logic is exercised against a
+ * real temp directory that mimics a cgroup v2 hierarchy (a directory holding
+ * a `cgroup.procs` control file) instead of the real, usually read-only
+ * /sys/fs/cgroup. No mock.module(), no global overrides.
+ *
+ * Real-subprocess behavior (descendant discovery + tree kill) lives in
+ * process-tree-kill.integration.test.ts.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const {
+  collectDescendantPids,
+  createRunCgroup,
+  killCgroup,
+  killTree,
+  markCgroupUnavailable,
+  probeCgroupDelegation,
+  removeRunCgroup,
+  resetCgroupSupportCache,
+  resolveCgroupBase,
+} = await import("./process-tree-kill.ts");
+
+const tempDirs: string[] = [];
+
+/** A temp dir shaped like a delegated cgroup v2 directory. */
+function fakeCgroupBase(): string {
+  const dir = mkdtempSync(join(tmpdir(), "shipwright-cgroup-test-"));
+  tempDirs.push(dir);
+  writeFileSync(join(dir, "cgroup.procs"), "");
+  return dir;
+}
+
+/** A temp dir that is NOT a cgroup hierarchy (no control files). */
+function plainTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "shipwright-plain-test-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  resetCgroupSupportCache();
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("resolveCgroupBase", () => {
+  test("maps the unified-hierarchy line of /proc/self/cgroup onto the mount root", () => {
+    const dir = plainTempDir();
+    const procSelfCgroup = join(dir, "cgroup");
+    writeFileSync(procSelfCgroup, "0::/kubepods/pod123/container456\n");
+    expect(resolveCgroupBase("/sys/fs/cgroup", procSelfCgroup)).toBe(
+      "/sys/fs/cgroup/kubepods/pod123/container456",
+    );
+  });
+
+  test("returns the mount root itself when the process sits at the hierarchy root", () => {
+    const dir = plainTempDir();
+    const procSelfCgroup = join(dir, "cgroup");
+    writeFileSync(procSelfCgroup, "0::/\n");
+    expect(resolveCgroupBase("/sys/fs/cgroup", procSelfCgroup)).toBe(
+      "/sys/fs/cgroup",
+    );
+  });
+
+  test("returns undefined on a v1-only host (no 0:: unified line)", () => {
+    const dir = plainTempDir();
+    const procSelfCgroup = join(dir, "cgroup");
+    writeFileSync(procSelfCgroup, "2:cpu:/foo\n1:name=systemd:/bar\n");
+    expect(resolveCgroupBase("/sys/fs/cgroup", procSelfCgroup)).toBeUndefined();
+  });
+
+  test("returns undefined when /proc/self/cgroup is unreadable", () => {
+    expect(
+      resolveCgroupBase("/sys/fs/cgroup", "/nonexistent/proc/self/cgroup"),
+    ).toBeUndefined();
+  });
+});
+
+describe("probeCgroupDelegation", () => {
+  test("reports usable and leaves no probe directory behind when the base is a writable cgroup dir", () => {
+    const base = fakeCgroupBase();
+    const support = probeCgroupDelegation(base);
+    expect(support.usable).toBe(true);
+    expect(support.base).toBe(base);
+    // Probe directory must be cleaned up — a leaked probe cgroup per boot
+    // would accumulate in the delegated hierarchy.
+    expect(readdirSync(base)).toEqual(["cgroup.procs"]);
+  });
+
+  test("reports unusable when the base is not a cgroup v2 hierarchy", () => {
+    const support = probeCgroupDelegation(plainTempDir());
+    expect(support.usable).toBe(false);
+    expect(support.reason).toContain("cgroup");
+  });
+
+  test("reports unusable when the base directory does not exist", () => {
+    const support = probeCgroupDelegation("/nonexistent/sys/fs/cgroup");
+    expect(support.usable).toBe(false);
+  });
+
+  test("reports unusable when the base is read-only (mirrors the deployed container)", () => {
+    // Directory permissions do not restrain uid 0, so this assertion is only
+    // meaningful as a non-root user (which is how both CI and the deployed
+    // pod run).
+    if (process.getuid?.() === 0) return;
+    const base = fakeCgroupBase();
+    // 0o500 = r-x------: the cgroup.procs check still passes, but mkdir of a
+    // child cgroup fails with EACCES — exactly the read-only-cgroupfs shape
+    // seen in the deployed agent pod.
+    chmodSync(base, 0o500);
+    const support = probeCgroupDelegation(base);
+    chmodSync(base, 0o700);
+    expect(support.usable).toBe(false);
+  });
+});
+
+describe("createRunCgroup / removeRunCgroup", () => {
+  test("creates a fresh, unique directory under the delegated base", () => {
+    const base = fakeCgroupBase();
+    const a = createRunCgroup(base);
+    const b = createRunCgroup(base);
+    expect(a).toBeDefined();
+    expect(b).toBeDefined();
+    expect(a).not.toBe(b);
+    expect(existsSync(a as string)).toBe(true);
+    expect(existsSync(b as string)).toBe(true);
+  });
+
+  test("returns undefined (no throw) when delegation is unavailable", () => {
+    expect(createRunCgroup(plainTempDir())).toBeUndefined();
+  });
+
+  test("caches the probe result so an unusable base is probed only once", () => {
+    const base = fakeCgroupBase();
+    expect(createRunCgroup(base)).toBeDefined();
+    markCgroupUnavailable("forced for test");
+    // Cached negative result short-circuits without touching the filesystem.
+    expect(createRunCgroup(base)).toBeUndefined();
+    resetCgroupSupportCache();
+    expect(createRunCgroup(base)).toBeDefined();
+  });
+
+  test("removeRunCgroup deletes the directory and never throws when it is already gone", () => {
+    const base = fakeCgroupBase();
+    const dir = createRunCgroup(base) as string;
+    removeRunCgroup(dir);
+    expect(existsSync(dir)).toBe(false);
+    expect(() => removeRunCgroup(dir)).not.toThrow();
+    expect(() => removeRunCgroup("/nonexistent/cgroup/dir")).not.toThrow();
+  });
+});
+
+describe("killCgroup", () => {
+  test("writes 1 to the cgroup.kill interface file", () => {
+    const base = fakeCgroupBase();
+    const dir = createRunCgroup(base) as string;
+    expect(killCgroup(dir)).toBe(true);
+    expect(readFileSync(join(dir, "cgroup.kill"), "utf8")).toBe("1");
+  });
+
+  test("returns false instead of throwing when the cgroup is gone", () => {
+    expect(killCgroup("/nonexistent/cgroup/dir")).toBe(false);
+  });
+});
+
+describe("collectDescendantPids", () => {
+  test("walks /proc/<pid>/task/<tid>/children transitively", () => {
+    const procRoot = plainTempDir();
+    // 100 → 200, 201 (via two threads); 200 → 300
+    const link = (pid: number, tid: number, children: string) => {
+      mkdirSync(join(procRoot, String(pid), "task", String(tid)), {
+        recursive: true,
+      });
+      writeFileSync(
+        join(procRoot, String(pid), "task", String(tid), "children"),
+        children,
+      );
+    };
+    link(100, 100, "200 ");
+    link(100, 111, "201 ");
+    link(200, 200, "300 ");
+    link(201, 201, "");
+    link(300, 300, "");
+
+    expect(collectDescendantPids(100, procRoot).sort()).toEqual([
+      200, 201, 300,
+    ]);
+  });
+
+  test("returns an empty list for an unknown pid instead of throwing", () => {
+    expect(collectDescendantPids(999999, plainTempDir())).toEqual([]);
+  });
+
+  test("does not loop forever on a self-referential children file", () => {
+    const procRoot = plainTempDir();
+    mkdirSync(join(procRoot, "7", "task", "7"), { recursive: true });
+    writeFileSync(join(procRoot, "7", "task", "7", "children"), "7 8");
+    mkdirSync(join(procRoot, "8", "task", "8"), { recursive: true });
+    writeFileSync(join(procRoot, "8", "task", "8", "children"), "7");
+    expect(collectDescendantPids(7, procRoot).sort()).toEqual([8]);
+  });
+});
+
+describe("killTree", () => {
+  test("kills the whole cgroup and skips the per-process path when a cgroup is in use", () => {
+    const base = fakeCgroupBase();
+    const dir = createRunCgroup(base) as string;
+    let directKills = 0;
+    killTree({ pid: 999999, kill: () => directKills++ }, dir);
+    expect(readFileSync(join(dir, "cgroup.kill"), "utf8")).toBe("1");
+    // cgroup.kill SIGKILLs every member, the CLI included — no extra signal.
+    expect(directKills).toBe(0);
+  });
+
+  test("falls back to the direct kill when the cgroup write fails", () => {
+    let directKills = 0;
+    killTree(
+      { pid: 999999, kill: () => directKills++ },
+      "/nonexistent/cgroup/dir",
+    );
+    expect(directKills).toBe(1);
+  });
+
+  test("kills the process directly when no cgroup is in use", () => {
+    let directKills = 0;
+    killTree({ pid: 999999, kill: () => directKills++ });
+    expect(directKills).toBe(1);
+  });
+
+  test("tolerates a proc with no pid (fully synthetic/fake proc)", () => {
+    let directKills = 0;
+    expect(() => killTree({ kill: () => directKills++ })).not.toThrow();
+    expect(directKills).toBe(1);
+  });
+
+  test("never throws when the underlying kill throws (process already exited)", () => {
+    expect(() =>
+      killTree({
+        pid: 999999,
+        kill: () => {
+          throw new Error("ESRCH");
+        },
+      }),
+    ).not.toThrow();
+  });
+});

package/progress-milestones.ts

@@ -0,0 +1,86 @@
+/**
+ * agent/src/runtime/progress-milestones.ts
+ * Maps a single `content` block from an `assistant` `stream-json` message to
+ * a generic `ProgressPhase` (see `@app-vitals/agent-lib/progress-phases`).
+ *
+ * LOAD-BEARING INVARIANT: `block.input` is never read here — not logged, not
+ * inspected, not passed to any function. Tool inputs can carry absolute
+ * filesystem paths, secrets, command lines, or URLs; none of that may ever
+ * leave the agent process via this code path. Phase is derived from
+ * `block.type` and `block.name` (the tool name) ONLY. Do not add any code
+ * here that touches `block.input`.
+ */
+
+import type { ProgressPhase } from "@app-vitals/agent-lib/progress-phases";
+
+/**
+ * The shape of one entry in an `assistant` message's `content` array, as
+ * emitted by `claude -p --output-format stream-json --verbose`. `input` is
+ * intentionally typed as `unknown` and MUST NOT be read by this module — see
+ * the file-level invariant above.
+ */
+export interface ContentBlock {
+  type: string;
+  name?: string;
+  input?: unknown;
+  /** Other block-type-specific fields (e.g. `thinking`, `text`) — never read. */
+  [key: string]: unknown;
+}
+
+/** Tool names (exact match) mapped to their progress phase. */
+const TOOL_PHASE_MAP: Record<string, ProgressPhase> = {
+  // Reading: pulling in a known file's full contents.
+  Read: "reading",
+  NotebookRead: "reading",
+  // Searching: looking for something across the codebase by pattern/name,
+  // distinct from "reading" a specific known file.
+  Grep: "searching",
+  Glob: "searching",
+  // Web: leaving the local filesystem/codebase entirely.
+  WebSearch: "web",
+  WebFetch: "web",
+  // Editing: mutating files.
+  Edit: "editing",
+  Write: "editing",
+  NotebookEdit: "editing",
+  // Running: shell/process execution.
+  Bash: "running",
+  KillShell: "running",
+  BashOutput: "running",
+  // Delegating: dispatching work to a subagent.
+  Agent: "delegating",
+  Task: "delegating",
+  // Planning: todo/plan-mode bookkeeping tools.
+  TodoWrite: "planning",
+  ExitPlanMode: "planning",
+  EnterPlanMode: "planning",
+};
+
+/**
+ * Generic fallback phase for any tool_use block whose name isn't recognized —
+ * covers both `mcp__*`-prefixed MCP tools and any other unmapped tool name.
+ */
+const GENERIC_TOOL_PHASE: ProgressPhase = "tool";
+
+/**
+ * Resolve the ProgressPhase for a single `assistant` content block. Returns
+ * `undefined` for block types this module doesn't map (e.g. `tool_result`,
+ * which only ever appears in `user` messages and is out of scope here).
+ *
+ * Never throws and never returns `undefined` for a `tool_use` block,
+ * regardless of tool name — new tools are added over time, so an unrecognized
+ * name always falls back to the generic `"tool"` phase rather than being
+ * dropped.
+ */
+export function phaseForBlock(block: ContentBlock): ProgressPhase | undefined {
+  switch (block.type) {
+    case "thinking":
+      return "thinking";
+    case "text":
+      return "writing";
+    case "tool_use":
+      return TOOL_PHASE_MAP[block.name ?? ""] ?? GENERIC_TOOL_PHASE;
+    default:
+      return undefined;
+  }
+}