catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/domain/util.ts

@@ -16,6 +16,28 @@ export function median(xs: readonly number[]): number | null {
   return s.length % 2 ? (s[m] as number) : ((s[m - 1] as number) + (s[m] as number)) / 2;
 }
 
+/** A stretch of time in epoch ms; `to` null while it is still open. */
+export interface Span {
+  from: number;
+  to: number | null;
+}
+
+/** How many ms of [from, to] any of `spans` covers, overlaps counted once; an open span runs to `to`. */
+export function coveredMs(from: number, to: number, spans: readonly Span[]): number {
+  const clipped = spans
+    .map((s) => [Math.max(from, s.from), Math.min(to, s.to ?? to)] as const)
+    .filter(([a, b]) => b > a)
+    .sort((x, y) => x[0] - y[0]);
+  let total = 0;
+  let end = -Infinity;
+  for (const [a, b] of clipped) {
+    if (b <= end) continue;
+    total += b - Math.max(a, end);
+    end = b;
+  }
+  return total;
+}
+
 /** A plain object: not null and not an array. */
 export const isPlain = (v: unknown): v is Record<string, unknown> =>
   typeof v === "object" && v !== null && !Array.isArray(v);

package/src/domain/workspace.ts

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { ID_PATTERN } from "./ids.ts";
+
+export const WORKSPACE_LIMIT = 100;
+
+export const WorkspaceIdSchema = z
+  .string()
+  .regex(ID_PATTERN)
+  .refine((s) => !s.includes(".."));
+export const WorkspaceBudgetSchema = z.strictObject({
+  minutes: z.number().finite().nonnegative().optional(),
+  tokens: z.number().finite().nonnegative().optional(),
+  usd: z.number().finite().nonnegative().optional(),
+});
+/** A git ref a release waits on (`origin/main`): no option, no range, no whitespace. */
+export const BaseRefSchema = z
+  .string()
+  .regex(/^[A-Za-z0-9_][A-Za-z0-9._/-]*$/)
+  .refine((s) => !s.includes("..") && !s.endsWith("/") && !s.endsWith(".lock"));
+export const RELEASES = ["land", "merge"] as const;
+export const WorkspaceStepSchema = z
+  .strictObject({
+    id: WorkspaceIdSchema,
+    repo: WorkspaceIdSchema,
+    title: z.string().min(1),
+    aLines: z.array(z.string()),
+    dependsOn: z.array(WorkspaceIdSchema).max(WORKSPACE_LIMIT).default([]),
+    milestone: WorkspaceIdSchema.default("M1"),
+    /**
+     * When the step releases its dependents: once its milestone lands (the default), or once the landed
+     * commit is an ancestor of `base` in its repository (`git merge-base --is-ancestor`), checked when a
+     * dependent asks, never polled.
+     */
+    release: z.enum(RELEASES).default("land"),
+    base: BaseRefSchema.optional(),
+  })
+  .refine((s) => (s.release === "merge") === (s.base !== undefined), {
+    message: 'release "merge" needs a base ref (e.g. origin/main), and only it takes one',
+  });
+export type WorkspaceStep = z.infer<typeof WorkspaceStepSchema>;
+export const WorkspaceSchema = z
+  .strictObject({
+    schema: z.literal(1),
+    id: WorkspaceIdSchema,
+    root: z.string().min(1),
+    title: z.string().min(1),
+    aLines: z.array(z.string()),
+    createdAt: z.iso.datetime(),
+    budget: WorkspaceBudgetSchema,
+    repos: z
+      .record(WorkspaceIdSchema, z.string().min(1))
+      .refine((repos) => Object.keys(repos).length <= WORKSPACE_LIMIT),
+    steps: z.array(WorkspaceStepSchema).min(1).max(WORKSPACE_LIMIT),
+  })
+  .superRefine((workspace, ctx) => {
+    // Zod may still refine an oversized array; do not traverse invalid graphs.
+    if (
+      workspace.steps.length > WORKSPACE_LIMIT ||
+      Object.keys(workspace.repos).length > WORKSPACE_LIMIT ||
+      workspace.steps.some((step) => step.dependsOn.length > WORKSPACE_LIMIT)
+    )
+      return;
+    const ids = new Set<string>();
+    let invalidIdentity = false;
+    for (const step of workspace.steps) {
+      if (ids.has(step.id) || !Object.hasOwn(workspace.repos, step.repo)) {
+        invalidIdentity = true;
+        ctx.addIssue({
+          code: "custom",
+          message: "steps require unique ids and repositories present in the snapshot",
+        });
+      }
+      ids.add(step.id);
+    }
+    if (invalidIdentity) return;
+    const byId = new Map(workspace.steps.map((step) => [step.id, step]));
+    const remaining = new Map<string, number>();
+    const dependents = new Map<string, string[]>();
+    const ready: string[] = [];
+    for (const step of workspace.steps) {
+      if (
+        new Set(step.dependsOn).size !== step.dependsOn.length ||
+        step.dependsOn.some((id) => !byId.has(id))
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          message: "dependencies must form a graph without cycles or unknown steps",
+        });
+        return;
+      }
+      remaining.set(step.id, step.dependsOn.length);
+      if (!step.dependsOn.length) ready.push(step.id);
+      for (const id of step.dependsOn) {
+        const next = dependents.get(id) ?? [];
+        next.push(step.id);
+        dependents.set(id, next);
+      }
+    }
+    const ancestors = new Map<string, Set<string>>();
+    const latestByRepo = new Map<string, string>();
+    // Topological order makes adjacent owners sufficient: if each owner follows
+    // the previous owner transitively, every pair of owners is ordered.
+    for (let i = 0; i < ready.length; i++) {
+      const step = byId.get(ready[i]!)!;
+      const before = new Set<string>();
+      for (const id of step.dependsOn) {
+        before.add(id);
+        for (const ancestor of ancestors.get(id)!) before.add(ancestor);
+      }
+      ancestors.set(step.id, before);
+      const previous = latestByRepo.get(step.repo);
+      if (previous && !before.has(previous))
+        ctx.addIssue({
+          code: "custom",
+          message: "steps sharing a repository must be ordered by dependencies",
+        });
+      latestByRepo.set(step.repo, step.id);
+      for (const id of dependents.get(step.id) ?? []) {
+        const count = remaining.get(id)! - 1;
+        remaining.set(id, count);
+        if (!count) ready.push(id);
+      }
+    }
+    if (ready.length !== workspace.steps.length)
+      ctx.addIssue({
+        code: "custom",
+        message: "dependencies must form a graph without cycles or unknown steps",
+      });
+  });
+export type Workspace = z.infer<typeof WorkspaceSchema>;

