catherd-cli 1.3.0 → 1.4.0

package/plugin/skills/catherd-setup/SKILL.md

@@ -7,7 +7,9 @@ description: Use when the user wants to tune catherd — which models and effort
 
 You tune the user's catherd profile in conversation. A profile says, per role, which rungs it may run on (`backend:model#effort`, in ladder order) and what it may touch (its access mode); whether routing favours cost or speed; how each backend is billed; whether Jev picks the rung; which rung stands in when a backend hits its usage limit; the run budget and timeouts; whether each vendor harness runs with the user's customizations or isolated; how many heavy commands run at once; and when to push.
 
-**You never edit a file by hand.** `profile_set` is the only writer, so this conversation, the `catherd profile` commands and the TUI cannot drift apart.
+**You never edit a file by hand.** Use `profile_set` for patches and the existing reviewed CLI reset below; both go through ProfileService, as do the `catherd profile` commands and the TUI.
+
+**Discover the host first with `status()`.** Use the host's available MCP discovery facility; names and deferred tools differ. Claude Code may use `ToolSearch`; Codex never needs invented Claude tools or native Claude agents. Pass the actual project `repo` explicitly to profile, setup and catalog calls that accept it: native Codex starts the MCP server in the installed plugin root, not the project. An unknown terminal can use `catherd init --host codex` or `--host claude-code` for setup; this does not create a conversation owner. Conflicting identity must be resolved before ownership or push.
 
 ## Rules
 
@@ -21,17 +23,19 @@ You tune the user's catherd profile in conversation. A profile says, per role, w
 Ask these, one at a time, each with its recommended answer:
 
 1. **Their order of speed, cost and quality.** Recommend cost first, the default `objective`: catherd climbs a rung when a cheap one cannot do the work, so the lanes that need speed get it anyway, and the reviewer and the verifier hold quality either way.
-2. **The subscriptions they hold:** a ChatGPT plan (Codex), a Claude plan, OpenCode Go, Zen credit or API keys. They set `billing` per key (`codex`, `claude`, `claude-code`, `opencode-go`, `opencode`, `cursor`, `grok`, `antigravity`): `chatgpt-plan`, `claude-plan`, `subscription` or `metered`. Recommend leaning on subscriptions before metered spend, and on Claude last among the workers, since it spends the same quota as this conversation.
+2. **The subscriptions they hold:** a ChatGPT plan (Codex), a Claude plan, OpenCode Go, Zen credit or API keys. They set `billing` per key (`codex`, `claude`, `claude-code`, `opencode-go`, `opencode`, `cursor`, `grok`, `antigravity`): `chatgpt-plan`, `claude-plan`, `subscription` or `metered`. Recommend leaning on subscriptions before metered spend. Explain which workers share this conversation's quota from the actual host and billing facts.
 3. **The kind of work they orchestrate:** front-end screens, back-end services, terminal and ops work, docs. Recommend from their own runs when `runs_summary` has any.
 
 ## 2. Read the facts before proposing
 
 In one message, call:
 
-- `catalog_query({ role: "<role>" })` for each role you will discuss: the models that can fill it, their scored rungs, any "treat like", each rung's cost under their billing, and whether their backend's last listing offers it (`listed: false` means their account does not);
+- `catalog_query({ repo, role: "<role>" })` for each role you will discuss: the models that can fill it, their scored rungs, any "treat like", each rung's cost under their billing, and whether their backend's last listing offers it (`listed: false` means their account does not);
 - `runs_summary({})`: how each rung has done on their own runs (runs, refusals, climbs, time) and the harness cost line, for claude-code and opencode only: Codex reports no per-request input, so it has no harness figure;
 - `profile_get({ repo })`: where they stand now, with each role's `access` and `enforcement`. Pass the user's repo: without a name, the profile tools act on the profile this repo runs on (the one bound to it, else the active one), which `here` names; `active` is the global active profile.
 
+Verify the exact omitted Codex model ID `gpt-6.1-sol` against native catalog discovery and validation. If its spelling differs, report the mismatch and resolve it explicitly with the owner; never silently normalize or substitute a model. Retain architect high and verifier low effort.
+
 ## 3. Propose one decision at a time
 
 Go through these in order, and skip any the user does not care about:
@@ -40,7 +44,7 @@ Go through these in order, and skip any the user does not care about:
 2. `billing`, from step 1;
 3. the worker's `rungs` and its `defaultRung`;
 4. the reviewer and the UI reviewer;
