catherd-cli 1.3.0 → 1.5.0

package/src/entry/runs-command.ts

@@ -1,5 +1,12 @@
 import { resolve } from "node:path";
 import { defineCommand } from "citty";
+import { assertId } from "../domain/ids.ts";
+import { knownQueueCapability, UNCHECKED_QUEUE } from "../infra/codex-queue.ts";
+import { listDispatches } from "../services/dispatches.ts";
+import { retryDelivery } from "../services/notifier.ts";
+import { pauseLine } from "../services/pause.ts";
+import { inspectDelivery } from "../services/run-debug.ts";
+import { terminalHost } from "./host-arg.ts";
 import { formatBudget } from "../domain/budget.ts";
 import { CatherdError } from "../domain/errors.ts";
 import { gitToplevel } from "../infra/git.ts";
@@ -7,10 +14,13 @@ import { redact } from "../infra/log.ts";
 import { cancel } from "../services/dispatch-service.ts";
 import { registerSavedSecrets } from "../services/jev-service.ts";
 import { runDebug } from "../services/run-debug.ts";
+import { cleanScratch } from "../services/scratch.ts";
+import { repin } from "../services/run-pin.ts";
+import { supersedeRun } from "../services/run-service.ts";
 import { findRun, listRuns, readRecords, type Run } from "../services/run-store.ts";
 import { groupRuns, type RunSession, type SessionGroup } from "../services/session-view.ts";
 import { type RunSummary, status, summarizeRun } from "../services/summary.ts";
-import { JSON_ARG, mark, printJson } from "./cli-kit.ts";
+import { JSON_ARG, mark, printJson, refuseInRole } from "./cli-kit.ts";
 import { defaultDeps } from "./deps.ts";
 
 const json = JSON_ARG;
@@ -34,6 +44,10 @@ export function formatRun(s: RunSummary, now: number = Date.now()): string[] {
   ];
   for (const q of s.questions) lines.push(`  ${mark("warn")} parked ${q.milestone}: ${q.question}`);
   for (const l of s.live) lines.push(`  live ${l.name}  ${l.rung}  ${l.state} ${l.secs}s`);