package/src/entry/answer-command.ts

@@ -0,0 +1,39 @@
+import { defineCommand } from "citty";
+import { CatherdError } from "../domain/errors.ts";
+import { answerUnit } from "../services/run-client.ts";
+import { defaultDeps } from "./deps.ts";
+import { JSON_ARG, printJson, refuseInRole } from "./cli-kit.ts";
+
+/** What the phone message names: the run, the unit and the answer, as one command. */
+export const answerCommand = defineCommand({
+  meta: {
+    name: "answer",
+    description: "Answer a parked unit of a run: it runs again with your answer",
+  },
+  args: {
+    run: { type: "positional", required: true, description: "the run id" },
+    unit: {
+      type: "positional",
+      required: true,
+      description: "the parked unit: the run, a milestone or a lane",
+    },
+    answer: {
+      type: "positional",
+      required: false,
+      description: "your answer (several words need no quotes)",
+    },
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd answer");
+    // citty names the first words; the rest of the line is the answer's too
+    const answer = (args._ as string[]).slice(2).join(" ").trim();
+    if (!answer)
+      throw new CatherdError("E_INPUT_INVALID", "no answer given", {
+        fix: 'catherd answer <run> <unit> "<your answer>"',
+      });
+    const r = await answerUnit(defaultDeps(), { run: args.run, unit: args.unit, answer });
+    if (args.json) return printJson(r);
+    console.log(`answered ${r.unit}${r.parked.length ? `; still waiting: ${r.parked.join(", ")}` : ""}`);
+  },
+});

package/src/entry/catalog-command.ts

@@ -1,4 +1,3 @@
-import { HOST_ARG, terminalHost } from "./host-arg.ts";
 import { defineCommand } from "citty";
 import { CatherdError, isCatherdError } from "../domain/errors.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