-5. the architect and the verifier, which spend Claude quota. A `claude:` rung runs as a native subagent in this session; a `claude-code:` rung runs headless through `dispatch`. Recommend native for these two;
+5. the architect and the verifier. Recommend omitted host defaults: on Codex, exactly `codex:gpt-6.1-sol#high` and `codex:gpt-6.1-sol#low`; on Claude Code, the existing native Claude defaults. A `claude:` rung requires a Claude Code host and its native `Agent`; `claude-code:` runs headless through `dispatch` on either host. Codex architect/verifier use process `dispatch`/`result`. Preserve explicit model IDs, efforts, ladder order and all other fields. Never silently convert `claude:` into `claude-code:`;
 6. the writer, the researcher and the artist;
 7. each role's `access` (below);
 8. `failover` (below);
@@ -48,6 +52,16 @@ Go through these in order, and skip any the user does not care about:
 10. harness isolation, per harness (below);
 11. `lock.heavy` and `notify`.
 
+Existing materialized profiles remain unchanged on read, init, upgrade or host switch. To deliberately opt into host defaults, use the existing CLI from the project directory, naming the profile returned by `profile_get`:
+
+```sh
+catherd profile reset-host-defaults <profile> --host codex --preview --json > /tmp/catherd-host-defaults-review.json
+# Read the complete diff, effective defaults, errors and warnings before saving.
+catherd profile reset-host-defaults <profile> --host codex --expect /tmp/catherd-host-defaults-review.json --json
+```
+
+Use `--host claude-code` for that host. This reviewed reset removes only architect/verifier `rungs` and `defaultRung`, preserving access, enabled state, network, budget, isolation, billing, routing and failover. The `--expect` file guards against a profile changing after review. There is no MCP reset tool. Offer the exact headless model/effort equivalent as a separate explicit choice when a native Claude rung is incompatible with Codex.
+
 Each proposal has three parts: the change, a worked example from their facts, and the tradeoff in their terms. For instance: "Luna high on build lanes: about 5 min slower than Sol medium, no Claude quota, climbs on 1 in 5 of your runs so far."
 
 - Offer only the rungs `catalog_query` lists as capable for the role, written `backend:model#effort`.
@@ -59,6 +73,8 @@ Each proposal has three parts: the change, a worked example from their facts, an
 
 **Budget and timeouts.** `budget` (`minutes`, `tokens`, `usd`) is a soft cap: from 80 % routing starts at the cheapest rung that clears the bar, and at 100 % no new role starts. `timeouts.idleMin` (15) stops a role that has gone quiet, `timeouts.wallMin` (90) one that runs too long. `preflight.confirm: true` makes `preflight` show its commands for the user to approve first.
 
+**Notifications and readiness.** `notify` controls milestone, finish and blocked moments through whatever notification facility the host actually exposes; Claude Code may have `PushNotification`. Do not invent a Codex tool or a scheduling promise. Completion uses Claude's peer inbox or Codex's existing native queue (`--remote unix://`); a Codex busy session receives ordered next input after its active turn, not urgent next-tool-round delivery. Queue acceptance proves neither processing nor `result` collection; unloaded/interrupted sessions may retain input. `catherd doctor --host codex` checks capability without sending; only explicit `--test-push` sends a labeled smoke input. Use the orchestration skill's `peek`/`result` recovery and current-owner, exact-event `runs retry-push` decision for ambiguity.
+
 **Harness isolation.** For each harness they use (`codex`, `claude-code`, `opencode`, `cursor`, `grok`, `antigravity`), offer `harness.<name>.isolated` with its harness line from `runs_summary` (Codex has none: it reports no per-request input, so say there is no figure for it instead of offering one) and this tradeoff: "native keeps your hooks, skills and AGENTS.md; isolated saves ~N tokens per run, but the role loses them." Recommend native. When they have no isolated runs yet, the number is the median first-turn input of their native runs: say that isolation would save some part of it, not all of it. When there are no runs at all, say there is no number yet, and recommend native until there is.
 
 ## 4. Write it
@@ -71,5 +87,5 @@ Each proposal has three parts: the change, a worked example from their facts, an
 ## 5. Say what applies when
 
 - Codex, claude-code, opencode, Cursor, grok and Antigravity changes, access and isolation included, apply at the next dispatch, even in a run already under way. Isolating Cursor needs `CURSOR_API_KEY` in the environment catherd runs in, isolating grok `XAI_API_KEY`, and isolating Antigravity `GEMINI_API_KEY`; `profile_validate` refuses each without. A read-only role (reviewer, architect, researcher) can run on Antigravity only isolated: agy has no read-only mode.
