catherd-cli 1.3.0 → 1.4.0

package/src/infra/codex-queue.ts

@@ -0,0 +1,165 @@
+import type { HostSessionRef } from "../domain/host.ts";
+import { runCli } from "./cli.ts";
+import { scrubSecrets } from "./env.ts";
+
+export interface QueueCapability {
+  cli: boolean;
+  server: "supported" | "unsupported" | "unverified";
+  reason: string | null;
+  /** false when nothing was probed yet: `cli` then says nothing about the CLI */
+  checked?: false;
+}
+export type QueueSendResult =
+  | { outcome: "accepted"; msgId: string }
+  | { outcome: "not-submitted"; reason: string }
+  | { outcome: "ambiguous"; reason: string };
+
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const uuid = new RegExp(`^${UUID}$`, "i");
+const receipt = new RegExp(`^Queued message (${UUID}) for thread (${UUID})\\.$`);
+const TIMEOUT_MS = 10000;
+
+export async function queueCapability(
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+): Promise<QueueCapability> {
+  try {
+    const help = await run("codex", ["queue", "--help"], {
+      timeoutMs: TIMEOUT_MS,
+      env: scrubSecrets({ ...process.env, ...env }),
+    });
+    if (
+      !help?.ok ||
+      !/\bqueue\b/.test(help.out) ||
+      !["--thread", "--message", "--remote"].every((flag) => new RegExp(`${flag}\\s`).test(help.out))
+    )
+      return {
+        cli: false,
+        server: "unverified",
+        reason: "Native codex queue with --remote is unavailable; update Codex and use peek/result.",
+      };
+    return {
+      cli: true,
+      server: "unverified",
+      reason: "Native server queue method enumeration is unavailable; help proves CLI support only.",
+    };
+  } catch {
+    return {
+      cli: false,
+      server: "unverified",
+      reason: "Could not inspect native codex queue; use peek/result.",
+    };
+  }
+}
+
+const PROBE_TTL_MS = 60_000;
+let known: { at: number; capability: QueueCapability } | null = null;
+let probing: Promise<void> | null = null;
+
+/** The capability a one-shot command reports without probing: it never waits, and doctor checks it. */
+export const UNCHECKED_QUEUE: QueueCapability = {
+  cli: false,
+  server: "unverified",
+  reason: "Native codex queue is not checked by this command; catherd doctor checks it.",
+  checked: false,
+};
+
+/**
+ * The last known queue capability, without waiting on the Codex CLI: peek and status never wait (spec §3.7).
+ * A missing or stale answer starts one probe in the background; until it lands the capability reads unchecked.
+ */
+export function knownQueueCapability(
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+  now: number = Date.now(),
+): QueueCapability {
+  if (!probing && (!known || now - known.at >= PROBE_TTL_MS))
+    probing = queueCapability(env, run)
+      .then((capability) => {
+        known = { at: now, capability };
+      })
+      .finally(() => {
+        probing = null;
+      });
+  return (
+    known?.capability ?? {
+      cli: false,
+      server: "unverified",
+      reason: "Native codex queue is being checked; peek again for the result.",
+      checked: false,
+    }
+  );
+}
+
+/** Settles the background probe knownQueueCapability started, if any (a test seam). */
+export async function queueProbeSettled(): Promise<void> {
+  await probing;
+}
+
+/** Settles any background probe and forgets its answer (a test seam). */
+export async function resetQueueProbe(): Promise<void> {
+  await probing;
+  known = null;
+}
+
+export async function sendToCodexQueue(
+  target: HostSessionRef,
+  content: string,
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+): Promise<QueueSendResult> {
+  if (target.host !== "codex" || target.sessionId.length !== 36 || !uuid.test(target.sessionId))
+    return {
+      outcome: "not-submitted",
+      reason: "Queue requires a validated original Codex thread UUID; use peek/result.",
+    };
+  if (!content.trim()) return { outcome: "not-submitted", reason: "Queue message is empty." };
+  const capability = await queueCapability(env, run);
+  if (!capability.cli || capability.server === "unsupported")
+    return {
+      outcome: "not-submitted",
+      reason: capability.reason ?? "Native queue is unavailable; use peek/result.",
+    };
+  try {
+    const args = ["queue", "--remote", "unix://", "--thread", target.sessionId, "--message", content];
+    const result = await run("codex", args, {
+      timeoutMs: TIMEOUT_MS,
+      env: scrubSecrets({ ...process.env, ...env }),
+      logArgs: [...args.slice(0, -1), "[redacted]"],
+    });
+    if (result === null)
+      return { outcome: "not-submitted", reason: "Codex executable is unavailable; use peek/result." };
+    const match = result.ok ? receipt.exec(result.out.trim()) : null;
+    if (match && match[2]?.toLowerCase() === target.sessionId.toLowerCase())
+      return { outcome: "accepted", msgId: match[1]! };
+    if (
+      !result.ok &&
+      !result.out.trim() &&
+      (/^Error: the remote app server does not support thread\/queue\/add; update or restart the remote app server(?:\n|$)/.test(
+        result.err,
+      ) ||
+        /^error: (?:unrecognized subcommand 'queue'|unexpected argument '--remote' found)(?:\n|$)/.test(
+          result.err,
+        ) ||
+        /^Error: failed to connect to remote app server at `unix:\/\/[^`\n]+`: [^\n]+(?:\n|$)/.test(
+          result.err,
+        ))
+    )
+      return {
+        outcome: "not-submitted",
+        reason:
+          "Native queue refused before submission; check CLI/server support and the existing native endpoint, then use peek/result.",
+      };
+    return {
+      outcome: "ambiguous",
+      reason:
+        "Native queue invocation has no verified receipt; use peek/result. Retrying may duplicate input.",
+    };
+  } catch {
+    return {
+      outcome: "ambiguous",
+      reason:
+        "Native queue invocation failed without a verified receipt; use peek/result. Retrying may duplicate input.",
+    };
+  }
+}

package/src/infra/delivery.ts

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { z } from "zod";
+import { CatherdError } from "../domain/errors.ts";
+import { sessionKey, type HostSessionRef } from "../domain/host.ts";
+import { awaitsCollect, dispatchPaths } from "./dispatch-dir.ts";
+import { withFileLockSync } from "./filelock.ts";
+import { readVersioned, writeJsonAtomic } from "./store.ts";
+
+const AttemptSchema = z
+  .looseObject({
+    attemptId: z.string().min(1),
+    target: z.object({
+      host: z.enum(["codex", "claude-code"]),
+      sessionId: z.string().min(1),
+      hostSessionId: z.string().nullable(),
+      name: z.string().nullable(),
+    }),
+    eventIds: z.array(z.string().min(1)).min(1),
+    at: z.iso.datetime(),
+    status: z.enum(["submitting", "accepted", "ambiguous", "failed"]),
+    msgId: z.string().nullable(),
+    reason: z.string().nullable(),
+  })
+  .refine((a) => a.status !== "accepted" || Boolean(a.msgId?.trim()), "accepted attempt needs a receipt");
+const DeliverySchema = z.looseObject({ schema: z.literal(1), attempts: z.array(AttemptSchema) });
+export type DeliveryAttempt = z.infer<typeof AttemptSchema>;
+export type DeliveryState = "pending" | "enqueue-accepted" | "ambiguous" | "collected";
+
+export function readDelivery(dir: string): DeliveryAttempt[] {
+  const file = dispatchPaths(dir).delivery;
+  return existsSync(file)
+    ? readVersioned(file, DeliverySchema, 1, {
+        fix: "Use peek/result; delivery evidence is unreadable and retry may duplicate input.",
+      }).attempts
+    : [];
+}
+
+/** Short shared lock: distinct stalled/finished event claims must not lose each other's updates. */
+export function writeDeliveryAttempt(dir: string, attempt: DeliveryAttempt): void {
+  const parsed = AttemptSchema.safeParse(attempt);
+  if (!parsed.success) throw new CatherdError("E_INPUT_INVALID", "Invalid delivery attempt");
+  const file = dispatchPaths(dir).delivery;
+  withFileLockSync(file, () => {
+    const document = existsSync(file)
+      ? readVersioned(file, DeliverySchema, 1)
+      : { schema: 1 as const, attempts: [] as DeliveryAttempt[] };
+    const prior = document.attempts.findIndex((a) => a.attemptId === attempt.attemptId);
+    if (prior < 0) document.attempts.push(parsed.data);
+    else {
+      const sent = document.attempts[prior]!;
+      if (
+        JSON.stringify(sent.target) !== JSON.stringify(parsed.data.target) ||
+        JSON.stringify(sent.eventIds) !== JSON.stringify(attempt.eventIds) ||
+        sent.at !== attempt.at
+      )
+        throw new CatherdError(
+          "E_INPUT_INVALID",
+          "Delivery target, events and submission time are immutable",
+        );
+      document.attempts[prior] = { ...sent, ...parsed.data };
+    }
+    writeJsonAtomic(file, document);
+  });
+}
+
+export function deliveryState(dir: string, target: HostSessionRef, eventId: string): DeliveryState {
+  try {
+    const event = JSON.parse(eventId) as unknown;
+    if (Array.isArray(event) && event[2] === "finished" && !awaitsCollect(dir)) return "collected";
+  } catch {
+    /* Invalid event text cannot imply collection. */
+  }
+  try {
+    const attempts = readDelivery(dir).filter(
+      (a) => sessionKey(a.target) === sessionKey(target) && a.eventIds.includes(eventId),
+    );
+    if (attempts.some((a) => a.status === "accepted")) return "enqueue-accepted";
+    if (attempts.some((a) => a.status === "submitting" || a.status === "ambiguous")) return "ambiguous";
+    return "pending";
+  } catch {
+    return "ambiguous";
+  }
+}

package/src/infra/dispatch-dir.ts

@@ -40,6 +40,7 @@ export function dispatchPaths(dir: string) {
     failover: join(dir, "failover.json"),
     /** the message that announced this dispatch's record to its session, once sent (plan 10) */
     notified: join(dir, "notified.json"),
+    delivery: join(dir, "delivery.json"),
     /** written once by the supervisor when the worker went quiet for half its idle timeout, not busy (spec §3.6) */
     stall: join(dir, "stall.json"),
     /** the message that announced the stall, once sent */

package/src/infra/env.ts

@@ -5,6 +5,9 @@
  * runs, a headless claude-code worker would inherit it): no process catherd starts gets them.
  */
 const SECRET_ENV = new Set([
+  "CODEX_THREAD_ID",
+  "CODEX_SESSION_ID",
+  "CATHERD_ORCHESTRATION_HOST",
   "TYPESAFE_API_KEY",
   // spec 1.2 §9: the user's Artificial Analysis key reads scores for catherd alone
   "ARTIFICIAL_ANALYSIS_API_KEY",
@@ -39,7 +42,7 @@ export function workerEnv(
   overrides: Record<string, string>,
   cwd: string,
 ): Record<string, string> {
-  return { ...scrubSecrets(base), ...overrides, PWD: cwd };
+  return { ...scrubSecrets({ ...base, ...overrides }), PWD: cwd };
 }
 
 /** What a preflight check may see; everything else, credentials included, stays out (spec §4.7). */

package/src/infra/host-context.ts

@@ -0,0 +1,58 @@
+import type { HostContext, KnownHost, OrchestrationHost } from "../domain/host.ts";
+import { readSessionEnv, sessionFileFor } from "./claude-session.ts";
+
+export function resolveHost(e: {
+  clientName?: string;
+  env: Record<string, string | undefined>;
+  terminalHost?: OrchestrationHost;
+}): HostContext {
+  const conflict = (message: string): HostContext => ({ host: "unknown", session: null, conflict: message });
+  const hosts = new Set<KnownHost>();
+  const client = e.clientName;
+  if (client === "codex-mcp-client") hosts.add("codex");
+  if (client === "claude-code") hosts.add("claude-code");
+  const launcher = e.env.CATHERD_ORCHESTRATION_HOST;
+  if (launcher === "codex" || launcher === "claude-code") hosts.add(launcher);
+  const claude = readSessionEnv(e.env);
+  if (claude) hosts.add("claude-code");
+  // UUIDs are case-insensitive: one spelling, so the launcher's and a request's casing name the same thread
+  const thread = e.env.CODEX_THREAD_ID?.toLowerCase();
+  const session = e.env.CODEX_SESSION_ID?.toLowerCase();
+  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (thread !== undefined || session !== undefined) {
+    hosts.add("codex");
+    if ((thread !== undefined && !uuid.test(thread)) || (session !== undefined && !uuid.test(session)))
+      return conflict("Codex session IDs must be UUIDs; remove invalid CODEX_THREAD_ID / CODEX_SESSION_ID");
+    if (thread && session && thread !== session)
+      return conflict("CODEX_THREAD_ID and CODEX_SESSION_ID disagree; correct the launcher environment");
+  }
+  if (hosts.size > 1)
+    return conflict(
+      "Initialized client and launcher session evidence disagree; remove the other host's environment",
+    );
+  const host = [...hosts][0] ?? e.terminalHost ?? "unknown";
+  if (host === "codex")
+    return {
+      host,
+      session:
+        thread || session ? { host, sessionId: thread || session!, hostSessionId: null, name: null } : null,
+      conflict: null,
+    };
+  if (host === "claude-code" && claude) {
+    const file = sessionFileFor(claude);
+    const id = file?.sessionId ?? claude.sessionId;
+    return {
+      host,
+      session: id
+        ? {
+            host,
+            sessionId: id,
+            hostSessionId: file?.hostSessionId ?? claude.hostSessionId,
+            name: file?.name ?? null,
+          }
+        : null,
+      conflict: null,
+    };
+  }
+  return { host, session: null, conflict: null };
+}

package/src/infra/peer-inbox.ts

@@ -51,10 +51,12 @@ export function sendToInbox(
   const socketPath = target.socketPath;
   return new Promise<SendResult>((resolve) => {
     let settled = false;
+    // once the frame is being written a failure may still have delivered it: such a result carries its msg_id
+    let writing = false;
     const done = (r: SendResult) => {
       if (settled) return;
       settled = true;
-      resolve(r);
+      resolve(writing && r.outcome === "error" ? { ...r, msgId } : r);
     };
     let s: ReturnType<typeof createConnection>;
     try {
@@ -77,6 +79,7 @@ export function sendToInbox(
     });
     s.on("connect", () => {
       clearTimeout(timer);
+      writing = true;
       s.write(frameText(content, priority, target.token, msgId), (err) => {
         if (err) {
           s.destroy();

package/src/infra/supervisor.ts

@@ -1,3 +1,4 @@
+import { scrubSecrets } from "./env.ts";
 import type { Subprocess } from "bun";
 import { appendFileSync, closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
 import { z } from "zod";
@@ -139,7 +140,7 @@ async function superviseHeld(spec: SuperviseSpec, hooks: SuperviseHooks): Promis
     fds.push(stderr);
     child = Bun.spawn([spec.cmd, ...spec.args], {
       cwd: spec.cwd,
-      env: spec.env,
+      env: scrubSecrets(spec.env),
       stdin,
       stdout,
       stderr,
@@ -149,7 +150,7 @@ async function superviseHeld(spec: SuperviseSpec, hooks: SuperviseHooks): Promis
       backend: spec.backend,
       dispatch: spec.dispatchDir,
       argv: [spec.cmd, ...spec.args],
-      env: spec.env,
+      env: scrubSecrets(spec.env),
       cwd: spec.cwd,
       pid: child.pid,
     });

package/src/services/admission.ts

@@ -1,3 +1,4 @@
+import type { KnownHost } from "../domain/host.ts";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { BackendAdapter } from "../adapters/backend.ts";
@@ -45,6 +46,7 @@ export interface AdmitInput {
   failoverOf?: string;
   /** the dispatching session (spec §3.3); absent means the session this process serves */
   sessionId?: string | null;
+  host?: KnownHost;
 }
 
 /** Spec §3.3: SIGTERM, then SIGKILL this long after. */
@@ -205,7 +207,6 @@ export async function admit(
   });
 
   await finalizeFinished(run, deps.now(), onRecorded);
-  const sessionId = i.sessionId !== undefined ? i.sessionId : (currentSession(deps)?.sessionId ?? null);
   return withFileLock(runPaths(run.dir).admission, async () => {
     // A dispatch blocks until its record is written, not only while it runs: its finalizer diffs the
     // tree after the exit, so a later dispatch's writes must not land in between. A finished one here
@@ -245,6 +246,9 @@ export async function admit(
       throw new CatherdError("E_RUN_BUDGET", `the run budget is spent: ${formatBudget(budget)}`, {
         fix: "ask the user to raise profile.budget, or finish the run with what landed",
       });
+    const before = await statusSnapshot(run.meta.repo);
+    const session = currentSession(deps);
+    const sessionId = i.sessionId !== undefined ? i.sessionId : (session?.sessionId ?? null);
     const admitted: Admit = {
       schema: 1,
       runId: run.id,
@@ -265,8 +269,8 @@ export async function admit(
       cliVersion: probe.version,
       admittedAt: new Date(deps.now()).toISOString(),
       repo: run.meta.repo,
-      before: await statusSnapshot(run.meta.repo),
-      ...(sessionId ? { sessionId } : {}),
+      before,
+      ...(sessionId ? { sessionId, host: i.host ?? session?.host ?? "claude-code" } : {}),
     };
     ensurePrivateDir(dir);
     // spec 1.1 §6: every brief ends with its role's reply contract, failover stand-ins' included

package/src/services/agent-links.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "../domain/host.ts";
 import {
   existsSync,
   lstatSync,
@@ -44,10 +45,10 @@ export interface Planned {
   links: Map<string, string>;
 }
 
-export function plan(extra: string[] = []): Planned {
+export function plan(host: OrchestrationHost, extra: string[] = [], selected?: string[]): Planned {
   const files = new Map<string, AgentFile[]>();
-  for (const name of new Set([...linkedProfiles(), ...extra.filter(profileExists)]))
-    files.set(name, agentFiles(getProfile(name), VERSION));
+  for (const name of new Set(selected ?? [...linkedProfiles(), ...extra.filter(profileExists)]))
+    files.set(name, agentFiles(getProfile(name, host), VERSION));
   const links = new Map<string, string>();
   for (const name of linkedProfiles())
     for (const f of files.get(name) ?? [])
@@ -71,6 +72,27 @@ export interface Synced {
   newSessionNeededFor: string[];
 }
 
+export function pruneProfileAgents(name: string): Synced {
+  const dir = join(agentsRoot(), name);
+  const pruned: string[] = [];
+  const target = claudeAgentsDir();
+  if (existsSync(target))
+    for (const entry of readdirSync(target)) {
+      const link = join(target, entry);
+      if (isOurLink(link) && readlinkSync(link).startsWith(`${dir}${sep}`)) {
+        rmSync(link);
+        pruned.push(entry);
+      }
+    }
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  pruned.sort();
+  return {
+    linked: [],
+    pruned,
+    newSessionNeededFor: pruned.map((entry) => basename(entry, ".md")),
+  };
+}
+
 /**
  * Writes the planned agent files and links, prunes catherd's stale ones, and says what changed. The
  * ownership check runs before the first write, so no caller can replace a file catherd does not own.
@@ -122,8 +144,11 @@ export function apply(p: Planned, removed: string[] = []): Synced {
 }
 
 /** What `doctor` compares: each link that should exist, and whether it and its file are current. */
-export function agentLinkState(): { missing: string[]; stale: string[]; ok: string[] } {
-  const p = plan();
+export function agentLinkState(
+  host: OrchestrationHost,
+  selected?: string[],
+): { missing: string[]; stale: string[]; ok: string[] } {
+  const p = plan(host, [], selected);
   const out = { missing: [] as string[], stale: [] as string[], ok: [] as string[] };
   for (const [name, files] of p.files)
     for (const f of files) {

package/src/services/backends.ts

@@ -1,3 +1,5 @@
+import type { OrchestrationHost } from "../domain/host.ts";
+import { nativeClaudeIssue } from "../domain/profile-rules.ts";
 import type { BackendAdapter, Probe } from "../adapters/backend.ts";
 import { adapterFor } from "../adapters/registry.ts";
 import "../adapters/all.ts";
@@ -80,3 +82,8 @@ export function standInFor(failover: Record<string, string>, rung: string, repo?
   const byAdapter = adapterFor(r.backend)?.failoverFor?.(r, repo) ?? null;
   return byAdapter && formatRung(byAdapter);
 }
+
+export function assertNativeHost(rung: string, host: OrchestrationHost): void {
+  const issue = nativeClaudeIssue(rung, host, "rung");
+  if (issue) throw new CatherdError("E_CONFIG_INVALID", `${issue.message}; ${issue.fix}`, { fix: issue.fix });
+}

package/src/services/dispatch-service.ts

@@ -1,3 +1,4 @@
+import { assertNativeHost } from "./backends.ts";
 import { existsSync, readFileSync } from "node:fs";
 import { CatherdError, errorMessage, isCatherdError } from "../domain/errors.ts";
 import { assertId, parseRung } from "../domain/ids.ts";
@@ -34,7 +35,7 @@ import { finalizeDispatch, finalizingElsewhere, waitForFinish } from "./finalize
 import type { Deps } from "./ports.ts";
 import { route } from "./lane-service.ts";
 import { findRun, readRecords, readRoutes, type Run } from "./run-store.ts";
-import { claimRun, ownsRun } from "./sessions.ts";
+import { claimRun, ownsRun, runOwner } from "./sessions.ts";
 import { type NotesPatch, refreshState } from "./state.ts";
 
 export interface DispatchInput {
@@ -101,17 +102,21 @@ export interface Stalled {
 export const stallHooks = new Set<(s: Stalled) => void>();
 
 /** A watcher's poll: the first time the dispatch's stall.json is there, every stall hook hears of it. */
+/** A stall's quiet time; 0 when stall.json is being written or damaged, so one bad file never blocks a notice. */
+export function readStallQuietMs(dir: string): number {
+  try {
+    return Number(JSON.parse(readFileSync(dispatchPaths(dir).stall, "utf8")).quietMs) || 0;
+  } catch {
+    return 0;
+  }
+}
+
 export function stallPoll(run: Run, d: Dispatch): () => void {
   let seen = false;
   return () => {
     if (seen || !existsSync(dispatchPaths(d.dir).stall)) return;
     seen = true;
-    let quietMs = 0;
-    try {
-      quietMs = Number(JSON.parse(readFileSync(dispatchPaths(d.dir).stall, "utf8")).quietMs) || 0;
-    } catch {
-      // being written: the stall is reported without its length
-    }
+    const quietMs = readStallQuietMs(d.dir);
     for (const hook of stallHooks) {
       try {
         hook({ run, d, quietMs });
@@ -294,6 +299,8 @@ export async function dispatch(deps: Deps, i: DispatchInput): Promise<DispatchSt
       hints.push(`${i.rung} is not on ${i.lane}'s routed ladder: dispatched at ${routed.rung}`);
     }
   }
+  // the rung that runs, after routing: an off-ladder native rung routing replaced is never launched
+  assertNativeHost(rung, deps.host.host);
   const { d, specPath } = await admit(
     deps,
     run,
@@ -493,6 +500,8 @@ async function failover(deps: Deps, run: Run, d: Dispatch, limited: RunRecord):
   // else that stand-in never ran and is over (recorded as lost, or past its start grace): admit a new one
   const standIn = standInFor(deps.profiles.forRepo(run.meta.repo).failover, limited.rung, run.meta.repo);
   if (!standIn) return { hints, started: null, pause: paused };
+  // the stand-in answers to whoever owns the run now, which a claim from another host may have changed
+  assertNativeHost(standIn, runOwner(run)?.host ?? deps.host.host);
   if (parseRung(standIn).backend === "claude") {
     const agent = deps.profiles.agentFor(run.meta.repo, d.admit.role, standIn);
     return {
@@ -517,6 +526,7 @@ async function failover(deps: Deps, run: Run, d: Dispatch, limited: RunRecord):
       failoverOf: d.admit.dispatchId,
       // the stand-in answers to the session that dispatched the limited role, whoever fails it over
       sessionId: d.admit.sessionId ?? null,
+      host: d.admit.host,
     });
   } catch (e) {
     if (!isCatherdError(e)) throw e;

package/src/services/dispatches.ts

@@ -36,6 +36,7 @@ const AdmitSchema = z.looseObject({
   before: z.record(z.string(), z.string()),
   /** the Claude Code session that dispatched it (spec §3.3); absent on 1.0 dispatches and outside Claude Code */
   sessionId: z.string().optional(),
+  host: z.enum(["claude-code", "codex"]).optional(),
 });
 export type Admit = z.infer<typeof AdmitSchema>;
 
@@ -65,7 +66,7 @@ export function listDispatches(run: Run): Dispatch[] {
       if (!id.isDirectory()) continue;
       const dir = join(roles, name.name, id.name);
       try {
-        out.push({ dir, admit: readVersioned(admitPath(dir), AdmitSchema, 1) });
+        out.push({ dir, admit: decodeAdmit(readVersioned(admitPath(dir), AdmitSchema, 1)) });
       } catch {
         // admission never finished writing this folder
       }
@@ -174,3 +175,7 @@ export function readFailover(dir: string): FailoverFile | null {
 export function recordHints(run: Run, d: Dispatch, r: RunRecord): string[] {
   return readFailover(d.dir)?.hints ?? dispatchHints(r, d.admit.owns, relative(run.dir, d.dir));
 }
+
+function decodeAdmit(a: Admit): Admit {
+  return a.sessionId && !a.host ? { ...a, host: "claude-code" } : a;
+}