catherd-cli 1.2.1 → 1.4.0

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)",
@@ -47,6 +49,7 @@ export const main: Command = defineCommand({
     profile: () => import("./entry/profile-command.ts").then((m) => m.profileCommand),
     doctor: () => import("./entry/doctor-command.ts").then((m) => m.doctorCommand),
     catalog: () => import("./entry/catalog-command.ts").then((m) => m.catalogCommand),
+    knowledge: () => import("./entry/knowledge-command.ts").then((m) => m.knowledgeCommand),
     lock: () => import("./entry/lock-command.ts").then((m) => m.lockCommand),
     "capture-fixtures": () =>
       import("./entry/capture-fixtures-command.ts").then((m) => m.captureFixturesCommand),
@@ -55,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);
   },
 });
@@ -68,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];
 }
@@ -122,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/catalog.ts

@@ -40,11 +40,20 @@ export const BILLING_KEYS = [
   "opencode",
   "cursor",
   "grok",
+  "antigravity",
 ] as const;
 export type BillingKey = (typeof BILLING_KEYS)[number];
 
 /** The keys a family's `on` map uses; the native `claude` pseudo-backend runs claude-code's model ids. */
-const MODEL_KEYS = ["codex", "claude-code", "opencode-go", "opencode", "cursor", "grok"] as const;
+const MODEL_KEYS = [
+  "codex",
+  "claude-code",
+  "opencode-go",
+  "opencode",
+  "cursor",
+  "grok",
+  "antigravity",
+] as const;
 type ModelKey = (typeof MODEL_KEYS)[number];
 
 export function billingKeyOf(r: Rung): BillingKey {

package/src/domain/cost.ts

@@ -13,6 +13,7 @@ export const DEFAULT_BILLING: Record<BillingKey, BillingMode> = {
   opencode: "metered",
   cursor: "metered",
   grok: "metered",
+  antigravity: "metered",
 };
 
 /**

package/src/domain/errors.ts

@@ -5,6 +5,7 @@ export type ErrorCode =
   | "E_BACKEND_MISSING"
   | "E_BACKEND_TOO_OLD"
   | "E_BACKEND_NOT_LOGGED_IN"
+  | "E_BACKEND_CANNOT_RUN"
   | "E_BACKEND_MODEL_UNKNOWN"
   | "E_RUN_NOT_FOUND"
   | "E_RUN_CORRUPT"

package/src/domain/failover.ts

@@ -113,7 +113,8 @@ function effortGap(a: string, b: string): number {
 const BACKEND_OF_KEY: Record<string, string> = { "opencode-go": "opencode" };
 
 /**
- * Every rung the catalog knows how to name: each shipped family's model on each backend at each effort,
+ * Every rung the catalog knows how to name: each shipped family's model on each backend at each effort (at
+ * `#default` when it has none),
  * each listed model at each effort, and each treat-like whose model is an opencode id (`opencode-go/…`,
  * `opencode/…`), such as the shipped Kimi K3 stand-in. Sorted, without duplicates.
  */
@@ -122,7 +123,9 @@ export function catalogRungs(c: Catalog): string[] {
   for (const f of c.families)
     for (const [key, m] of Object.entries(f.on)) {
       if (!m) continue;
-      for (const e of m.efforts) out.add(`${BACKEND_OF_KEY[key] ?? key}:${m.id}#${e}`);
+      // a model with no effort has one rung, #default (Claude Code's Haiku, Cursor's Composer; spec 1.3 §7.1)
+      for (const e of m.efforts.length ? m.efforts : ["default"])
+        out.add(`${BACKEND_OF_KEY[key] ?? key}:${m.id}#${e}`);
     }
   for (const [backend, l] of Object.entries(c.listed))
     for (const m of l.models) for (const e of m.efforts) out.add(`${backend}:${m.id}#${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/ids.ts

@@ -11,8 +11,8 @@ export function assertId(kind: string, value: string): string {
   return value;
 }
 
-/** The backends that run as a process through a `BackendAdapter` (cursor and grok: plan 8). */
-export const ADAPTER_IDS = ["codex", "claude-code", "opencode", "cursor", "grok"] as const;
+/** The backends that run as a process through a `BackendAdapter` (spec 1.3: cursor, grok and antigravity). */
+export const ADAPTER_IDS = ["codex", "claude-code", "opencode", "cursor", "grok", "antigravity"] as const;
 
 /** `claude` is the native Claude Code subagent path (no process); the rest are adapters. */
 const RUNG_BACKENDS = [...ADAPTER_IDS, "claude"] as const;

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";
@@ -169,10 +170,67 @@ export const DEFAULT_FAILOVER: Record<string, string> = {
   [SOL("medium")]: "opencode:opencode-go/kimi-k3#max",
 };
 
+/**
+ * Cursor's live slug and efforts for a paired family (`cursor-agent models`, 2026-10-01). Empty efforts means the
+ * bare slug.
+ */
+const CURSOR_PAIR: Record<string, { id: string; efforts: readonly string[] }> = {
+  "grok-4.7": { id: "grok-4.7", efforts: ["low", "medium", "high", "xhigh"] },
+  "grok-4.6": { id: "cursor-grok-4.6", efforts: ["low", "medium", "high", "xhigh"] },
+  "grok-4.5": { id: "cursor-grok-4.5", efforts: ["low", "medium", "high"] },
+  "gemini-3.8-flash": { id: "gemini-3.8-flash", efforts: ["low", "medium", "high"] },
+  "gemini-3.7-flash": { id: "gemini-3.7-flash", efforts: ["low", "medium", "high"] },
+  "gemini-3.6-flash": { id: "gemini-3.6-flash", efforts: ["minimal", "low", "medium", "high"] },
+  "gemini-3.1-pro": { id: "gemini-3.1-pro", efforts: [] },
+};
+
+/** The Cursor effort a paired rung can actually run: the same one when listed, else `high`, else the bare slug. */
+function cursorPairEffort(model: string, effort: string): string {
+  const list = CURSOR_PAIR[model]?.efforts ?? [];
+  if (list.length === 0) return "default";
+  if (effort !== "default" && list.includes(effort)) return effort;
+  return list.includes("high") ? "high" : (list[0] as string);
+}
+
+/**
+ * Spec 1.3 §7.3: the same model through two backends bills two pools, so each stands in for the other on a
+ * limit, at the same effort where both list it. Otherwise the stand-in runs at `high`: Grok 4.5 `xhigh` at Cursor
+ * `high`, Cursor's Gemini 3.6 `minimal` at agy `high`; Gemini 3.1 Pro's bare Cursor slug pairs with agy `high`.
+ * Grok and Gemini are paired with Cursor. Consulted after the profile's own failover and never written into a
+ * profile, where a pair whose rung is on no ladder would warn "never runs"; never a stand-in for a shipped Codex,
+ * Claude or opencode rung.
+ */
+export const PAIRED_FAILOVER: Record<string, string> = Object.fromEntries(
+  (
+    [
+      ["grok", ["grok-4.7", "grok-4.6", "grok-4.5"], ["low", "medium", "high", "xhigh"]],
+      [
+        "antigravity",
+        ["gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash"],
+        ["low", "medium", "high"],
+      ],
+      ["antigravity", ["gemini-3.1-pro"], ["low", "high"]],
+    ] as const
+  ).flatMap(([backend, models, efforts]) =>
+    models.flatMap((m) => {
+      const cursor = CURSOR_PAIR[m] as { id: string; efforts: readonly string[] };
+      const back = ["default", ...efforts].map(
+        (e) => [`${backend}:${m}#${e}`, `cursor:${cursor.id}#${cursorPairEffort(m, e)}`] as const,
+      );
+      // `#default` too, as on the other side: a Cursor rung with no effort flag fails over the same way
+      const fore = [...new Set(["default", ...cursor.efforts])].map((e) => {
+        const there = e !== "default" && (efforts as readonly string[]).includes(e) ? e : "high";
+        return [`cursor:${cursor.id}#${e}`, `${backend}:${m}#${there}`] as const;
+      });
+      return [...back, ...fore];
+    }),
+  ),
+);
+
 /** 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,
@@ -180,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 },
@@ -195,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] = {
@@ -211,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

@@ -68,11 +68,14 @@ export const RunRecordSchema = z.looseObject({
   threadHeavy: z.boolean(),
   access: z.enum(ACCESS),
   isolated: z.boolean(),
+  /** the role's network grant (1.1 §5) it ran under, copied from admit.json; absent before 1.3 */
+  network: z.boolean().optional(),
   images: z.array(z.string()),
   error: z.object({ code: z.string(), message: z.string() }).nullable(),
   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/domain/util.ts

@@ -5,6 +5,9 @@ export const slug = (s: string): string =>
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-|-$/g, "");
 
+/** One table cell or one line of text: `|` and newlines become `/`, whitespace runs one space, trimmed. */
+export const cell = (s: string): string => s.replace(/[|\n]/g, "/").replace(/\s+/g, " ").trim();
+
 /** The middle value, or the mean of the two middle values for an even count; null when there are none. */
 export function median(xs: readonly number[]): number | null {
   if (xs.length === 0) return null;

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();
     }