-- An agent listed in `newSessionNeededFor` applies from the next Claude Code session: Claude Code reads agent files when a session starts. Other Claude changes apply now.
-- Editing a profile that is not the active one writes its agent files but links none; they apply once it becomes active (`catherd profile use <name>`), or in a repo it is bound to (`catherd profile use <name> --repo`).
+- For native Claude roles, an agent listed in `newSessionNeededFor` applies from the next Claude Code session: Claude Code reads agent files when a session starts. Other Claude changes apply now. `record_agent_run` accounts only for native Claude Agent results on Claude Code; process records are automatic.
+- ProfileService manages Claude agent files/links only when native Claude roles are used. Codex-only setup and profile operations do not write under `~/.claude`; Claude CLI/login is needed only by an enabled selected role or reachable failover that uses it. Editing an inactive Claude-dependent profile writes its managed files but links none; they apply once active or repo-bound. Keep role-disabled, access, isolation, budget and failover choices intact.

package/src/adapters/access.ts

@@ -1,3 +1,4 @@
+import { scrubSecrets } from "../infra/env.ts";
 import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
@@ -53,7 +54,12 @@ export type ToolQuery = (bin: string, args: string[]) => string[];
 
 const queryTool: ToolQuery = (bin, args) => {
   try {
-    const r = Bun.spawnSync([bin, ...args], { stdout: "pipe", stderr: "ignore", timeout: 5_000 });
+    const r = Bun.spawnSync([bin, ...args], {
+      env: scrubSecrets(process.env),
+      stdout: "pipe",
+      stderr: "ignore",
+      timeout: 5_000,
+    });
     return r.exitCode === 0
       ? r.stdout
           .toString()

package/src/adapters/cli.ts

@@ -1,67 +1,4 @@
-import { scrubSecrets } from "../infra/env.ts";
-import { log } from "../infra/log.ts";
-import { killGroup } from "../infra/proc.ts";
-
-export interface CliResult {
-  ok: boolean;
-  out: string;
-  err: string;
-}
-
-/** Process groups of CLI calls still running: an exiting catherd (Ctrl-C is exit 130) kills them. */
-const live = new Set<number>();
-let hooked = false;
-function track(pid: number): void {
-  live.add(pid);
-  if (hooked) return;
-  hooked = true;
-  // a detached group gets no terminal SIGINT, and process.exit skips the timeout, so kill it on the way out
-  process.on("exit", () => {
-    for (const g of live) killGroup(g, "SIGKILL");
-  });
-}
-
-/**
- * Runs `bin <args>` without catherd's secrets and with no stdin; null when `bin` is not on PATH. A call
- * past `timeoutMs` is killed with every process it started (it runs in its own process group) and is
- * reported as failed, so neither a wedged CLI nor a child holding its pipes stalls the caller.
- */
-export async function runCli(
-  bin: string,
-  args: string[],
-  o: { timeoutMs: number; env?: Record<string, string>; cwd?: string },
-): Promise<CliResult | null> {
-  if (!Bun.which(bin, { PATH: process.env.PATH ?? "" })) return null;
-  log("debug", "spawn", { argv: [bin, ...args], env: o.env ?? {} });
-  const p = Bun.spawn([bin, ...args], {
-    cwd: o.cwd,
-    env: { ...scrubSecrets(process.env), ...o.env },
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-    detached: true,
-  });
-  track(p.pid);
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const late = new Promise<null>((resolve) => {
-    timer = setTimeout(() => resolve(null), o.timeoutMs);
-  });
-  try {
-    const done = await Promise.race([
-      Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]),
-      late,
-    ]);
-    if (!done) {
-      killGroup(p.pid, "SIGKILL");
-      return { ok: false, out: "", err: `${bin} ${args.join(" ")} timed out after ${o.timeoutMs} ms` };
-    }
-    const [code, out, err] = done;
-    return { ok: code === 0, out, err };
-  } finally {
-    clearTimeout(timer);
-    live.delete(p.pid);
-  }
-}
+export { runCli, type CliResult } from "../infra/cli.ts";
 
 /** The JSON a CLI printed, or null for empty or unreadable output. */
 export function jsonOf(out: string | undefined): unknown {

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { HOST_ARG } from "./entry/host-arg.ts";
 import type { ArgsDef } from "citty";
 import { errorMessage } from "./domain/errors.ts";
 import { runtimeRefusal } from "./domain/runtime.ts";
@@ -12,7 +13,7 @@ if (refusal) {
 
 const { realpathSync } = await import("node:fs");
 const { fileURLToPath } = await import("node:url");
-const { defineCommand, renderUsage, runCommand } = await import("citty");
+const { defineCommand, renderUsage, runCommand, parseArgs } = await import("citty");
 const { CatherdError, isCatherdError } = await import("./domain/errors.ts");
 const { EXIT, exitCodeOf, printError, stripAnsi } = await import("./entry/cli-kit.ts");
 const { VERSION } = await import("./infra/version.ts");
@@ -21,6 +22,7 @@ type Command = ReturnType<typeof defineCommand>;
 
 /** The dashboard's flags, typed as any command's args so `main` stays a plain `Command`. */
 const dashboardArgs: ArgsDef = {
+  ...HOST_ARG,
   plain: {
     type: "boolean",
     description: "the dashboard in ASCII without colour (NO_COLOR also drops colour)",
@@ -56,7 +58,7 @@ export const main: Command = defineCommand({
   },
   // citty runs this after any subcommand too; only a bare `catherd` loads and opens the dashboard
   async run(ctx) {
-    if (!ctx.rawArgs.every((a) => a.startsWith("-"))) return;
+    if (ctx.args._.length > 0) return;
     await (await import("./entry/tui/run.tsx")).tuiRun(ctx);
   },
 });
@@ -69,14 +71,24 @@ async function commandFor(argv: string[]): Promise<[Command, Command | undefined
   let cmd = main;
   let parent: Command | undefined;
   const path: string[] = [];
-  for (const a of argv) {
-    if (a.startsWith("-")) continue;
+  let remaining = argv;
+  while (true) {
+    const defs = await resolve(cmd.args ?? {});
+    const navigationArgs: ArgsDef = Object.fromEntries(
+      Object.entries(defs).map(([key, def]) => [
+        key,
+        { ...def, required: false, ...(def.type === "enum" ? { type: "string" as const } : {}) },
+      ]),
+    ) as ArgsDef;
+    const a = parseArgs(remaining, navigationArgs)._[0];
+    if (!a) break;
     const subs = cmd.subCommands ? await resolve(cmd.subCommands) : undefined;
     const next = subs?.[a];
     if (!next) break;
     parent = cmd;
     cmd = (await resolve(next)) as Command;
     path.push(a);
+    remaining = remaining.slice(remaining.indexOf(a) + 1);
   }
   return [cmd, parent, path];
 }
@@ -123,22 +135,39 @@ export async function runCli(argv: string[]): Promise<number> {
     console.log(`${await helpText(cmd, path)}\n`);
     return EXIT.ok;
   }
-  const command = own.find((a) => !a.startsWith("-"));
-  // a bare `catherd` opens the dashboard, which takes only its own flags: a typo is not a terminal problem
-  const flag = (a: string) => (a.startsWith("--") ? (a.slice(2).split("=")[0] ?? "") : "");
-  // citty negates a boolean as `--no-<name>`
-  const known = (name: string) =>
-    Object.hasOwn(dashboardArgs, name) ||
-    (name.startsWith("no-") && dashboardArgs[name.slice(3)]?.type === "boolean");
-  const unknown = command === undefined ? own.find((a) => !known(flag(a))) : undefined;
-  if (unknown !== undefined) {
-    printError(new CatherdError("E_INPUT_INVALID", `unknown option ${unknown}`, { fix: "catherd --help" }));
-    return EXIT.usage;
-  }
-  // `lock` forwards signals to its command itself; everything else stops at once on Ctrl-C. The command is
-  // the first word that is not a flag: `catherd --plain lock -- …` is `lock` too.
-  if (command !== "lock") process.once("SIGINT", () => process.exit(EXIT.interrupted));
   try {
+    const command = parseArgs(own, dashboardArgs)._[0];
+    // a bare `catherd` opens the dashboard, which takes only its own flags: a typo is not a terminal problem
+    const flag = (a: string) => (a.startsWith("--") ? (a.slice(2).split("=")[0] ?? "") : "");
+    // citty negates a boolean as `--no-<name>`
+    const known = (name: string) =>
+      Object.hasOwn(dashboardArgs, name) ||
+      (name.startsWith("no-") && dashboardArgs[name.slice(3)]?.type === "boolean");
+    const unknown =
+      command === undefined
+        ? own.find((a, i) => a.startsWith("-") && !known(flag(a)) && own[i - 1] !== "--host")
+        : undefined;
+    if (unknown !== undefined) {
+      printError(new CatherdError("E_INPUT_INVALID", `unknown option ${unknown}`, { fix: "catherd --help" }));
+      return EXIT.usage;
+    }
+    // `lock` forwards signals to its command itself; everything else stops at once on Ctrl-C. The command is
+    // the first word that is not a flag: `catherd --plain lock -- …` is `lock` too.
+    if (command !== "lock") process.once("SIGINT", () => process.exit(EXIT.interrupted));
+    const parsed = parseArgs(own, dashboardArgs);
+    if (parsed.host !== undefined) {
+      const forwarded = own.filter(
+        (a, i) => a !== "--host" && own[i - 1] !== "--host" && !a.startsWith("--host="),
+      );
+      rawArgs.splice(
+        0,
+        rawArgs.length,
+        ...forwarded,
+        "--host",
+        String(parsed.host),
+        ...(dashdash < 0 ? [] : argv.slice(dashdash)),
+      );
+    }
     await runCommand(main, { rawArgs });
     return Number(process.exitCode ?? EXIT.ok);
   } catch (e) {

package/src/domain/host.ts

@@ -0,0 +1,17 @@
+export type OrchestrationHost = "claude-code" | "codex" | "unknown";
+export type KnownHost = Exclude<OrchestrationHost, "unknown">;
+export interface HostSessionRef {
+  host: KnownHost;
+  sessionId: string;
+  hostSessionId: string | null;
+  name: string | null;
+}
+export interface HostContext {
+  host: OrchestrationHost;
+  session: HostSessionRef | null;
+  conflict: string | null;
+}
+export function sessionKey(s: Pick<HostSessionRef, "host" | "sessionId">): string {
+  // a Codex thread is a UUID, whatever its casing: an owner stored before normalization still matches
+  return JSON.stringify([s.host, s.host === "codex" ? s.sessionId.toLowerCase() : s.sessionId]);
+}

package/src/domain/notice.ts

@@ -9,6 +9,7 @@ export type NoticePriority = "later" | "next";
 /** One role's news: it finished (`record`), or an event while it runs (`stall`). */
 export interface Notice {
   kind: "finished" | "stalled";
+  eventId: string;
   runId: string;
   runTitle: string;
   dispatchId: string;
@@ -62,9 +63,11 @@ const neutral = (s: string) => s.replace(/(cross)-(session)-(message)/gi, "$1 $2
 
 function block(n: Notice): string {
   const call = `run: "${n.runId}", name: "${n.name}"`;
-  if (n.kind === "stalled") return `${noticeHeader(n)}\nPeek: peek(${call})`;
+  if (n.kind === "stalled") return `${noticeHeader(n)}\nPeek: peek(${call})\nEvent: ${n.eventId}`;
   const reply = capNoticeReply(n.reply);
-  return [noticeHeader(n), ...(reply ? [reply] : []), `Record: result(${call})`].join("\n");
+  return [noticeHeader(n), ...(reply ? [reply] : []), `Record: result(${call})`, `Event: ${n.eventId}`].join(
+    "\n",
+  );
 }
 
 /** The preview line of a message that carries several roles: `catherd · <title> · 3 roles finished: …`. */

package/src/domain/profile-rules.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "./host.ts";
 import {
   type Catalog,
   type Dim,
@@ -145,6 +146,7 @@ export function validateProfile(
   c: Catalog,
   backends: readonly string[],
   doc?: ProfileDoc,
+  host: OrchestrationHost = "unknown",
 ): Validation {
   const errors: Issue[] = [];
   const warnings: Issue[] = [];
@@ -171,6 +173,8 @@ export function validateProfile(
       });
     if (!rc.enabled) continue;
     for (const rung of rc.rungs) {
+      const native = nativeClaudeIssue(rung, host, `${at}.rungs`);
+      if (native) errors.push(native);
       const r = tryParseRung(rung);
       if (!r) {
         errors.push({
@@ -274,6 +278,8 @@ export function validateProfile(
   });
   for (const [from, to] of Object.entries(p.failover)) {
     const at = `failover.${from}`;
+    const native = ladders.has(from) ? nativeClaudeIssue(to, host, at) : null;
+    if (native) errors.push(native);
     const a = tryParseRung(from);
     const b = tryParseRung(to);
     if (!a || !b) {
@@ -327,3 +333,14 @@ export function validateProfile(
     warnings.push({ path: x.path, message: standInMessage(x), fix: SUGGEST_FIX(x.rungs[0] as string) });
   return { errors, warnings };
 }
+
+export function nativeClaudeIssue(rung: string, host: OrchestrationHost, path: string): Issue | null {
+  const r = tryParseRung(rung);
+  return host !== "claude-code" && r?.backend === "claude"
+    ? {
+        path,
+        message: `${rung}: native Claude subagents require the claude-code orchestration host`,
+        fix: `use claude-code:${r.model}#${r.effort} for headless execution, or --host claude-code`,
+      }
+    : null;
+}

package/src/domain/profile.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "./host.ts";
 import { z } from "zod";
 import type { Budget } from "./budget.ts";
 import { BILLING_KEYS, type BillingKey } from "./catalog.ts";
@@ -229,7 +230,7 @@ export const PAIRED_FAILOVER: Record<string, string> = Object.fromEntries(
 /** The five billing keys spec §7.1 writes out; cursor and grok arrive with their backends. */
 const WRITTEN_BILLING: BillingKey[] = ["codex", "claude", "claude-code", "opencode-go", "opencode"];
 
-/** The full default profile document, every field written out: what `init` and `profile new` save. */
+/** Stored defaults for init/new; architect/verifier rungs resolve from the current host. */
 export function defaultProfileDoc(name = "default"): ProfileDoc {
   return {
     schema: PROFILE_SCHEMA,
@@ -237,7 +238,7 @@ export function defaultProfileDoc(name = "default"): ProfileDoc {
     objective: "cost",
     jev: { use: "auto" },
     billing: Object.fromEntries(WRITTEN_BILLING.map((k) => [k, DEFAULT_BILLING[k]])),
-    roles: structuredClone(BUILTIN_ROLES),
+    roles: hostDefaultsDoc({ schema: PROFILE_SCHEMA, roles: structuredClone(BUILTIN_ROLES) }).roles,
     harness: {
       codex: { isolated: false },
       "claude-code": { isolated: false },
@@ -252,12 +253,38 @@ export function defaultProfileDoc(name = "default"): ProfileDoc {
   };
 }
 
-/** Spec §7.1: every field a document leaves out takes its default; a missing role takes the built-in one. */
-export function resolveProfile(doc: ProfileDoc, name: string): Profile {
+/** Remove only the four architect/verifier execution choices, preserving other stored fields. */
+export function hostDefaultsDoc(doc: ProfileDoc): ProfileDoc {
+  const next = structuredClone(doc);
+  for (const role of ["architect", "verifier"] as const) {
+    const r = next.roles?.[role];
+    if (r) {
+      delete r.rungs;
+      delete r.defaultRung;
+    }
+  }
+  return next;
+}
+
+/** Resolve omitted role execution choices from the explicit orchestration host. */
+export function resolveProfile(doc: ProfileDoc, name: string, host: OrchestrationHost): Profile {
   const roles = {} as Record<Role, RoleConfig>;
   for (const role of ROLES) {
     const d = doc.roles?.[role];
     const b = BUILTIN_ROLES[role];
+    let omitted = b.rungs;
+    if ((role === "architect" || role === "verifier") && d?.rungs === undefined) {
+      if (host === "unknown" && (d?.enabled ?? b.enabled))
+        throw new CatherdError("E_CONFIG_INVALID", `roles.${role}.rungs needs an orchestration host`, {
+          fix: "pass --host codex or --host claude-code, or set explicit role rungs",
+        });
+      omitted =
+        host === "codex"
+          ? [`codex:gpt-6.1-sol#${role === "architect" ? "high" : "low"}`]
+          : host === "unknown"
+            ? []
+            : b.rungs;
+    }
     // a role that lists its own rungs never inherits the built-in default rung, which may not be among them
     const defaultRung = d?.defaultRung ?? (d?.rungs === undefined ? b.defaultRung : undefined);
     roles[role] = {
@@ -268,7 +295,7 @@ export function resolveProfile(doc: ProfileDoc, name: string): Profile {
           : known(ACCESS, d.access)
             ? d.access
             : STORED_FALLBACK.access,
-      rungs: [...(d?.rungs ?? b.rungs)],
+      rungs: [...(d?.rungs ?? omitted)],
       ...(defaultRung ? { defaultRung } : {}),
       ...(d?.network === false ? { network: false as const } : {}),
     };

package/src/domain/record.ts

@@ -75,6 +75,7 @@ export const RunRecordSchema = z.looseObject({
   replyPath: z.string(),
   /** the Claude Code session that dispatched it, copied from admit.json (spec §3.3); absent before 1.1 */
   sessionId: z.string().optional(),
+  host: z.enum(["claude-code", "codex"]).optional(),
 });
 export type RunRecord = z.infer<typeof RunRecordSchema>;
 

package/src/entry/catalog-command.ts

@@ -1,3 +1,4 @@
+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";
@@ -194,6 +195,7 @@ const treatLike = defineCommand({
       "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,
@@ -228,14 +230,14 @@ const treatLike = defineCommand({
         return;
       }
       if (args.clear !== undefined) {
-        const r = await clearTreatLike(args.clear);
+        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();
+        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(

package/src/entry/deps.ts

@@ -1,3 +1,4 @@
+import type { HostContext } from "../domain/host.ts";
 import { readSessionEnv } from "../infra/claude-session.ts";
 import { VERSION } from "../infra/version.ts";
 import type { Deps } from "../services/ports.ts";
@@ -5,13 +6,15 @@ import { profileService } from "../services/profile-service.ts";
 import { routingService } from "../services/routing-service.ts";
 
 /** The services every entry point (MCP server, CLI commands) runs on. */
-export function defaultDeps(): Deps {
-  return {
-    profiles: profileService(),
+export function defaultDeps(host: HostContext = { host: "unknown", session: null, conflict: null }): Deps {
+  const deps: Deps = {
+    host,
+    profiles: profileService(() => deps.host),
     routing: routingService(),
     version: VERSION,
     pollMs: 250,
     session: readSessionEnv(process.env),
     now: Date.now,
   };
+  return deps;
 }

package/src/entry/doctor-command.ts

@@ -1,7 +1,8 @@
+import { gitToplevel } from "../infra/git.ts";
+import { HOST_ARG, terminalHost } from "./host-arg.ts";
 import { defineCommand } from "citty";
 import { VERSION } from "../infra/version.ts";
 import { type DoctorReport, doctor } from "../services/doctor.ts";
-import { probePush } from "../services/doctor-push.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";
@@ -34,15 +35,23 @@ export const doctorCommand = defineCommand({
     description: "Readiness report: Bun, backends, Jev, the plugin, agents, the MCP server, locks",
   },
   args: {
+    ...HOST_ARG,
     ...JSON_ARG,
+    "test-push": {
+      type: "boolean",
+      description:
+        "send one labeled smoke to the validated original session (receipt does not prove processing)",
+    },
     plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
   },
   async run({ args }) {
     const r = await doctor({
+      host: terminalHost(args.host),
+      repo: await gitToplevel(process.cwd()),
       bunVersion: Bun.version,
       version: VERSION,
       handshake: () => mcpHandshake(),
-      push: () => probePush(),
+      testPush: args["test-push"] === true,
     });
     if (args.json) printJson(r);
     else for (const l of formatReport(r, args.plain === true)) console.log(l);

package/src/entry/host-arg.ts

@@ -0,0 +1,28 @@
+import { CatherdError } from "../domain/errors.ts";
+import type { HostContext } from "../domain/host.ts";
+import { resolveHost } from "../infra/host-context.ts";
+
+export const HOST_ARG = {
+  host: {
+    type: "enum" as const,
+    options: ["auto", "codex", "claude-code"],
+    description: "orchestration host (auto uses session evidence)",
+  },
+};
+
+export function terminalHost(value: string | undefined, env = process.env): HostContext {
+  if (value === undefined || value === "auto") return resolveHost({ env });
+  if (value !== "codex" && value !== "claude-code")
+    throw new CatherdError("E_INPUT_INVALID", `unknown host ${value}`, {
+      fix: "use --host auto, codex or claude-code",
+    });
+  const resolved = resolveHost({ env, terminalHost: value });
+  if (resolved.conflict) return resolved;
+  if (resolved.host !== value)
+    return {
+      host: "unknown",
+      session: null,
+      conflict: "Terminal host and launcher session evidence disagree; remove the other host’s environment",
+    };
+  return { ...resolved, session: null };
+}

package/src/entry/init-command.ts

@@ -1,3 +1,5 @@
+import { gitToplevel } from "../infra/git.ts";
+import { HOST_ARG, terminalHost } from "./host-arg.ts";
 import { defineCommand } from "citty";
 import { assertProfileName } from "../domain/profile.ts";
 import { errorMessage, isCatherdError } from "../domain/errors.ts";
@@ -11,6 +13,7 @@ import { type SyncReport, syncSources } from "../services/source-sync.ts";
 import { reinstallCommand } from "../services/doctor-checks.ts";
 import { ensureGlobal, type GlobalInstallDeps, realGlobalInstall } from "../services/global-install.ts";
 import { hasProfileFile, type InitResult, initSetup, moveLegacy } from "../services/setup.ts";
+import { activeName } from "../services/profile-store.ts";
 import { formatRefreshed, syncLines } from "./catalog-command.ts";
 import { mark as markOf } from "./cli-kit.ts";
 import { formatReport } from "./doctor-command.ts";
@@ -195,6 +198,7 @@ export const initCommand = defineCommand({
       "First run: the global catherd command, the Jev key, the Artificial Analysis key, a sync of the public model sources, the default profile, its agents, and a readiness report. Piped, it reads the answers from stdin one per line, a line per question even when this machine skips it (the Jev key, the Artificial Analysis key, the profile, whether to replace it), and waits for stdin to close; --no-input asks nothing",
   },
   args: {
+    ...HOST_ARG,
     // citty reads --no-input as input: false, whatever the flag is named; naming it no-input shows it as is
     "no-input": { type: "boolean", description: "ask nothing: keep what exists, else write the defaults" },
     // read as global: false, like no-input above
@@ -202,7 +206,10 @@ export const initCommand = defineCommand({
       type: "boolean",
       description: "do not install the global catherd command (bun add -g catherd-cli@<this version>)",
     },
-    profile: { type: "string", description: "the profile to set up and make active (default: default)" },
+    profile: {
+      type: "string",
+      description: "the profile to set up and make active (default: current repo profile)",
+    },
     plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
   },
   async run({ args }) {
@@ -218,19 +225,21 @@ export const initCommand = defineCommand({
       await jevStep(ask, {}, plain);
       await aaStep(ask, {}, plain);
       await syncStep({ plain });
-      if (args.profile !== undefined) ask?.skip?.();
-      const name = assertProfileName(
-        args.profile ?? (ask ? (await ask.ask("Profile to set up [default]: ")) || "default" : "default"),
-      );
+      const repo = await gitToplevel(process.cwd());
       // 0.x files go first, so a legacy profile about to be moved aside is never asked about
       const moved = moveLegacy();
+      const current = activeName(repo);
+      if (args.profile !== undefined) ask?.skip?.();
+      const selected =
+        args.profile ?? (ask ? (await ask.ask(`Profile to set up [${current}]: `)) || undefined : undefined);
+      const name = assertProfileName(selected ?? current);
       const exists = hasProfileFile(name);
       if (!exists) ask?.skip?.();
       const overwrite =
         ask !== null &&
         exists &&
         /^y(es)?$/i.test(await ask.ask(`Replace profile ${name} with the default profile? [y/N] `));
-      const r = await initSetup({ profile: name, overwrite });
+      const r = await initSetup({ profile: selected, repo, overwrite, host: terminalHost(args.host) });
       for (const f of [...moved, ...r.moved]) console.log(`${mark("ok")} moved a 0.x file aside: ${f}`);
       for (const l of profileLines(r, plain)) console.log(l);
       if (r.synced?.linked.length)
@@ -238,13 +247,15 @@ export const initCommand = defineCommand({
       for (const x of r.refreshed) console.log(formatRefreshed(x, plain));
       console.log("");
       const report = await doctor({
+        host: terminalHost(args.host),
+        repo,
         bunVersion: Bun.version,
         version: VERSION,
         handshake: () => mcpHandshake(),
       });
       for (const l of formatReport(report, plain)) console.log(l);
       console.log("");
-      for (const l of PLUGIN_STEPS) console.log(l);
+      for (const l of terminalHost(args.host).host === "claude-code" ? PLUGIN_STEPS : []) console.log(l);
     } finally {
       ask?.close();
     }