@@ -6,68 +5,35 @@ import { gitToplevel } from "../infra/git.ts";
 import {
   type CatalogModel,
   catalogQuery,
+  type IndexStatus,
   type Refreshed,
   refreshDiscovery,
-  saveTreatLike,
+  refreshIndex,
 } from "../services/catalog-service.ts";
-import { readDerived } from "../infra/sources/cache.ts";
-import { type SyncReport, syncSources } from "../services/source-sync.ts";
-import { clearTreatLike, type LeftOnStandIn, resetTreatLikes, suggestFor } from "../services/treat-likes.ts";
+import { indexCheck } from "../services/doctor-checks.ts";
 import { exitCodeOf, JSON_ARG, mark, printError } from "./cli-kit.ts";
 
-/**
- * Spec 1.2 §9: a sync, one line per source (fetched, fresh, skipped, or failed with the answer it kept),
- * then the rungs newly scored, the user's stand-ins no longer needed and the cross-check warnings.
- */
-export function syncLines(r: SyncReport, plain = false): string[] {
-  if (r.busy) return ["- sources: another sync is running; its results apply when it ends"];
-  const out: string[] = [];
-  for (const s of r.sources) {
-    if (s.state === "fetched") out.push(`${mark("ok", plain)} ${s.source}: fetched`);
-    else if (s.state === "fresh") out.push(`- ${s.source}: fresh (fetched ${s.fetchedAt})`);
-    else if (s.state === "skipped") out.push(`- ${s.source}: ${s.detail}`);
-    else
-      out.push(
-        `${mark("warn", plain)} ${s.source}: ${s.error}; ${s.fetchedAt ? `keeps the answer fetched ${s.fetchedAt}` : "no earlier answer"}`,
-      );
-  }
-  if (r.newlyScored.length) out.push(`newly scored: ${r.newlyScored.join(", ")}`);
-  for (const n of r.noLongerNeeded)
-    out.push(`stand-in no longer needed: ${n.rung} has values of its own for what ${n.like} lent it`);
-  for (const w of r.warnings) out.push(`${mark("warn", plain)} ${w}`);
-  return out;
+/** `sync`'s one line: the index's pair count and age, or why the last fetch failed and what was kept. */
+export function syncLine(s: IndexStatus, plain = false, now = Date.now()): string {
+  const c = indexCheck(now, s);
+  return `${mark(c.state === "ok" ? "ok" : "warn", plain)} ${c.label}: ${c.detail}`;
 }
 
 const sync = defineCommand({
   meta: {
     name: "sync",
     description:
-      "Fetch the public model facts and scores now (each source at most every 12 hours unless --force) and show what changed",
+      "Fetch the Slopalytics index now (it is refreshed at most hourly unless --force) and show how many pairs it holds",
   },
   args: {
-    force: { type: "boolean", description: "fetch every source, however fresh" },
-    unmatched: {
-      type: "boolean",
-      description: "also list each source's ids that match no model in the catalog",
-    },
+    force: { type: "boolean", description: "fetch even when the index was checked within the hour" },
     ...JSON_ARG,
   },
   async run({ args }) {
-    try {
-      const r = await syncSources({ force: args.force === true });
-      if (args.json) console.log(JSON.stringify(r, null, 2));
-      else for (const l of syncLines(r)) console.log(l);
-      if (args.unmatched && !args.json) {
-        const unmatched = readDerived()?.unmatched ?? {};
-        if (Object.keys(unmatched).length === 0) console.log("unmatched: none");
-        for (const [source, ids] of Object.entries(unmatched))
-          console.log(`unmatched in ${source}: ${ids.join(", ")}`);
-      }
-      const got = r.sources.some((s) => s.state === "fetched" || s.state === "fresh");
-      process.exitCode = r.failed.length && !got ? 1 : 0;
-    } catch (e) {
-      fail(e);
-    }
+    const s = await refreshIndex({ force: args.force === true });
+    if (args.json) console.log(JSON.stringify(s, null, 2));
+    else console.log(syncLine(s));
+    process.exitCode = s.pairs === 0 ? 1 : 0;
   },
 });
 
@@ -80,29 +46,19 @@ export function formatRefreshed(r: Refreshed, plain = false): string {
   ].join("\n");
 }
 
