catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/doctor-checks.ts

@@ -7,6 +7,7 @@ import { claudeHome, locksDir } from "../infra/paths.ts";
 import { ensurePrivateDir, PRIVATE_FILE } from "../infra/store.ts";
 import { agentLinkState } from "./agent-links.ts";
 import type { Handshake } from "./doctor.ts";
+import { type IndexStatus, indexStatus } from "./catalog-service.ts";
 import { activeName } from "./profile-store.ts";
 
 // The rows of `catherd doctor` and the checks that stand alone; doctor.ts assembles the report.
@@ -40,6 +41,52 @@ export function guarded(id: string, label: string, fallbackFix: string, check: (
   }
 }
 
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+
+/** An age as doctor prints it: minutes under an hour, hours under two days, else days. */
+export function ageText(ms: number): string {
+  if (ms < HOUR) return `${Math.max(1, Math.round(ms / 60_000))} min`;
+  if (ms < 2 * DAY) return `${Math.round(ms / HOUR)} h`;
+  return `${Math.round(ms / DAY)} d`;
+}
+
+/**
+ * The `catalog` row: the Slopalytics index's age and the last fetch's error. `info` before the first fetch;
+ * a warning when the last fetch failed, or the index has not been checked for a day, since the hourly refresh
+ * would have. It reads the cache file only: no request.
+ */
+export function indexCheck(now = Date.now(), s: IndexStatus = indexStatus()): Check {
+  const base = { id: "catalog", label: "catalog" };
+  if (s.checkedAt === null || (s.fetchedAt === null && s.error === null))
+    return {
+      ...base,
+      state: "info",
+      word: "not fetched",
+      detail: "no model is indexed yet",
+      fix: "catherd catalog sync",
+    };
+  const age = ageText(now - Date.parse(s.fetchedAt ?? s.checkedAt));
+  if (s.error !== null)
+    return {
+      ...base,
+      state: "warn",
+      word: "failing",
+      detail:
+        s.fetchedAt === null ? `${s.error}; no index` : `${s.error}; keeps the index fetched ${age} ago`,
+      fix: "catherd catalog sync --force",
+    };
+  if (now - Date.parse(s.checkedAt) > DAY)
+    return {
+      ...base,
+      state: "warn",
+      word: "stale",
+      detail: `${s.pairs} pairs, fetched ${age} ago`,
+      fix: "catherd catalog sync --force",
+    };
+  return { ...base, state: "ok", word: "fresh", detail: `${s.pairs} pairs, fetched ${age} ago` };
+}
+
 export function pluginCheck(version: string): Check {
   const base = { id: "plugin", label: "Claude Code plugin" };
   const file = join(claudeHome(), "plugins", "installed_plugins.json");

package/src/services/doctor-docker.ts

@@ -0,0 +1,221 @@
+import {
+  accessSync,
+  constants,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statfsSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { realTmpdir, toolchainCaches } from "../adapters/access.ts";
+import { runCli } from "../adapters/cli.ts";
+import { probeTwice } from "../infra/host-probe.ts";
+import { probeTargets } from "./doctor-access.ts";
+import type { Check } from "./doctor-checks.ts";
+
+// Plan 23: the rows that catch what cost the identity and payment runs their verifier rounds: a Docker client
+// that injects proxies into every container, a compose network whose services cannot reach each other by
+// name, a Docker disk about to fill, and the toolchain caches a sandboxed worker writes.
+
+/** Under this much free space in Docker's data root, doctor warns: image builds start failing near it (tests raise it). */
+export const dockerDisk = { minFreeBytes: 10 * 1024 ** 3 };
+
+/** How long the compose probe may take, an image pull included. */
+export const composeProbe = { timeoutMs: 120_000 };
+
+/** The Docker client's config file: $DOCKER_CONFIG/config.json, else ~/.docker/config.json. */
+export const dockerConfigFile = (env = process.env): string =>
+  join(env.DOCKER_CONFIG || join(env.HOME || homedir(), ".docker"), "config.json");
+
+/** The keys of a proxies entry the Docker client turns into container environment variables. */
+const PROXY_KEYS = ["httpProxy", "httpsProxy", "noProxy", "ftpProxy", "allProxy"];
+
+/** The Docker client's default daemon host, which its proxies block may key an entry by. */
+const DEFAULT_DOCKER_HOST = "unix:///var/run/docker.sock";
+
+/**
+ * A `proxies` block in the Docker client's config that sets a value: every container then gets HTTP_PROXY and its
+ * siblings. The Docker client applies the current daemon host's entry, else `default`; an entry with no value
+ * (or an empty block) injects nothing.
+ */
+export function proxiesCheck(
+  file = dockerConfigFile(),
+  env: Record<string, string | undefined> = process.env,
+): Check | null {
+  let config: { proxies?: unknown };
+  try {
+    config = JSON.parse(readFileSync(file, "utf8")) as { proxies?: unknown };
+  } catch {
+    return null;
+  }
+  const proxies = config.proxies;
+  if (!proxies || typeof proxies !== "object") return null;
+  const entries = proxies as Record<string, unknown>;
+  const host = env.DOCKER_HOST || DEFAULT_DOCKER_HOST;
+  const entry = Object.hasOwn(entries, host) ? entries[host] : entries.default;
+  const sets =
+    !!entry &&
+    typeof entry === "object" &&
+    PROXY_KEYS.some((k) => {
+      const v = (entry as Record<string, unknown>)[k];
+      return typeof v === "string" && v.trim() !== "";
+    });
+  if (!sets) return null;
+  return {
+    id: "docker-proxies",
+    label: "Docker client proxies",
+    state: "warn",
+    word: "injects proxies",
+    detail: `${file} has a proxies block: every container gets HTTP_PROXY, so compose services cannot reach each other by name and a loopback health check goes to the proxy`,
+    fix: `remove the proxies block from ${file}, or add the compose service names and 127.0.0.1 to its noProxy`,
+  };
+}
+
+/** Two busybox services: `web` serves on 8080 with a loopback health check, `probe` fetches it by name. */
+const COMPOSE = `services:
+  web:
+    image: busybox:1.36
+    command: ["httpd", "-f", "-p", "8080", "-h", "/etc"]
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/hostname"]
+      interval: 1s
+      retries: 30
+  probe:
+    image: busybox:1.36
+    depends_on:
+      web:
+        condition: service_healthy
+    command: ["wget", "-q", "-O", "/dev/null", "http://web:8080/hostname"]
+`;
+
+/** `docker compose up` on the two-service file, then `down`; the result of the up. */
+async function composeUp(docker: string): Promise<{ ok: boolean; why: string }> {
+  const dir = mkdtempSync(join(realTmpdir(), "catherd-compose-"));
+  const file = join(dir, "compose.yaml");
+  writeFileSync(file, COMPOSE);
+  const project = ["compose", "-p", `catherd-doctor-${process.pid}`, "-f", file];
+  try {
+    const up = await runCli(
+      docker,
+      [...project, "up", "--abort-on-container-exit", "--exit-code-from", "probe"],
+      {
+        timeoutMs: composeProbe.timeoutMs,
+        cwd: dir,
+      },
+    );
+    const lines = `${up?.err ?? ""}\n${up?.out ?? ""}`
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean);
+    return { ok: up?.ok === true, why: lines.at(-1) ?? "no output" };
+  } finally {
+    await runCli(docker, [...project, "down", "-v", "--remove-orphans"], { timeoutMs: 30_000, cwd: dir });
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Free bytes in Docker's data root, when it is on this machine's disk; null when Docker runs in a VM. */
+async function dockerFree(docker: string): Promise<{ root: string; free: number } | null> {
+  const r = await runCli(docker, ["info", "--format", "{{.DockerRootDir}}"], { timeoutMs: 15_000 });
+  const root = r?.ok ? r.out.trim() : "";
+  if (!root || !existsSync(root)) return null;
+  try {
+    const s = statfsSync(root);
+    return { root, free: Number(s.bavail) * Number(s.bsize) };
+  } catch {
+    return null;
+  }
+}
+
+const gb = (bytes: number): string => `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+
+/**
+ * The Docker rows: the client's proxies, read from its config file; with `probe` (`catherd doctor --docker`), when
+ * a daemon answers, the compose network probe (retried once after 5 s before it calls the host blocked) and the
+ * free space in Docker's data root. The probes pull busybox and start containers, so a plain doctor skips them.
+ */
+export async function dockerChecks(o: { probe: boolean }): Promise<Check[]> {
+  const docker = probeTargets.docker;
+  const checks: Check[] = [];
+  const proxies = proxiesCheck();
+  if (proxies) checks.push(proxies);
+  if (!o.probe) return checks;
+  const version = await runCli(docker, ["version"], { timeoutMs: 15_000 });
+  if (!version?.ok) return checks;
+  const compose = await runCli(docker, ["compose", "version"], { timeoutMs: 15_000 });
+  if (compose?.ok) {
+    const { result, attempts } = await probeTwice(
+      () => composeUp(docker),
+      (r) => r.ok,
+    );
+    checks.push(
+      result.ok
+        ? {
+            id: "docker-network",
+            label: "compose network",
+            state: "ok",
+            word: "ready",
+            detail: "two services reach each other by name, and a loopback health check passes",
+          }
+        : {
+            id: "docker-network",
+            label: "compose network",
+            state: "warn",
+            word: "blocked",
+            detail: `a compose service could not reach another by name, or its loopback health check failed (${attempts} tries, 5 s apart): ${result.why}`,
+            fix: proxies
+              ? (proxies.fix as string)
+              : "check the Docker client's proxies, a VPN or socket filter on the Docker bridge, and that busybox can be pulled",
+          },
+    );
+  }
+  const free = await dockerFree(docker);
+  if (free && free.free < dockerDisk.minFreeBytes)
+    checks.push({
+      id: "docker-disk",
+      label: "Docker disk",
+      state: "warn",
+      word: "low",
+      detail: `${gb(free.free)} free in Docker's data root ${free.root}; builds fail with no space left on device`,
+      fix: "docker image prune -f, then docker builder prune -f",
+    });
+  return checks;
+}
+
+/** Whether this user may write `dir`. */
+const writable = (dir: string): boolean => {
+  try {
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The toolchain caches present on the machine (Go's build and module caches, the pnpm store, Bun's and npm's
+ * caches), which join every workspace-write worker's writable roots; a warning for one this user cannot write.
+ */
+export function cachesCheck(caches = toolchainCaches()): Check {
+  const base = { id: "caches", label: "toolchain caches" };
+  if (caches.length === 0)
+    return { ...base, state: "skip", word: "none", detail: "no Go, pnpm, Bun or npm cache on this machine" };
+  const blocked = caches.filter((c) => !writable(c));
+  return blocked.length
+    ? {
+        ...base,
+        state: "warn",
+        word: "not writable",
+        detail: `${blocked.join(", ")}: a worker's checks cannot write it, even with it in their writable roots`,
+        fix: `chown -R "$(id -un)" ${blocked.join(" ")}`,
+      }
+    : {
+        ...base,
+        state: "ok",
+        word: "ready",
+        detail: `in every workspace-write worker's writable roots: ${caches.join(", ")}`,
+      };
+}

package/src/services/doctor-role-mcp.ts

@@ -0,0 +1,65 @@
+import { tryParseRung } from "../domain/ids.ts";
+import type { Profile } from "../domain/profile.ts";
+import { roleMcpTools } from "../domain/role-tools.ts";
+import { ROLES } from "../domain/roles.ts";
+import { ROLE_MCP_STARTUP_SEC, type RoleServerStart } from "../infra/role-mcp.ts";
+import { standInFor } from "./backends.ts";
+import type { Check } from "./doctor-checks.ts";
+
+/**
+ * The active profile's role server, per backend that runs one (codex, claude-code), isolated or not (spec 1.5
+ * plan 21, #42 finding 6): the roles that get it and their tools, and, when doctor probed it, how long a cold
+ * start took against Codex's startup timeout. A start past half that timeout warns: on a loaded machine Codex,
+ * which requires the server, would abort the role.
+ */
+export function roleMcpChecks(profile: Profile | null, start?: RoleServerStart): Check[] {
+  if (!profile) return [];
+  const checks: Check[] = [];
+  for (const backend of ["codex", "claude-code"] as const) {
+    const uses = (rung: string) => tryParseRung(rung)?.backend === backend;
+    const roles = ROLES.filter((role) => {
+      const configured = profile.roles[role];
+      return (
+        configured.enabled &&
+        configured.rungs.some((rung) => {
+          const failover = standInFor(profile.failover, rung);
+          return uses(rung) || (failover !== null && uses(failover));
+        })
+      );
+    });
+    if (!roles.length) continue;
+    const base = { id: `role-mcp:${profile.name}:${backend}`, label: `${profile.name} ${backend} role MCP` };
+    const tools = [...new Set(roles.flatMap(roleMcpTools))];
+    const configured = `${roles.join(", ")}: scoped catherd_role exposes ${tools.join(", ")}; ${backend === "codex" ? "per-tool approval_mode=approve" : "exact MCP tool allowlist"}. Model invocation not tested; managed policy may still deny tools.`;
+    const limit = ROLE_MCP_STARTUP_SEC * 1000;
+    if (start && !start.ok) {
+      checks.push({
+        ...base,
+        state: "fail",
+        word: "no start",
+        detail: `the role server did not start: ${start.error}`,
+        fix: "reinstall catherd at this version, then run catherd doctor again",
+      });
+      continue;
+    }
+    if (start?.ok && start.ms > limit / 2) {
+      checks.push({
+        ...base,
+        state: "warn",
+        word: "slow start",
+        detail: `the role server took ${Math.round(start.ms)} ms to start; Codex gives it ${ROLE_MCP_STARTUP_SEC} s and stops the role when it misses`,
+        fix: "install catherd globally (catherd init) so roles start it without resolving a package, and check the machine's load",
+      });
+      continue;
+    }
+    checks.push({
+      ...base,
+      state: "info",
+      word: "configured",
+      detail: start?.ok
+        ? `${configured} Starts in ${Math.round(start.ms)} ms (limit ${ROLE_MCP_STARTUP_SEC} s).`
+        : configured,
+    });
+  }
+  return checks;
+}

package/src/services/doctor.ts

@@ -7,14 +7,17 @@ import { BUILTIN_ROLES, type Profile } from "../domain/profile.ts";
 import { DEFAULT_ACCESS, ROLES } from "../domain/roles.ts";
 import { bunTooOld, MIN_BUN } from "../domain/runtime.ts";
 import type { JevTransport } from "../infra/jev-client.ts";
+import type { RoleServerStart } from "../infra/role-mcp.ts";
 import { linkedProfiles } from "./agent-links.ts";
 import { accessChecks } from "./doctor-access.ts";
 import { backendChecks, usedBackends } from "./doctor-backends.ts";
 import { type PushProbe, pushCheck, probePush } from "./doctor-push.ts";
-import { sourcesCheck, standInsToConfirmIn } from "./doctor-sources.ts";
+import { cachesCheck, dockerChecks } from "./doctor-docker.ts";
+import { roleMcpChecks } from "./doctor-role-mcp.ts";
 import {
   agentsCheck,
   hostFlag,
+  indexCheck,
   type Check,
   errText,
   fixOf,
@@ -66,14 +69,33 @@ export interface DoctorDeps {
   /** Explicit smoke test injection; default doctor never invokes it. */
   push?: () => Promise<PushProbe>;
   testPush?: boolean;
+  /** plan 23: `--docker`: run the Docker host probes (a compose network by service name, the free disk) */
+  docker?: boolean;
   env?: Record<string, string | undefined>;
   jev?: JevTransport;
+  /** spec 1.5 plan 21: a cold start of the role server, timed; absent, doctor does not probe it */
+  roleServerStart?: () => Promise<RoleServerStart>;
 }
 
 /**
  * Spec §10.3: the readiness report. Reads and probes; it writes discovery and a lock probe itself, and the
  * handshake starts `catherd mcp`, which reconciles runs as it starts. A check that throws becomes a `fail` row.
  */
+/**
+ * Where the access probes look for a per-repo sandbox: the current repo and each repo bound to a checked
+ * profile. A repo bound to another profile never runs these roles, so its settings must not decide the probes.
+ */
+export function accessRepos(
+  repo: string | null,
+  bindings: Record<string, string>,
+  checked: string[],
+): string[] {
+  const bound = Object.entries(bindings)
+    .filter(([, name]) => checked.includes(name))
+    .map(([r]) => r);
+  return [...new Set([...(repo ? [repo] : []), ...bound])];
+}
+
 export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
   const checks: Check[] = [];
   checks.push(
@@ -86,7 +108,13 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
           detail: `${d.bunVersion}, needs ${MIN_BUN}`,
           fix: "bun upgrade",
         }
-      : { id: "bun", label: "Bun", state: "ok", word: "ready", detail: d.bunVersion },
+      : {
+          id: "bun",
+          label: "Bun",
+          state: "ok",
+          word: "ready",
+          detail: d.bunVersion,
+        },
   );
 
   // every fix names the host doctor judged with: run elsewhere (a plain terminal), it must judge the same way
@@ -148,7 +176,7 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
     const named = (fix: string) =>
       fix.replaceAll("catherd profile set ", `catherd profile set --profile ${name}${onHost} `);
     const row = guarded(id, `profile ${name}`, validate, () => {
-      const v = validateNamed(name, d.repo, d.host.host);
+      const v = validateNamed(name, d.repo, d.host.host, { unindexed: "warning" });
       const first = v.errors[0] ?? v.warnings[0];
       return {
         id,
@@ -170,6 +198,7 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
   const used = usedBackends(profiles);
   const installed = new Set<string>();
   checks.push(...(await backendChecks(used, profiles, installed, d.host.host)));
+  checks.push(...roleMcpChecks(active, await d.roleServerStart?.()));
 
   if (active && [active, ...profiles].every((p) => p.jev.use === "off"))
     checks.push({
@@ -194,7 +223,13 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
       const ok = await testJevKey(key, d.jev).catch(() => false);
       checks.push(
         ok
-          ? { id: "jev", label: "Jev", state: "ok", word: "ready", detail: "the key answers" }
+          ? {
+              id: "jev",
+              label: "Jev",
+              state: "ok",
+              word: "ready",
+              detail: "the key answers",
+            }
           : {
               id: "jev",
               label: "Jev",
@@ -207,14 +242,9 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
     }
   }
 
-  // spec 1.2 §9: the public sources' ages and errors, the Artificial Analysis key, and the active and linked
-  // profiles' stand-ins to confirm
   const mine = [...(active ? [active] : []), ...diagnostics.filter((p) => p.name !== active?.name)];
-  checks.push(
-    guarded("sources", "sources", "catherd catalog sync --force", () =>
-      sourcesCheck(Date.now(), standInsToConfirmIn(mine)),
-    ),
-  );
+  // the Slopalytics index: its age and the last fetch's error
+  checks.push(guarded("catalog", "catalog", "catherd catalog sync", () => indexCheck()));
 
   const native = used.get("claude");
   const plugin = pluginCheck(d.version);
@@ -275,7 +305,9 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
       word: !queue.cli ? "unavailable" : queue.server,
       detail: queue.reason ?? "Native server advertises queue support",
       ...(!queue.cli || queue.server === "unsupported"
-        ? { fix: "Update native Codex/server; use peek/result while push is unavailable." }
+        ? {
+            fix: "Update native Codex/server; use peek/result while push is unavailable.",
+          }
         : {}),
     });
   let push: PushProbe | null = null;
@@ -291,8 +323,21 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
   }
 
   checks.push(locksCheck());
+  // plan 23: the toolchain caches workers write, and Docker as a gate sees it (before the access probes)
+  checks.push(cachesCheck());
+  checks.push(...(await dockerChecks({ probe: d.docker === true })));
   // spec §5 and §12: which codex sandbox form runs, and the five access probes per workspace-write backend
-  checks.push(...(await accessChecks(profiles, installed)));
+  let repos: string[] = d.repo ? [d.repo] : [];
+  try {
+    repos = accessRepos(
+      d.repo,
+      readProjects().bindings,
+      profiles.map((p) => p.name),
+    );
+  } catch {
+    // the config row above already reports an unreadable projects.json
+  }
+  checks.push(...(await accessChecks(profiles, installed, repos)));
 
   // spec 1.1 §13: what the shipped defaults do is info; a warning only for what a profile changed
   const full = { changed: [] as string[], shipped: [] as string[] };
@@ -329,7 +374,13 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
           word: "warning",
           detail: `${what}: ${rows.changed.join(", ")}${shipped ? `; as shipped: ${shipped}` : ""}`,
         }
-      : { id, label, state: "info", word: "default", detail: `${what}: ${shipped}` };
+      : {
+          id,
+          label,
+          state: "info",
+          word: "default",
+          detail: `${what}: ${shipped}`,
+        };
   };
   for (const row of [
     accessRow("access:full", "full access", full, "no sandbox for"),
@@ -372,7 +423,13 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
               detail: unreadable.message,
               fix: unreadable.fix ?? `fix or delete ${creds}, then catherd init`,
             }
-          : { id: "credentials", label: "credentials.json", state: "ok", word: "ready", detail: "mode 600" },
+          : {
+              id: "credentials",
+              label: "credentials.json",
+              state: "ok",
+              word: "ready",
+              detail: "mode 600",
+            },
     );
   }
 

package/src/services/end-push.ts

@@ -0,0 +1,157 @@
+import { readFileSync } from "node:fs";
+import { errorMessage } from "../domain/errors.ts";
+import type { HostSessionRef } from "../domain/host.ts";
+import { envelope, formatNotices } from "../domain/notice.ts";
+import { type QueueSendResult, sendToCodexQueue } from "../infra/codex-queue.ts";
+import {
+  type DeliveryAttempt,
+  deliveryState,
+  ROLE_THREAD_REFUSAL,
+  writeDeliveryAttempt,
+} from "../infra/delivery.ts";
+import { awaitsCollect, dispatchPaths } from "../infra/dispatch-dir.ts";
+import { tryLock } from "../infra/filelock.ts";
+import { log } from "../infra/log.ts";
+import { admitPath, listDispatches, roleThreadOf } from "./dispatches.ts";
+import { finalizeDispatch } from "./finalize.ts";
+import { finishedNotice, recoverSubmission } from "./notifier.ts";
+import { findRun } from "./run-store.ts";
+import { runOwner } from "./sessions.ts";
+
+/**
+ * How long the supervisor leaves the owner's MCP server to push first (the fast path: its watcher finalizes,
+ * settles and sends within the notifier's coalescing window). Either path sends under the same per-event receipt,
+ * so a late server or a late supervisor finds the event accepted and sends nothing.
+ */
+export const END_PUSH_GRACE_MS = 20_000;
+
+/** `CATHERD_END_PUSH_GRACE_MS` (a test of the spawned supervisor shortens it), else END_PUSH_GRACE_MS. */
+function graceFromEnv(): number {
+  const ms = Number(process.env.CATHERD_END_PUSH_GRACE_MS);
+  return process.env.CATHERD_END_PUSH_GRACE_MS !== undefined && Number.isFinite(ms) && ms >= 0
+    ? ms
+    : END_PUSH_GRACE_MS;
+}
+
+export interface EndPushOptions {
+  graceMs?: number;
+  /** the sender; tests replace it */
+  sendCodex?: (target: HostSessionRef, content: string) => Promise<QueueSendResult>;
+  now?: () => number;
+}
+
+/** Why the supervisor pushed nothing, or the receipt's status when it did. */
+export type EndPushOutcome =
+  | "off"
+  | "not-a-run"
+  | "not-codex"
+  | "limit"
+  | "read"
+  | "busy"
+  | "delivered"
+  | DeliveryAttempt["status"];
+
+/** The run's owner, when it is a Codex thread: the supervisor's push targets it. */
+function codexOwner(runId: string): HostSessionRef | null {
+  const owner = runOwner(findRun(runId));
+  return owner?.host === "codex"
+    ? { host: "codex", sessionId: owner.sessionId, hostSessionId: null, name: null }
+    : null;
+}
+
+/**
+ * Plan 22, push from where a role ends: the detached supervisor of a dispatch whose run a Codex thread owns, once
+ * its worker exited, queues the role's notice to that thread with `codex queue --remote unix:// --thread <owner>`.
+ * Codex's app-server keeps queued input for an unloaded thread, so a result reaches a coordinator whose MCP
+ * server the daemon stopped (no client attached) at its next attach. The notice is the server's own text, and it
+ * goes under the same per-event receipt (`delivery.json`, the dispatch's notify lock), so the two paths never
+ * double-deliver. A usage limit is left to the owner's server, which fails it over before it announces it.
+ * `CATHERD_NO_END_PUSH=1` turns it off (the test preload sets it). Never throws.
+ */
+export async function pushFromEnd(dispatchDir: string, o: EndPushOptions = {}): Promise<EndPushOutcome> {
+  if (process.env.CATHERD_NO_END_PUSH === "1") return "off";
+  try {
+    const runId = (JSON.parse(readFileSync(admitPath(dispatchDir), "utf8")) as { runId?: unknown }).runId;
+    if (typeof runId !== "string") return "not-a-run";
+    // read before the grace: a run no Codex thread owns costs the supervisor nothing
+    if (!codexOwner(runId)) return "not-codex";
+    await Bun.sleep(o.graceMs ?? graceFromEnv());
+    const run = findRun(runId);
+    const d = listDispatches(run).find((x) => x.dir === dispatchDir);
+    if (!d) return "not-a-run";
+    const record = await finalizeDispatch(run, d);
+    if (record.status === "limit") return "limit";
+    // the owner of record now, which a claim may have changed during the grace
+    const target = codexOwner(runId);
+    if (!target) return "not-codex";
+    if (!awaitsCollect(d.dir)) return "read";
+    const notice = finishedNotice(run, d, record);
+    const release = tryLock(dispatchPaths(d.dir).notified);
+    if (!release) return "busy";
+    try {
+      recoverSubmission(d.dir, notice.eventId);
+      if (deliveryState(d.dir, target, notice.eventId) !== "pending") return "delivered";
+      // spec 1.5 plan 21: never to a role's own thread (a `codex exec` thread exits after its turn, so what is
+      // queued there is lost); it fails loudly, with the notifier's reason, which `status` shows
+      const role = roleThreadOf(run, target.sessionId);
+      if (role !== null) {
+        const reason = `${ROLE_THREAD_REFUSAL} (${role}, ${target.host} ${target.sessionId}), not the orchestrator's; peek(run) from the orchestrator's session takes the run back`;
+        log("error", "notify", { from: "supervisor", run: run.id, dispatch: notice.dispatchId, reason });
+        writeDeliveryAttempt(d.dir, {
+          attemptId: crypto.randomUUID(),
+          target,
+          eventIds: [notice.eventId],
+          at: new Date((o.now ?? Date.now)()).toISOString(),
+          status: "failed",
+          msgId: null,
+          reason,
+        });
+        return "failed";
+      }
+      const attempt: DeliveryAttempt = {
+        attemptId: crypto.randomUUID(),
+        target,
+        eventIds: [notice.eventId],
+        at: new Date((o.now ?? Date.now)()).toISOString(),
+        status: "submitting",
+        msgId: null,
+        reason: null,
+      };
+      writeDeliveryAttempt(d.dir, attempt);
+      let sent: QueueSendResult;
+      try {
+        sent = await (o.sendCodex ?? ((t, c) => sendToCodexQueue(t, c, process.env)))(
+          target,
+          envelope(formatNotices([notice])),
+        );
+      } catch {
+        sent = { outcome: "ambiguous", reason: "Sender ended without a verified receipt; use peek/result." };
+      }
+      const receipt: DeliveryAttempt = {
+        ...attempt,
+        status:
+          sent.outcome === "accepted"
+            ? "accepted"
+            : sent.outcome === "not-submitted"
+              ? "failed"
+              : "ambiguous",
+        msgId: sent.outcome === "accepted" ? sent.msgId : null,
+        reason: sent.outcome === "accepted" ? null : sent.reason,
+      };
+      writeDeliveryAttempt(d.dir, receipt);
+      log(receipt.status === "accepted" ? "info" : "warn", "notify", {
+        from: "supervisor",
+        outcome: receipt.status,
+        msgId: receipt.msgId,
+        reason: receipt.reason,
+        dispatches: [notice.dispatchId],
+      });
+      return receipt.status;
+    } finally {
+      release();
+    }
+  } catch (e) {
+    log("warn", "notify", { from: "supervisor", dispatch: dispatchDir, error: errorMessage(e) });
+    return "not-a-run";
+  }
+}