+  if (s.waiting)
+    lines.push(
+      `  ${s.waiting.stalled ? `${mark("warn")} stalled · ` : ""}waiting for orchestrator since ${s.waiting.since} · ${s.waiting.seconds}s · ${s.waiting.unread} unread result(s)`,
+    );
   lines.push(
     `  done ${t.runs} role run(s), ${t.ok} ok${t.notOk.length ? `; not ok: ${t.notOk.join(", ")}` : ""}`,
     `  tokens ${n(t.tokens.input)} in (${n(t.tokens.cached)} cached) · ${n(t.tokens.output)} out · $${t.costUsd.toFixed(2)}` +
@@ -50,18 +64,35 @@ export function formatRun(s: RunSummary, now: number = Date.now()): string[] {
   for (const m of s.milestones) lines.push(`  landed ${m}`);
   if (s.verifier)
     lines.push(
-      `  verifier step ${s.verifier.item}${s.verifier.carried ? " (carried over)" : ""} at ${s.verifier.at.slice(11, 16)}`,
+      `  verifier step ${s.verifier.item}${s.verifier.carried ? " (carried over)" : ""} at ${s.verifier.at.slice(11, 16)} · ${Math.floor(s.verifier.secs / 60)} min ago · ${s.verifier.open ? "open" : `closed (${s.verifier.closedBy})`}`,
+    );
+  for (const d of s.delivery)
+    lines.push(
+      `  ${JSON.parse(d.eventId)[2] === "stalled" ? "stalled notice" : d.delivery === "collected" ? "collected" : "unread"} ${d.name} · delivery ${d.delivery}${d.receipt ? ` · queue receipt ${d.receipt.msgId}` : ""}`,
     );
   for (const l of s.stateTail) lines.push(`  | ${l}`);
   for (const w of s.warnings) lines.push(`  ${mark("warn")} ${w}`);
   return lines;
 }
 
-function printStatus(runId: string | undefined, asJson: boolean): void {
+/**
+ * `live`: a long-lived watch, which reads the queue capability a background probe keeps fresh. A one-shot
+ * status never probes it: a slow Codex CLI must not delay the stored run state, nor hold the process open.
+ */
+async function printStatus(runId: string | undefined, asJson: boolean, live = false): Promise<void> {
   // redacted as `runs show` is: the state.md tail can quote a secret, and status goes to shared terminals
   registerSavedSecrets();
-  const r = redact(status(defaultDeps(), runId));
+  const host = terminalHost(undefined);
+  const queue =
+    host.host === "codex" && !host.conflict
+      ? live
+        ? knownQueueCapability(process.env)
+        : UNCHECKED_QUEUE
+      : null;
+  const r = redact(status(defaultDeps(host), runId, queue));
   if (asJson) return printJson(r);
+  // spec 1.5 "Group pause": a pause comes first, before any run
+  for (const p of r.paused) console.log(`${mark("warn")} ${pauseLine(p)}`);
   if (r.runs.length === 0) console.log("no runs yet");
   // grouped by session, as the runs page is (spec §4); a run shows once, under the session that started it
   const byId = new Map(r.runs.map((s) => [s.id, s]));
@@ -84,18 +115,26 @@ function printStatus(runId: string | undefined, asJson: boolean): void {
       for (const l of rest) console.log(l);
     }
   }
+  console.log(`inspection host ${r.host.host}${r.host.conflict ? ` · conflict: ${r.host.conflict}` : ""}`);
+  if (r.queue)
+    console.log(
+      r.queue.checked === false
+        ? `queue unchecked · ${r.queue.reason}`
+        : `queue CLI ${r.queue.cli ? "supported" : "unavailable"} · server ${r.queue.server}${r.queue.reason ? ` · ${r.queue.reason}` : ""}`,
+    );
   for (const w of r.warnings) console.log(`${mark("warn")} ${w}`);
 }
 
-/** Spec §8 `catherd status [run] [--json]`: that run, else every run with a live role, else the newest. */
+/** `catherd status [run] [--json]`: that run, else the live runs, else the runs waiting for their orchestrator, else the newest. */
 export const statusCommand = defineCommand({
   meta: {
     name: "status",
-    description: "A run at a glance (default: runs with a live role, else the newest)",
+    description:
+      "A run at a glance (default: live runs, else runs waiting for their orchestrator, else the newest)",
   },
   args: { run: { type: "positional", required: false, description: "run id" }, ...json },
   run({ args }) {
-    printStatus(args.run, args.json === true);
+    return printStatus(args.run, args.json === true);
   },
 });
 
@@ -142,7 +181,7 @@ export const watchCommand = defineCommand({
     }
     for (;;) {
       if (process.stdout.isTTY) process.stdout.write("\x1b[2J\x1b[H");
-      printStatus(undefined, false);
+      await printStatus(undefined, false, true);
       console.log(`updated ${new Date().toLocaleTimeString()} · Ctrl-C to stop`);
       await Bun.sleep(every);
     }
@@ -172,6 +211,8 @@ const list = defineCommand({
         roleRuns: s.totals.runs,
         session: s.session,
         continuedIn: s.continuedIn,
+        waiting: s.waiting,
+        supersededBy: s.supersededBy ?? null,
       };
     };
     const groups = groupRuns(shown);
@@ -182,7 +223,7 @@ const list = defineCommand({
       for (const x of g.runs) {
         const r = row(x.run);
         console.log(
-          `  ${r.id}  ${r.live ? `${r.live} live` : "idle"}  ${r.roleRuns} role run(s)  ${r.title}  ${r.repo}${movedNote(x)}`,
+          `  ${r.id}  ${r.supersededBy ? `superseded by ${r.supersededBy}` : r.live ? `${r.live} live` : r.waiting ? `${r.waiting.stalled ? "stalled · " : ""}waiting for orchestrator ${r.waiting.seconds}s` : "idle"}  ${r.roleRuns} role run(s)  ${r.title}  ${r.repo}${movedNote(x)}`,
         );
       }
     }
@@ -223,6 +264,10 @@ const show = defineCommand({
     for (const d of debug ?? []) {
       console.log(`\n--- ${d.name} ${d.dispatchId} (${d.rung}, admitted ${d.admittedAt})`);
       console.log(`record: ${d.record ? JSON.stringify(d.record) : "none yet"}`);
+      for (const e of d.deliveries.length ? d.deliveries : [d])
+        console.log(
+          `delivery: ${e.delivery}; event ${e.eventId}; receipt ${e.receipt ? JSON.stringify(e.receipt) : "none"}`,
+        );
       console.log(`exit.json: ${d.exit ? JSON.stringify(d.exit) : "none yet"}`);
       for (const [label, lines] of [
         ["stderr", d.stderrTail],
@@ -246,15 +291,116 @@ const cancelCmd = defineCommand({
     name: { type: "positional", required: true, description: "the role's name, as status lists it" },
   },
   async run({ args }) {
+    refuseInRole(process.env, "catherd runs cancel");
     const r = await cancel(defaultDeps(), args.id, args.name);
     console.log(`${mark("ok")} ${r.record.name} ${r.record.status}`);
     for (const h of r.hints) console.log(`  ${h}`);
   },
 });
 
+const clean = defineCommand({
+  meta: {
+    name: "clean",
+    description:
+      "Remove the roles' scratch folders (their TMPDIR) of a run with no live role, or of every such run",
+  },
+  args: { id: { type: "positional", required: false, description: "run id (default: every run)" }, ...json },
+  run({ args }) {
+    refuseInRole(process.env, "catherd runs clean");
+    const r = cleanScratch({ run: args.id });
+    if (args.json) return printJson(r);
+    for (const x of r.removed)
+      console.log(`${mark("ok")} ${x.run}  scratch removed (${n(Math.round(x.bytes / 1024))} KB)`);
+    for (const x of r.kept) console.log(`${mark("skip")} ${x.run}  scratch kept: ${x.why}`);
+    if (!r.removed.length && !r.kept.length) console.log("no scratch to remove");
+  },
+});
+
+const retryPush = defineCommand({
+  meta: {
+    name: "retry-push",
+    description: "Retry a stored event for its current owner, acknowledging possible duplicate input",
+  },
+  args: {
+    run: { type: "positional", required: true, description: "stored run id" },
+    name: { type: "positional", required: true, description: "stored role name" },
+    event: { type: "string", required: true, description: "exact event ID shown by peek/status" },
+    "acknowledge-possible-duplicate": {
+      type: "boolean",
+      description: "explicitly acknowledge possible duplicate native input",
+    },
+    ...json,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd runs retry-push");
+    if (args["acknowledge-possible-duplicate"] !== true)
+      throw new CatherdError("E_INPUT_INVALID", "Retry requires --acknowledge-possible-duplicate");
+    assertId("role name", args.name);
+    const run = findRun(args.run);
+    const d = listDispatches(run).find(
+      (d) =>
+        d.admit.name === args.name &&
+        ["finished", "stalled"].some(
+          (kind) => args.event === JSON.stringify([run.id, d.admit.dispatchId, kind]),
+        ),
+    );
+    if (!d) throw new CatherdError("E_INPUT_INVALID", "Event does not belong to this stored run and role");
+    const deps = defaultDeps(terminalHost(undefined));
+    await retryDelivery(deps, d.dir, args.event, { allowPossibleDuplicate: true });
+    const inspection = inspectDelivery(
+      run,
+      d,
+      readRecords(run).records.some((r) => r.dispatchId === d.admit.dispatchId),
+      args.event,
+    );
+    if (args.json) printJson({ ...inspection, processing: "unconfirmed" });
+    else
+      console.log(
+        `retry inspected: ${inspection.delivery}; event ${args.event}${inspection.receipt ? `; queue receipt ${inspection.receipt.msgId}` : ""}; processing unconfirmed; use peek/result`,
+      );
+  },
+});
+
+const supersede = defineCommand({
+  meta: {
+    name: "supersede",
+    description: "Close a run with a pointer to the run that took it over; status hides it",
+  },
+  args: {
+    id: { type: "positional", required: true, description: "the run to close" },
+    by: { type: "string", required: true, description: "the run that took it over" },
+    ...json,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd runs supersede");
+    const r = await supersedeRun(defaultDeps(), { run: args.id, by: args.by });
+    if (args.json) return printJson(r);
+    console.log(`${mark("ok")} ${r.run} superseded by ${r.by}`);
+    for (const h of r.hints ?? []) console.log(`  ${h}`);
+  },
+});
+
+const pin = defineCommand({
+  meta: {
+    name: "pin",
+    description: "Re-pin a run to the profile, access and isolation its repo runs on now",
+  },
+  args: { id: { type: "positional", required: true, description: "run id" }, ...json },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd runs pin");
+    const r = await repin(defaultDeps(), { run: args.id });
+    if (args.json) return printJson(r);
+    console.log(`${mark("ok")} ${args.id} pinned to ${r.pin.profile}`);
+    for (const c of r.changed) console.log(`  was: ${c}`);
+  },
+});
+
 /** Spec §8 `catherd runs list|show [--debug]|cancel`; a bare `catherd runs` lists them, as `status` needs no run. */
 export const runsCommand = defineCommand({
-  meta: { name: "runs", description: "Runs: list them (the default), show one, cancel a live role" },
-  subCommands: { list, show, cancel: cancelCmd },
+  meta: {
+    name: "runs",
+    description: "Runs: list them (the default), show one, cancel a live role, supersede or re-pin one",
+  },
+  subCommands: { list, show, cancel: cancelCmd, clean, "retry-push": retryPush, supersede, pin },
   default: "list",
 });

package/src/entry/supervise-command.ts

@@ -1,8 +1,11 @@
 import { defineCommand } from "citty";
 import { adapterFor } from "../adapters/registry.ts";
 import { workerEnv } from "../infra/env.ts";
+import { log } from "../infra/log.ts";
+import { loginEnv } from "../infra/login-env.ts";
 import { readVersioned } from "../infra/store.ts";
 import { SuperviseSpecSchema, supervise } from "../infra/supervisor.ts";
+import { resolveRefs } from "../services/gate-env.ts";
 import "../adapters/all.ts";
 
 /**
@@ -10,22 +13,46 @@ import "../adapters/all.ts";
  * spec.json holds only the adapter's env overrides; the worker's env is built here, from this process's
  * own inherited env (already without catherd's secrets), so no credential is ever on disk (spec §10.4).
  */
+/**
+ * The worker's env: this process's env, the gate env's references (plan 23: read here from this env, else the
+ * login env), then the spec's own env last, so no reference ever takes the role's identity, scratch or home.
+ */
+export function superviseEnv(
+  read: { env: Record<string, string>; envFrom?: Record<string, string>; cwd: string; dispatchDir?: string },
+  base: Record<string, string | undefined>,
+  login: () => Record<string, string | undefined>,
+): Record<string, string> {
+  const refs = resolveRefs({}, read.envFrom ?? {}, base, login);
+  if (refs.missing.length) log("warn", "gate-env", { dispatch: read.dispatchDir, unset: refs.missing });
+  return workerEnv(base, { ...refs.env, ...read.env }, read.cwd);
+}
+
 export async function runSupervise(specPath: string): Promise<void> {
   const read = readVersioned(specPath, SuperviseSpecSchema, 1);
-  const spec = { ...read, env: workerEnv(process.env, read.env, read.cwd) };
+  const spec = { ...read, env: superviseEnv(read, process.env, loginEnv) };
   const a = adapterFor(spec.backend);
   const busy = a?.isBusy?.bind(a);
   const stop = a?.interrupt?.bind(a);
-  await supervise(spec, {
+  const retrying = a?.providerRetry?.bind(a);
+  const ended = await supervise(spec, {
     onLine: (line) => {
       const d = a?.parse(line) ?? {};
-      return { final: d.final, thread: d.thread, item: d.item };
+      return { final: d.final, thread: d.thread, item: d.item, step: d.step };
     },
     isBusy: busy
       ? (thread, sinceMs) => (thread ? busy(thread, spec.cwd, sinceMs) : Promise.resolve(false))
       : undefined,
     interrupt: stop ? (thread) => (thread ? stop(thread, spec.cwd) : Promise.resolve()) : undefined,
+    providerRetry: retrying
+      ? (thread, sinceMs) => (thread ? retrying(thread, spec.cwd, sinceMs) : Promise.resolve(null))
+      : undefined,
   });
+  // plan 22: a Codex owner hears of the role from here too, when its thread's MCP server is gone. Loaded only
+  // once the worker ended (a supervisor that lost the lock to another pushes nothing); never throws.
+  if (ended && process.env.CATHERD_NO_END_PUSH !== "1") {
+    const { pushFromEnd } = await import("../services/end-push.ts");
+    await pushFromEnd(spec.dispatchDir);
+  }
 }
 
 export const superviseCommand = defineCommand({

package/src/entry/tui/effects.ts

@@ -1,3 +1,5 @@
+import type { HostContext } from "../../domain/host.ts";
+import { sessionKey } from "../../domain/host.ts";
 import { realpathSync, statSync, watch } from "node:fs";
 import { adapterFor } from "../../adapters/registry.ts";
 import "../../adapters/all.ts";
@@ -70,6 +72,7 @@ export type {
 
 /** One line of the run list. */
 export interface RunRow {
+  waiting?: RunSummary["waiting"];
   id: string;
   title: string;
   repo: string;
@@ -88,6 +91,7 @@ export interface RunRow {
  * The live set calls the services; tests and the storybook pass fakes.
  */
 export interface Effects {
+  host: HostContext;
   version: string;
   doctor(): Promise<DoctorReport>;
   runs(): { rows: RunRow[]; warnings: string[] };
@@ -204,6 +208,7 @@ export function stampOf(dir: string): string {
     p.jev,
     p.agents,
     p.state,
+    p.stateJson,
     p.ledger,
     p.roles,
     profilesDir(),
@@ -230,6 +235,7 @@ export function memoRuns(compute: (run: Run) => RunRow, stamp: (dir: string) =>
     runs.map((r) => {
       const s = stamp(r.dir);
       const hit = cache.get(r.dir);
+      // the wait is computed with the row, once per stamp change; the views age it (waitingLine)
       if (hit && hit.stamp === s && hit.row.live === 0) return hit.row;
       const row = compute(r);
       cache.set(r.dir, { stamp: s, row });
@@ -239,6 +245,7 @@ export function memoRuns(compute: (run: Run) => RunRow, stamp: (dir: string) =>
 
 export function rowOf(s: RunSummary): RunRow {
   return {
+    waiting: s.waiting,
     id: s.id,
     title: s.title,
     repo: s.repo,
@@ -247,7 +254,7 @@ export function rowOf(s: RunSummary): RunRow {
     roleRuns: s.totals.runs,
     landed: s.milestones.length,
     budget: s.budget?.fraction ?? null,
-    session: s.session?.sessionId ?? null,
+    session: s.session ? sessionKey(s.session) : null,
   };
 }
 
@@ -314,14 +321,19 @@ export function watchDirs(
  * The live effects. `repo` is the git toplevel the TUI was opened in (null outside one): inside a repo
  * bound to a profile, `here` is that profile and activating binds the repo instead of the global profile.
  */
-export function liveEffects(repo: string | null = null): Effects {
-  const deps = defaultDeps();
+export function liveEffects(
+  repo: string | null = null,
+  host: HostContext = { host: "unknown", session: null, conflict: null },
+): Effects {
+  const deps = defaultDeps(host);
   const rows = memoRuns((r) => rowOf(summarizeRun(deps, r)));
   const harnesses = HARNESS_KEYS.filter((h) => adapterFor(h));
   const bound = () => (repo !== null && readProjects().bindings[repo] !== undefined ? repo : null);
   return {
+    host,
     version: VERSION,
-    doctor: () => doctor({ bunVersion: Bun.version, version: VERSION, handshake: () => mcpHandshake() }),
+    doctor: () =>
+      doctor({ host, repo, bunVersion: Bun.version, version: VERSION, handshake: () => mcpHandshake() }),
     runs() {
       const { runs, corrupt } = listRuns();
       return { rows: rows(runs), warnings: corrupt.map((c) => `skipped run ${c.id}: ${c.reason}`) };
@@ -343,7 +355,7 @@ export function liveEffects(repo: string | null = null): Effects {
         models: catalogQuery({ scoredOnly: false, limit: Number.MAX_SAFE_INTEGER }, billing).models,
       };
     },
-    validate: (p, c) => validateHere(p, c),
+    validate: (p, c) => validateHere(p, c, undefined, host.host),
     enforcement: enforcementOf,
     harnesses,
     isolation(h) {
@@ -356,10 +368,13 @@ export function liveEffects(repo: string | null = null): Effects {
     agents: (p) => agentFiles(p, VERSION).map((f) => f.name),
     async save(name, patch, treatLikes, shown) {
       for (const [rung, like] of Object.entries(treatLikes)) await saveTreatLike(rung, like);
-      return patchProfile(name, patch, shown === undefined ? {} : { expect: shown });
+      return patchProfile(name, patch, {
+        host: host.host,
+        ...(shown === undefined ? {} : { expect: shown }),
+      });
     },
-    activate: (name, scope) => activate(name, scope),
-    create: createProfile,
+    activate: (name, scope) => activate(name, scope, host.host),
+    create: (name, from) => createProfile(name, from, host.host),
     remove: deleteProfile,
     refreshCatalog: () => refreshDiscovery(),
     syncSources: () => syncSources(),

package/src/entry/tui/fixtures.ts

@@ -1,3 +1,5 @@
+import type { OrchestrationHost } from "../../domain/host.ts";
+import { sessionKey } from "../../domain/host.ts";
 import { isDeepStrictEqual } from "node:util";
 import {
   applyPatch,
@@ -30,6 +32,9 @@ import { withStaged } from "./profile-tree.ts";
  * the catalog is the shipped one, read through the catalog service.
  */
 export const FIXTURE_REPORT: DoctorReport = {
+  host: { host: "unknown", session: null, conflict: null },
+  queue: null,
+  push: null,
   ready: false,
   version: "1.0.0",
   checks: [
@@ -79,6 +84,7 @@ export const FIXTURE_REPORT: DoctorReport = {
 };
 
 const summary = (o: Partial<RunSummary> & Pick<RunSummary, "id" | "title">): RunSummary => ({
+  delivery: [],
   repo: "/home/me/app",
   createdAt: "2026-09-26T11:48:00.000Z",
   session: null,
@@ -112,7 +118,13 @@ const FIXTURE_RUNS: RunSummary[] = [
   summary({
     id: JOBS,
     title: "Jobs screen",
-    session: { sessionId: "s-jobs", hostSessionId: null, name: "jobs screen", live: true },
+    session: {
+      host: "claude-code",
+      sessionId: "s-jobs",
+      hostSessionId: null,
+      name: "jobs screen",
+      live: true,
+    },
     stateTail: ["M1 in review", "Next: fix round for M1.L2"],
     live: [
       {
@@ -141,7 +153,13 @@ const FIXTURE_RUNS: RunSummary[] = [
     title: "Auth refactor",
     repo: "/home/me/api",
     createdAt: "2026-09-25T09:00:00.000Z",
-    session: { sessionId: "s-auth", hostSessionId: null, name: "auth build", live: false },
+    session: {
+      host: "claude-code",
+      sessionId: "s-auth",
+      hostSessionId: null,
+      name: "auth build",
+      live: false,
+    },
     continuedIn: "kit follow-up",
     stateTail: ["Next: done"],
     totals: {
@@ -200,7 +218,7 @@ const auth = (continued: SessionRun["continued"]): SessionRun => ({
 export const FIXTURE_SESSIONS: { row: SessionRow; runs: SessionRun[] }[] = [
   {
     row: {
-      key: "s-jobs",
+      key: sessionKey({ host: "claude-code", sessionId: "s-jobs" }),
       name: "jobs screen",
       live: true,
       runs: 1,
@@ -267,7 +285,7 @@ export const FIXTURE_SESSIONS: { row: SessionRow; runs: SessionRun[] }[] = [
   },
   {
     row: {
-      key: "s-kit",
+      key: sessionKey({ host: "claude-code", sessionId: "s-kit" }),
       name: "kit follow-up",
       live: false,
       runs: 1,
@@ -279,7 +297,7 @@ export const FIXTURE_SESSIONS: { row: SessionRow; runs: SessionRun[] }[] = [
   },
   {
     row: {
-      key: "s-auth",
+      key: sessionKey({ host: "claude-code", sessionId: "s-auth" }),
       name: "auth build",
       live: false,
       runs: 2,
@@ -394,6 +412,7 @@ const BACKENDS = ["claude", "codex", "claude-code", "opencode"];
  * directory the TUI stands in and `bindings` the repo bindings, as `liveEffects(repo)` reads them.
  */
 export interface FixtureOptions {
+  host?: OrchestrationHost;
   runs?: RunSummary[];
   sessions?: { row: SessionRow; runs: SessionRun[] }[];
   report?: DoctorReport;
@@ -418,6 +437,7 @@ export function fixtureEffects(o: FixtureOptions = {}): Effects & {
   /** the run folders watched now */
   watched: string[][];
 } {
+  const host = o.host ?? "claude-code";
   const runs = o.runs ?? FIXTURE_RUNS;
   const sessions = o.sessions ?? FIXTURE_SESSIONS;
   const listeners = new Set<() => void>();
@@ -434,15 +454,17 @@ export function fixtureEffects(o: FixtureOptions = {}): Effects & {
     after: ProfileDoc,
     staged: Record<string, string> = {},
   ) => {
-    const p = resolveProfile(after, name);
+    const p = resolveProfile(after, name, host);
     const c = withStaged(loadCatalog({ timings: false }), staged);
-    const v = validateProfile(p, c, BACKENDS);
+    const v = validateProfile(p, c, BACKENDS, undefined, host);
     // spec 1.2 §6.2, as the ProfileService rules: a save that repairs part of an invalid profile goes through
-    const was = docs.has(name) ? validateProfile(resolveProfile(before, name), c, BACKENDS) : null;
+    const was = docs.has(name)
+      ? validateProfile(resolveProfile(before, name, host), c, BACKENDS, undefined, host)
+      : null;
     return {
       saved: repairs(was, v),
       ...v,
-      diff: diffProfiles(resolveProfile(before, name), p),
+      diff: diffProfiles(resolveProfile(before, name, host), p),
       linked: [],
       pruned: [],
       newSessionNeededFor: [],
@@ -454,6 +476,7 @@ export function fixtureEffects(o: FixtureOptions = {}): Effects & {
     touch: () => {
       for (const l of listeners) l();
     },
+    host: { host, session: null, conflict: null },
     version: "1.0.0",
     doctor: async () => o.report ?? FIXTURE_REPORT,
     runs: () => ({ rows: runs.map(rowOf), warnings: [] }),
@@ -520,7 +543,7 @@ export function fixtureEffects(o: FixtureOptions = {}): Effects & {
       catalog: loadCatalog({ timings: false }),
       models: catalogQuery({ scoredOnly: false, limit: Number.MAX_SAFE_INTEGER }, billing).models,
     }),
-    validate: (p, c) => validateProfile(p, c, BACKENDS),
+    validate: (p, c) => validateProfile(p, c, BACKENDS, undefined, host),
     enforcement: (rung) => (rung.startsWith("codex:") ? "enforced" : "advisory"),
     harnesses: ["codex", "claude-code", "opencode"],
     isolation: () => ({}),

package/src/entry/tui/run.tsx

@@ -1,3 +1,4 @@
+import { terminalHost } from "../host-arg.ts";
 import { type CliRenderer, createCliRenderer, SystemClock } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 import { gitToplevel } from "../../infra/git.ts";
@@ -26,6 +27,7 @@ import { App } from "./views/app.tsx";
 
 export interface TuiOptions {
   rawArgs: string[];
+  host?: string;
   tab?: Tab;
   env?: Record<string, string | undefined>;
   /** Whether stdin and stdout are a terminal; tests pass it so none reads the real one. */
@@ -59,8 +61,9 @@ export async function openTui(o: TuiOptions): Promise<number> {
   }
   const keybinds = keybindsFromConfig();
   const story = Boolean(env.CATHERD_STORY);
+  const host = terminalHost(o.host, env);
   // the repo this directory is in, resolved once at start (the repo ruling)
-  const effects: Effects = story ? fixtureEffects() : liveEffects(await gitToplevel(process.cwd()));
+  const effects: Effects = story ? fixtureEffects() : liveEffects(await gitToplevel(process.cwd()), host);
   const renderer = await createCliRenderer({
     exitOnCtrlC: false,
     useMouse: false,
@@ -83,7 +86,7 @@ export async function openTui(o: TuiOptions): Promise<number> {
         keymap={createAppKeymap(renderer)}
         effects={effects}
         clock={new WallClock()}
-        initial={initialState(o.tab ?? "status")}
+        initial={initialState(o.tab ?? "status", effects.host.host)}
         copy={(text) => renderer.copyToClipboardOSC52(text)}
         onExit={(code, kept) => {
           result = { code, kept };
@@ -103,6 +106,9 @@ export async function openTui(o: TuiOptions): Promise<number> {
 }
 
 /** Bare `catherd`: `cli.ts` imports this only when no subcommand was named, so no subcommand loads OpenTUI. */
-export async function tuiRun(ctx: { rawArgs: string[] }): Promise<void> {
-  process.exitCode = await openTui({ rawArgs: ctx.rawArgs });
+export async function tuiRun(ctx: { rawArgs: string[]; args?: Record<string, unknown> }): Promise<void> {
+  process.exitCode = await openTui({
+    rawArgs: ctx.rawArgs,
+    host: typeof ctx.args?.host === "string" ? ctx.args.host : undefined,
+  });
 }