-/**
- * One model: its rungs scored and roles, then (spec 1.2 §4.1, §5.3, §8) its price and speed facts, and each
- * rung's values with their confidence and source, and the runs catherd has made on it.
- */
+/** One model: its indexed pairs and roles, then each pair's intelligence, price, speed and the runs catherd has made on it. */
 export function formatModel(m: CatalogModel): string {
-  const scored = m.rungs.filter((r) => r.enabled).length;
   const listed = m.listed === false ? "  not offered by this account" : "";
   const lines = [
-    `${m.backend}:${m.model}  ${scored}/${m.rungs.length} rungs scored  roles ${m.roles.join(",") || "none"}${listed}`,
-  ];
-  const facts = [
-    ...(m.price ? [`$${m.price.input}/$${m.price.output} per M tokens in/out`] : []),
-    ...Object.entries(m.speed).map(([k, v]) => `${k} ${Number(v.toPrecision(4))}`),
+    `${m.backend}:${m.model}  ${m.rungs.length} ${m.rungs.length === 1 ? "pair" : "pairs"}  roles ${m.roles.join(",") || "none"}${listed}`,
   ];
-  if (facts.length) lines.push(`  ${facts.join(" · ")}`);
   for (const r of m.rungs) {
-    // spec 1.2 §5.3: each value with its confidence and source, as `route` reports it; a guess names its rung
-    const values = Object.entries(r.scores).map(
-      ([dim, v]) =>
-        `${dim} ${Number(v.value.toPrecision(4))} (${v.from ? `inferred from ${v.from}` : v.confidence}, ${v.source})`,
-    );
-    if (values.length === 0 && !r.evidence) continue;
-    lines.push(`  #${r.rung.slice(r.rung.lastIndexOf("#") + 1)}  ${values.join(" · ") || "unscored"}`);
+    const parts = [
+      `intelligence ${r.intelligence.toFixed(1)}`,
+      ...(r.price ? [`$${r.price.input}/$${r.price.output} per M`] : []),
+      ...(r.speed !== null ? [`${Number(r.speed.toPrecision(3))} tok/s`] : []),
+    ];
+    lines.push(`  #${r.rung.slice(r.rung.lastIndexOf("#") + 1)}  ${parts.join(" · ")}`);
     if (r.evidence) lines.push(`    runs: ${r.evidence}`);
   }
   return lines.join("\n");
@@ -129,12 +85,11 @@ const refresh = defineCommand({
 });
 
 const list = defineCommand({
-  meta: { name: "list", description: "The models catherd can place, with their scored rungs" },
+  meta: { name: "list", description: "The models catherd can place, with their indexed pairs" },
   args: {
     backend: { type: "string", description: "only this backend or billing key" },
     role: { type: "string", description: `only models for this role (${ROLES.join(", ")})` },
     text: { type: "string", description: "only ids containing this" },
-    scored: { type: "boolean", description: "only models with a scored rung" },
     ...JSON_ARG,
   },
   async run({ args }) {
@@ -149,7 +104,6 @@ const list = defineCommand({
         backend: args.backend,
         role: args.role as Role | undefined,
         text: args.text,
-        scoredOnly: args.scored === true,
         limit: 10_000,
         repo: await hereRepo(),
       });
@@ -161,103 +115,8 @@ const list = defineCommand({
   },
 });
 
-/** Spec 1.2 §6.4: the profile rungs a removal leaves on an inferred stand-in or unscored, one line each. */
-export function leftLines(left: LeftOnStandIn[], plain = false): string[] {
-  return left.map(
-    (l) =>
-      `${mark("warn", plain)} ${l.profile}: ${l.rung} is left ${l.unscored ? "unscored: routing skips it" : `on an inferred stand-in for ${l.dims.join(", ")}`}`,
-  );
-}
-
-/** Spec 1.2 §6.4 `--suggest`: the three nearest stand-ins, each with its distance and the features it rests on. */
-export function suggestLines(r: ReturnType<typeof suggestFor>, rung: string): string[] {
-  const head = r.lacking.length
-    ? `${r.canonical} has no ${r.lacking.join(", ")} value of its own; the nearest stand-ins:`
-    : `${r.canonical} has every value the bars use; the nearest scored rungs:`;
-  if (r.suggestions.length === 0)
-    return [
-      `${r.canonical}: no scored rung shares 3 features with it; map it by hand: catherd catalog treat-like ${rung} <rung>`,
-    ];
-  return [
-    head,
-    ...r.suggestions.map(
-      (s, i) =>
-        `  ${i + 1}. ${s.like}  distance ${s.distance.toFixed(2)}  lends ${s.lends.join(", ")}  on ${s.features.join(", ")}`,
-    ),
-    `map one: catherd catalog treat-like ${rung} <rung>`,
-  ];
-}
-
-const treatLike = defineCommand({
-  meta: {
-    name: "treat-like",
-    description:
-      "Score an unscored rung as a scored one; --suggest ranks stand-ins, --clear and --reset remove your mappings",
-  },
-  args: {
-    ...HOST_ARG,
-    rung: {
-      type: "positional",
-      required: false,
-      description: "the unscored rung, backend:model#effort or model#effort",
-    },
-    like: { type: "positional", required: false, description: "the scored rung whose scores it borrows" },
-    suggest: { type: "string", description: "list the 3 nearest stand-ins for this rung" },
-    clear: { type: "string", description: "remove your treat-like for this rung" },
-    reset: { type: "boolean", description: "remove every treat-like of yours" },
-    ...JSON_ARG,
-  },
-  async run({ args }) {
-    try {
-      const modes = [
-        args.suggest !== undefined,
-        args.clear !== undefined,
-        args.reset === true,
-        args.rung !== undefined,
-      ];
-      if (modes.filter(Boolean).length !== 1 || (args.rung !== undefined && args.like === undefined))
-        throw new CatherdError(
-          "E_INPUT_INVALID",
-          "treat-like takes <rung> <like>, or one of --suggest, --clear, --reset",
-          {
-            fix: "catherd catalog treat-like <rung> <like> | --suggest <rung> | --clear <rung> | --reset",
-          },
-        );
-      if (args.suggest !== undefined) {
-        const r = suggestFor(args.suggest);
-        if (args.json) console.log(JSON.stringify(r, null, 2));
-        else for (const l of suggestLines(r, args.suggest)) console.log(l);
-        return;
-      }
-      if (args.clear !== undefined) {
-        const r = await clearTreatLike(args.clear, terminalHost(args.host).host);
-        if (args.json) return console.log(JSON.stringify(r, null, 2));
-        for (const l of leftLines(r.left)) console.log(l);
-        console.log(`${mark("ok")} ${r.rung} is no longer treated like ${r.like}`);
-        return;
-      }
-      if (args.reset) {
-        const r = await resetTreatLikes(terminalHost(args.host).host);
-        if (args.json) return console.log(JSON.stringify(r, null, 2));
-        for (const l of leftLines(r.left)) console.log(l);
-        console.log(
-          r.removed.length
-            ? `${mark("ok")} removed ${r.removed.length} treat-like${r.removed.length === 1 ? "" : "s"}: ${r.removed.map(([a, b]) => `${a} → ${b}`).join(", ")}`
-            : "no treat-like of yours to remove",
-        );
-        return;
-      }
-      const r = await saveTreatLike(args.rung as string, args.like as string);
-      if (args.json) return console.log(JSON.stringify(r, null, 2));
-      console.log(`${mark("ok")} ${r.rung} is treated like ${r.like}`);
-    } catch (e) {
-      fail(e);
-    }
-  },
-});
-
-/** Spec §8 and 1.2 §9: `catherd catalog refresh|list|sync|treat-like <rung> <like> | --suggest|--clear|--reset`. */
+/** Spec §8: `catherd catalog refresh|list|sync`. */
 export const catalogCommand = defineCommand({
   meta: { name: "catalog", description: "The model catalog" },
-  subCommands: { refresh, list, sync, "treat-like": treatLike },
+  subCommands: { refresh, list, sync },
 });

package/src/entry/check-bin.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+// The detached check worker's entry: it imports only what running one milestone check needs, never src/cli.ts.
+import { errorMessage } from "../domain/errors.ts";
+import { checkWorker } from "../services/milestone-check.ts";
+
+const flight = process.argv[2];
+if (!flight) {
+  console.error("usage: check-bin.ts <flight file>");
+  process.exit(2);
+}
+try {
+  await checkWorker(flight);
+} catch (e) {
+  console.error(`catherd check: ${errorMessage(e)}`);
+  process.exit(1);
+}
+process.exit(0);

package/src/entry/cli-kit.ts

@@ -1,4 +1,5 @@
-import { type CatherdError, isCatherdError } from "../domain/errors.ts";
+import { CatherdError, isCatherdError } from "../domain/errors.ts";
+import { roleScopeFromEnv } from "../domain/role-scope.ts";
 import { RUN_NOT_FOUND_FIX } from "../services/run-store.ts";
 import { glyph, type State } from "./glyphs.ts";
 
@@ -24,13 +25,28 @@ export function printError(e: Pick<CatherdError, "code" | "message" | "fix">): v
 export const exitCodeOf = (e: unknown): number =>
   isCatherdError(e) && e.code === "E_INPUT_INVALID" ? EXIT.usage : EXIT.error;
 
+/**
+ * Spec 1.5 plan 21: a role's shell (CATHERD_ROLE, or its scratch TMPDIR) never runs a command that writes the
+ * orchestrator's state (pause, runs cancel, profile set, …): E_ROLE_SCOPE, as `catherd run-file` and `catherd gate`
+ * refuse an operation the role has not. `command` is the command as typed, like `catherd pause`.
+ */
+export function refuseInRole(env: Record<string, string | undefined>, command: string): void {
+  const scope = roleScopeFromEnv(env);
+  if (!scope) return;
+  throw new CatherdError(
+    "E_ROLE_SCOPE",
+    `${command} is the orchestrator's: this process runs ${scope.name} of run ${scope.run}`,
+    { fix: "report it in your reply; the orchestrator does it" },
+  );
+}
+
 export const printJson = (v: unknown): void => console.log(JSON.stringify(v, null, 2));
 
 /** The `--json` flag every read command takes. */
 export const JSON_ARG = { json: { type: "boolean", description: "print JSON" } } as const;
 
 /**
- * The glyph for a state, as in `✓ ready`: the dashboard's own (spec §9.3), ASCII with `--plain` only;
+ * The glyph for a state, as in `✓ ready`: catherd's own (spec §9.3), ASCII with `--plain` only;
  * NO_COLOR drops colour, never glyphs. The caller adds the word.
  */
 export const mark = (state: State, plain = false): string => glyph(state, plain);

package/src/entry/daemon-bin.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env bun
+// The detached run daemon's entry: like the supervisor's it imports only what driving a run needs, never
+// src/cli.ts.
+import { errorMessage } from "../domain/errors.ts";
+import { runDaemon } from "../services/daemon.ts";
+import { defaultDeps } from "./deps.ts";
+
+const runId = process.argv[2];
+if (!runId) {
+  console.error("usage: daemon-bin.ts <run id>");
+  process.exit(2);
+}
+try {
+  // nobody's role and no Claude Code session: the daemon answers to the run's events
+  const result = await runDaemon({ ...defaultDeps(), session: null, role: null }, runId);
+  if (result === "lost-lock") console.error(`catherd daemon: another daemon holds run ${runId}`);
+} catch (e) {
+  console.error(`catherd daemon: ${errorMessage(e)}`);
+  process.exit(1);
+}
+// the lock is released and the run's events are written: a hook's call left hanging must not keep it alive
+process.exit(0);

package/src/entry/deps.ts

@@ -1,4 +1,5 @@
 import type { HostContext } from "../domain/host.ts";
+import { roleScopeFromEnv } from "../domain/role-scope.ts";
 import { readSessionEnv } from "../infra/claude-session.ts";
 import { VERSION } from "../infra/version.ts";
 import type { Deps } from "../services/ports.ts";
@@ -15,6 +16,7 @@ export function defaultDeps(host: HostContext = { host: "unknown", session: null
     pollMs: 250,
     session: readSessionEnv(process.env),
     now: Date.now,
+    role: roleScopeFromEnv(process.env),
   };
   return deps;
 }

package/src/entry/doctor-command.ts

@@ -1,11 +1,13 @@
 import { gitToplevel } from "../infra/git.ts";
-import { HOST_ARG, terminalHost } from "./host-arg.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { HOST_ARG, terminalHost, withThread } from "./host-arg.ts";
 import { defineCommand } from "citty";
 import { VERSION } from "../infra/version.ts";
 import { type DoctorReport, doctor } from "../services/doctor.ts";
 import type { Check } from "../services/doctor-checks.ts";
 import { EXIT, JSON_ARG, mark, printJson } from "./cli-kit.ts";
 import { mcpHandshake } from "./mcp/handshake.ts";
+import { probeRoleServer } from "../infra/role-mcp.ts";
 
 /**
  * One row per check: `✓ ready  Bun — 1.4.2`, then the full fix on its own line; a fix of several lines
@@ -42,16 +44,32 @@ export const doctorCommand = defineCommand({
       description:
         "send one labeled smoke to the validated original session (receipt does not prove processing)",
     },
+    thread: {
+      type: "string",
+      description:
+        "with --test-push: the Codex thread to send the smoke to (Codex does not export it to the commands it runs)",
+    },
+    docker: {
+      type: "boolean",
+      description:
+        "also probe Docker as a gate sees it: two compose services reaching each other by name, and the free disk (pulls busybox)",
+    },
     plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
   },
   async run({ args }) {
+    if (args.thread !== undefined && args["test-push"] !== true)
+      throw new CatherdError("E_INPUT_INVALID", "--thread only names where --test-push sends its smoke", {
+        fix: `catherd doctor --test-push --thread ${args.thread}`,
+      });
     const r = await doctor({
-      host: terminalHost(args.host),
+      host: withThread(terminalHost(args.host), args.thread),
       repo: await gitToplevel(process.cwd()),
       bunVersion: Bun.version,
       version: VERSION,
       handshake: () => mcpHandshake(),
+      roleServerStart: () => probeRoleServer(),
       testPush: args["test-push"] === true,
+      docker: args.docker === true,
     });
     if (args.json) printJson(r);
     else for (const l of formatReport(r, args.plain === true)) console.log(l);

package/src/entry/glyphs.ts

@@ -1,6 +1,6 @@
 /**
- * Spec §9.3's glyphs, each with its ASCII twin for `--plain`: the dashboard and every CLI command draw
- * state with these. Free of OpenTUI, so `mcp`, `lock` and `_supervise` can load it (spec §3.1).
+ * Spec §9.3's glyphs, each with its ASCII twin for `--plain`: every CLI command draws state with these, so
+ * `mcp`, `lock` and `_supervise` can load them (spec §3.1).
  */
 const GLYPHS = {
   ok: ["✓", "+"],
@@ -32,3 +32,16 @@ export const glyph = (g: Glyph, plain: boolean): string => GLYPHS[g][plain ? 1 :
 
 /** The words state always travels with (spec §9.3: green/amber/red only for state, always with a word). */
 export type State = "ok" | "warn" | "fail" | "skip" | "info";
+
+export type Mood = "good" | "working" | "waiting" | "failed";
+export const FACES: Record<Mood, string> = {
+  good: "=^.^=",
+  working: "=o.o=",
+  waiting: "=-.-=",
+  failed: "=x.x=",
+};
+
+/** The conductor, for the init welcome only (spec §9.3). ASCII already. */
+export function mascot(mood: Mood): [string, string, string] {
+  return [" /\\_/\\  .", `(${FACES[mood]})/`, ' (")(")'].map((l) => l.padEnd(9)) as [string, string, string];
+}

package/src/entry/host-arg.ts

@@ -10,6 +10,34 @@ export const HOST_ARG = {
   },
 };
 
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Plan 22, `doctor --test-push --thread <uuid>`: Codex does not export its thread id to the commands it runs, so a
+ * shell names the thread the smoke goes to. It makes the host that Codex thread; a Claude Code session refuses it.
+ */
+export function withThread(host: HostContext, thread: string | undefined): HostContext {
+  if (thread === undefined) return host;
+  if (!UUID.test(thread))
+    throw new CatherdError("E_INPUT_INVALID", `--thread ${thread} is not a Codex thread id`, {
+      fix: "pass the thread's UUID, as the first line of a catherd message names it (thread: <uuid>)",
+    });
+  if (host.host === "claude-code")
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      "--thread names a Codex thread, and this is a Claude Code session",
+      {
+        fix: "run catherd doctor --test-push without --thread from Claude Code",
+      },
+    );
+  const sessionId = thread.toLowerCase();
+  return {
+    host: "codex",
+    session: { host: "codex", sessionId, hostSessionId: null, name: null },
+    conflict: null,
+  };
+}
+
 export function terminalHost(value: string | undefined, env = process.env): HostContext {
   if (value === undefined || value === "auto") return resolveHost({ env });
   if (value !== "codex" && value !== "claude-code")