catherd-cli 1.2.1 → 1.4.0

package/src/services/profile-service.ts

@@ -1,3 +1,5 @@
+import type { HostContext, OrchestrationHost } from "../domain/host.ts";
+import { agentFiles } from "../domain/agents.ts";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -9,18 +11,19 @@ import {
   assertProfileName,
   type Change,
   defaultProfileDoc,
+  hostDefaultsDoc,
   diffProfiles,
   type Profile,
   type ProfileDoc,
   type ProfilePatch,
   resolveProfile,
 } from "../domain/profile.ts";
-import { repairs, type Validation, validateProfile } from "../domain/profile-rules.ts";
+import { nativeClaudeIssue, repairs, type Validation } from "../domain/profile-rules.ts";
 import { ROLES } from "../domain/roles.ts";
 import { withFileLockSync } from "../infra/filelock.ts";
 import { configDir } from "../infra/paths.ts";
 import { ensurePrivateDir, writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
-import { apply, plan, type Synced } from "./agent-links.ts";
+import { apply, plan, pruneProfileAgents, type Synced } from "./agent-links.ts";
 import { loadCatalog } from "./catalog-service.ts";
 import type { ProfilePort, ProfileSaved, ProfileView } from "./ports.ts";
 import {
@@ -37,7 +40,7 @@ import {
   readProjects,
   requireProfile,
   roleEnforcement,
-  runnableBackends,
+  validateHere,
   validateNamed,
 } from "./profile-store.ts";
 
@@ -54,11 +57,18 @@ const locked = withProfilesLock;
 const writeDoc = (name: string, doc: ProfileDoc) => writeJsonAtomic(profileFile(name), { ...doc, name });
 
 /** Writes `doc` as profile `name` and relinks; when the relink refuses, puts the profile back as it was. */
-function saveAndLink(name: string, doc: ProfileDoc): Synced {
+/** `repairing`: a saved repair with errors still open, whose remaining native roles are among those errors. */
+function saveAndLink(name: string, doc: ProfileDoc, host: OrchestrationHost, repairing = false): Synced {
   const before = existsSync(profileFile(name)) ? readFileSync(profileFile(name), "utf8") : null;
+  const nativeOn = (h: OrchestrationHost) => agentFiles(getProfile(name, h), "").length > 0;
+  const hadNative = before !== null && nativeOn(host);
+  // omitted defaults are native only on claude-code: the artifacts that resolution made count too
+  const hadClaudeNative = before !== null && host !== "claude-code" && nativeOn("claude-code");
   writeDoc(name, doc);
   try {
-    return apply(plan([name]));
+    // a profile left with no native role on any host owns no agents; one still native there keeps them
+    const allowPrune = host === "claude-code" || hadNative || (hadClaudeNative && !nativeOn("claude-code"));
+    return syncFor(name, host, [name], allowPrune, repairing);
   } catch (e) {
     if (before === null) rmSync(profileFile(name), { force: true });
     else writeTextAtomic(profileFile(name), before);
@@ -66,8 +76,34 @@ function saveAndLink(name: string, doc: ProfileDoc): Synced {
   }
 }
 
-const validate = (doc: ProfileDoc, name: string): Validation =>
-  validateProfile(resolveProfile(doc, name), loadCatalog({ timings: false }), runnableBackends(), doc);
+const validate = (doc: ProfileDoc, name: string, host: OrchestrationHost): Validation => {
+  try {
+    return validateHere(resolveProfile(doc, name, host), loadCatalog({ timings: false }), doc, host);
+  } catch (e) {
+    if (!(e instanceof CatherdError)) throw e;
+    return { errors: [{ path: "roles", message: e.message, fix: e.fix }], warnings: [] };
+  }
+};
+function nativeAgents(name: string, host: OrchestrationHost) {
+  const files = agentFiles(getProfile(name, host), "");
+  const first = files[0];
+  const issue = first && nativeClaudeIssue(first.rung, host, `roles.${first.role}.rungs`);
+  if (issue) throw new CatherdError("E_CONFIG_INVALID", issue.message, { fix: issue.fix });
+  return files;
+}
+function syncFor(
+  name: string,
+  host: OrchestrationHost,
+  extra: string[] = [],
+  allowPrune = host === "claude-code",
+  repairing = false,
+): Synced {
+  // a partial repair keeps its open native-role errors: link and prune nothing until they are fixed
+  if (repairing && agentFiles(getProfile(name, host), "").some((f) => nativeClaudeIssue(f.rung, host, "")))
+    return { linked: [], pruned: [], newSessionNeededFor: [] };
+  if (nativeAgents(name, host).length) return apply(plan(host, extra));
+  return allowPrune ? pruneProfileAgents(name) : { linked: [], pruned: [], newSessionNeededFor: [] };
+}
 
 /** What a save returns: the port's ProfileSaved (one type for the CLI, the TUI and the MCP tools). */
 export type Saved = ProfileSaved;
@@ -95,7 +131,7 @@ export const CHANGED_ON_DISK = "profile";
 export function patchProfile(
   name: string | undefined,
   patch: ProfilePatch,
-  opts: { expect?: ProfileDoc } = {},
+  opts: { host: OrchestrationHost; expect?: ProfileDoc },
 ): Saved {
   return locked(() => {
     const n = assertProfileName(name ?? activeName());
@@ -111,17 +147,18 @@ export function patchProfile(
         ],
         warnings: [],
       });
+    const host = opts.host;
     const after = applyPatch(before, patch);
-    const resolved = resolveProfile(after, n);
-    const v = validate(after, n);
-    if (v.errors.length && !repairs(profileExists(n) ? validate(before, n) : null, v)) return unsaved(v);
-    const diff = diffProfiles(resolveProfile(before, n), resolved);
-    return { saved: true, ...v, diff, ...saveAndLink(n, after) };
+    const v = validate(after, n, host);
+    if (v.errors.length && !repairs(profileExists(n) ? validate(before, n, host) : null, v))
+      return unsaved(v);
+    const diff = diffProfiles(resolveProfile(before, n, host), resolveProfile(after, n, host));
+    return { saved: true, ...v, diff, ...saveAndLink(n, after, host, v.errors.length > 0) };
   });
 }
 
 /** Spec §7.3 `create` and `copy`: a new profile from `from` (default: the default profile). */
-export function createProfile(name: string, from?: string): Saved {
+export function createProfile(name: string, from: string | undefined, host: OrchestrationHost): Saved {
   return locked(() => {
     // `default` exists without a file: resetProfile is the only way to write it
     if (profileExists(assertProfileName(name)))
@@ -133,20 +170,20 @@ export function createProfile(name: string, from?: string): Saved {
         fix: "catherd profile list",
       });
     const doc = from === undefined ? defaultProfileDoc(name) : readProfileDoc(from);
-    const v = validate(doc, name);
+    const v = validate(doc, name, host);
     if (v.errors.length) return unsaved(v);
-    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc) };
+    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc, host) };
   });
 }
 
 /** Writes the default profile under `name`, replacing what is there (`catherd init` when asked to). */
-export function resetProfile(name: string): Saved {
+export function resetProfile(name: string, host: OrchestrationHost): Saved {
   return locked(() => {
     assertProfileName(name);
     const doc = defaultProfileDoc(name);
-    const v = validate(doc, name);
+    const v = validate(doc, name, host);
     if (v.errors.length) return unsaved(v);
-    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc) };
+    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc, host) };
   });
 }
 
@@ -181,7 +218,7 @@ export function deleteProfile(name: string): Synced {
         bindings: Object.fromEntries(Object.entries(projects.bindings).filter(([r]) => !gone.has(r))),
       });
     try {
-      return apply(plan(), [name]);
+      return pruneProfileAgents(name);
     } catch (e) {
       writeTextAtomic(profileFile(name), text);
       if (gone.size) writeJsonAtomic(projectsFile(), projects);
@@ -193,7 +230,8 @@ export function deleteProfile(name: string): Synced {
 /** Spec §7.3 `activate(name, repo?)`: the active profile, or the one bound to a repo; relinks the agents. */
 export function activate(
   name: string,
-  repo: string | null = null,
+  repo: string | null,
+  host: OrchestrationHost,
 ): Synced & { active: string; repo: string | null } {
   return locked(() => {
     assertProfileName(name);
@@ -201,6 +239,7 @@ export function activate(
       throw new CatherdError("E_INPUT_INVALID", `no profile named "${name}"`, {
         fix: "catherd profile list",
       });
+    nativeAgents(name, host);
     const config = readConfig();
     const projects = readProjects();
     const write = () =>
@@ -213,7 +252,7 @@ export function activate(
           });
     write();
     try {
-      return { active: name, repo, ...apply(plan([name])) };
+      return { active: name, repo, ...syncFor(name, host, [name]) };
     } catch (e) {
       if (repo === null) writeJsonAtomic(configFile(), config);
       else writeJsonAtomic(projectsFile(), projects);
@@ -223,7 +262,7 @@ export function activate(
 }
 
 /** `catherd profile use --repo --clear`: removes `repo`'s binding, so it runs on the active profile again. */
-export function unbind(repo: string): Synced & { repo: string; was: string } {
+export function unbind(repo: string, host: OrchestrationHost): Synced & { repo: string; was: string } {
   return locked(() => {
     const projects = readProjects();
     const was = projects.bindings[repo];
@@ -235,7 +274,11 @@ export function unbind(repo: string): Synced & { repo: string; was: string } {
     delete bindings[repo];
     writeJsonAtomic(projectsFile(), { ...projects, schema: 1, bindings });
     try {
-      return { repo, was, ...apply(plan()) };
+      // a binding to a deleted profile is what doctor sends here to clear: there is nothing of it to relink
+      const synced = profileExists(was)
+        ? syncFor(was, host)
+        : { linked: [], pruned: [], newSessionNeededFor: [] };
+      return { repo, was, ...synced };
     } catch (e) {
       writeJsonAtomic(projectsFile(), projects);
       throw e;
@@ -243,8 +286,8 @@ export function unbind(repo: string): Synced & { repo: string; was: string } {
   });
 }
 
-export function diffNamed(a: string, b: string): Change[] {
-  return diffProfiles(getProfile(a), getProfile(b));
+export function diffNamed(a: string, b: string, host: OrchestrationHost): Change[] {
+  return diffProfiles(getProfile(a, host), getProfile(b, host));
 }
 
 function viewOf(p: Profile): ProfileView {
@@ -267,13 +310,16 @@ function viewOf(p: Profile): ProfileView {
 }
 
 /** The ProfilePort the run engine and the MCP tools use (spec §7.3: the single writer). */
-export function profileService(): ProfilePort {
+export function profileService(host: () => HostContext): ProfilePort {
   // without a name, each tool acts on the profile `repo` runs on (the active one outside a repo)
   return {
-    forRepo: (repo) => viewOf(profileFor(repo)),
+    withHost: profileService,
+    raw: (name, repo = null) => readProfileDoc(name ?? activeName(repo)),
+    budgetFor: (repo) => readProfileDoc(activeName(repo)).budget ?? {},
+    forRepo: (repo) => viewOf(profileFor(repo, host().host)),
     get(name, repo = null) {
       const here = activeName(repo);
-      const p = getProfile(name === undefined ? here : requireProfile(name));
+      const p = getProfile(name === undefined ? here : requireProfile(name), host().host);
       return {
         active: activeName(),
         here,
@@ -283,12 +329,52 @@ export function profileService(): ProfilePort {
       };
     },
     validate(name, repo = null) {
-      const v = validateNamed(name === undefined ? activeName(repo) : requireProfile(name), repo);
+      const v = validateNamed(
+        name === undefined ? activeName(repo) : requireProfile(name),
+        repo,
+        host().host,
+      );
       return { valid: v.errors.length === 0, ...v };
     },
     // a name that does not exist yet starts from the default profile
-    set: (name, patch, repo = null) => patchProfile(name ?? activeName(repo), patch),
+    set: (name, patch, repo = null) => patchProfile(name ?? activeName(repo), patch, { host: host().host }),
     agentFor: (repo, role, rung) =>
       parseRung(rung).backend === "claude" ? agentName(activeName(repo), role, rung) : null,
   };
 }
+
+export function resetHostDefaults(
+  name: string,
+  host: OrchestrationHost,
+  opts:
+    | { preview: true; expect?: ProfileDoc }
+    | { preview: false; expect: ProfileDoc; reviewed: { profile: string; host: OrchestrationHost } },
+): Saved & { expect: ProfileDoc; profile: string; host: OrchestrationHost } {
+  return locked(() => {
+    const refuse = (message: string, expect: ProfileDoc) => ({
+      ...unsaved({
+        errors: [{ path: CHANGED_ON_DISK, message, fix: "preview again and review the changes" }],
+        warnings: [],
+      }),
+      expect,
+      profile: name,
+      host,
+    });
+    // the reset is host-specific: a preview approves one profile on one host, never another
+    if (!opts.preview && (opts.reviewed.profile !== name || opts.reviewed.host !== host))
+      return refuse(
+        `the preview was for profile "${opts.reviewed.profile}" on host ${opts.reviewed.host}, not "${name}" on ${host}`,
+        opts.expect,
+      );
+    const before = readProfileDoc(name);
+    if (!opts.preview && !isDeepStrictEqual(before, opts.expect))
+      return refuse(`profile "${name}" changed on disk since it was shown`, before);
+    const after = hostDefaultsDoc(before);
+    const v = validate(after, name, host);
+    if (v.errors.length) return { ...unsaved(v), expect: before, profile: name, host };
+    const diff = diffProfiles(resolveProfile(before, name, host), resolveProfile(after, name, host));
+    return opts.preview
+      ? { ...unsaved(v), diff, expect: before, profile: name, host }
+      : { saved: true, ...v, diff, ...saveAndLink(name, after, host), expect: before, profile: name, host };
+  });
+}

package/src/services/profile-store.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "../domain/host.ts";
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -14,11 +15,13 @@ import {
   ProfileDocSchema,
   resolveProfile,
 } from "../domain/profile.ts";
-import { type Validation, validateProfile } from "../domain/profile-rules.ts";
+import { type Issue, type Validation, validateProfile } from "../domain/profile-rules.ts";
+import type { Catalog } from "../domain/catalog.ts";
 import type { Access } from "../domain/record.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
 import { configDir } from "../infra/paths.ts";
 import { readJsonFile } from "../infra/store.ts";
+import { standInFor } from "./backends.ts";
 import { backendOfKey, loadCatalog } from "./catalog-service.ts";
 
 // Spec §7.3, the read side of the profile service: where profiles, config.json and projects.json live,
@@ -92,7 +95,8 @@ export function readProfileDoc(name: string): ProfileDoc {
   throw new CatherdError("E_CONFIG_INVALID", `no profile named "${name}"`, { fix: "catherd profile list" });
 }
 
-export const getProfile = (name: string): Profile => resolveProfile(readProfileDoc(name), name);
+export const getProfile = (name: string, host: OrchestrationHost): Profile =>
+  resolveProfile(readProfileDoc(name), name, host);
 
 /** A profile name the user typed: refused as bad input (exit 2) when no such profile exists. */
 export function requireProfile(name: string): string {
@@ -107,7 +111,8 @@ export function activeName(repo: string | null = null): string {
   return bound ?? readConfig().activeProfile ?? "default";
 }
 
-export const profileFor = (repo: string | null): Profile => getProfile(activeName(repo));
+export const profileFor = (repo: string | null, host: OrchestrationHost): Profile =>
+  getProfile(activeName(repo), host);
 
 /** The backends catherd can run: every registered adapter, and the native `claude` path. */
 export const runnableBackends = (): string[] => ["claude", ...ADAPTER_IDS.filter((id) => adapterFor(id))];
@@ -116,12 +121,128 @@ export const runnableBackends = (): string[] => ["claude", ...ADAPTER_IDS.filter
 export const keyRunnable = (key: string, backends: string[] = runnableBackends()): boolean =>
   backends.includes(backendOfKey(key));
 
+/**
+ * Spec 1.3 §8: each backend `p` isolates whose isolated run logs in with an API key that is not in `env` (the
+ * environment catherd runs, and starts workers, in).
+ */
+export function isolationKeyErrors(
+  p: Profile,
+  env: Record<string, string | undefined> = process.env,
+): Issue[] {
+  const out: Issue[] = [];
+  for (const [id, h] of Object.entries(p.harness)) {
+    const key = h.isolated ? adapterFor(id)?.isolationKey : undefined;
+    if (key && !env[key])
+      out.push({
+        path: `harness.${id}.isolated`,
+        message: `an isolated ${id} run needs ${key}, which catherd's environment does not have`,
+        fix: `export ${key}=<key>, or catherd profile set harness.${id}.isolated false`,
+      });
+  }
+  return out;
+}
+
+/**
+ * Spec 1.3 §9 Q2: each enabled role whose rung, or a failover stand-in of one, runs natively on a backend that
+ * holds the role's access only when isolated (agy has no read-only flag).
+ */
+export function isolatedOnlyErrors(p: Profile): Issue[] {
+  const out: Issue[] = [];
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    if (!rc.enabled) continue;
+    // a stand-in the profile does not name is the one dispatch picks on its own (a paired backend's or the
+    // adapter's); one on the rung's own backend adds nothing, since the rung's own error names that backend
+    const runs = [
+      ...rc.rungs.map((r) => [r, `roles.${role}.rungs`]),
+      ...rc.rungs.flatMap((r) => {
+        if (p.failover[r]) return [[p.failover[r], `failover.${r}`, null]];
+        const s = standInFor(p.failover, r);
+        return s && tryParseRung(s)?.backend !== tryParseRung(r)?.backend
+          ? [[s, `roles.${role}.rungs`, r]]
+          : [];
+      }),
+    ] as [string, string, string | null][];
+    for (const [rung, path, auto] of runs) {
+      const b = tryParseRung(rung)?.backend;
+      if (!b || p.harness[b]?.isolated || !adapterFor(b)?.isolatedOnly?.includes(rc.access)) continue;
+      const isolate = `isolate ${b} (catherd profile set harness.${b}.isolated true)`;
+      out.push({
+        path,
+        message: `${rung}${auto ? `, the automatic stand-in of ${auto}` : ""}: native ${b} cannot hold the ${role} role to ${rc.access}`,
+        fix: auto
+          ? `${isolate}, or name another stand-in (catherd profile set failover.${auto} <rung>)`
+          : `${isolate}, or put this role on another backend`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Spec §4.6: with `budget.usd` set, one warning per backend an enabled role runs on whose adapter reports no
+ * dollar cost, since that cap never sees what the backend spends. Never an error: the cap still counts the rest.
+ */
+export function budgetUsdWarnings(p: Profile): Issue[] {
+  if (p.budget.usd === undefined) return [];
+  const blind = new Map<string, Role[]>();
+  const note = (rung: string, role: Role) => {
+    const b = tryParseRung(rung)?.backend;
+    // no adapter (native `claude`, whose subagents report their own cost): nothing to warn about
+    if (!b || adapterFor(b)?.reportsCost !== false) return;
+    const roles = blind.get(b) ?? [];
+    if (!roles.includes(role)) roles.push(role);
+    blind.set(b, roles);
+  };
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    if (!rc.enabled) continue;
+    for (const rung of rc.rungs) {
+      note(rung, role);
+      // a quota failover runs the role on its stand-in (its own, paired or the backend's), which the cap must see
+      const standIn = standInFor(p.failover, rung);
+      if (standIn) note(standIn, role);
+    }
+  }
+  return [...blind].map(([b, roles]) => ({
+    path: "budget.usd",
+    message: `budget.usd will not see ${b}'s spend: ${b} reports no dollar cost (${roles.join(", ")} run on it)`,
+    fix: "cap it with budget.tokens or budget.minutes: catherd profile set budget.tokens <n>",
+  }));
+}
+
+/**
+ * Spec §7.1 validation on this machine: the backends catherd can run here, the keys isolation needs, the
+ * accesses a backend holds only when isolated, and the backends a dollar budget cannot see.
+ */
+export function validateHere(
+  p: Profile,
+  c: Catalog,
+  doc?: ProfileDoc,
+  host: OrchestrationHost = "unknown",
+): Validation {
+  const v = validateProfile(p, c, runnableBackends(), doc, host);
+  return {
+    errors: [...v.errors, ...isolationKeyErrors(p), ...isolatedOnlyErrors(p)],
+    warnings: [...v.warnings, ...budgetUsdWarnings(p)],
+  };
+}
+
 /** `repo`: the git toplevel whose listing route reads (opencode lists its models per repository). */
-export function validateNamed(name?: string, repo: string | null = null): Validation {
+export function validateNamed(
+  name: string | undefined,
+  repo: string | null,
+  host: OrchestrationHost,
+): Validation {
   const n = name ?? activeName(repo);
   const doc = readProfileDoc(n);
   const catalog = loadCatalog({ timings: false, ...(repo === null ? {} : { repo }) });
-  return validateProfile(resolveProfile(doc, n), catalog, runnableBackends(), doc);
+  try {
+    return validateHere(resolveProfile(doc, n, host), catalog, doc, host);
+  } catch (e) {
+    if (!(e instanceof CatherdError)) throw e;
+    return { errors: [{ path: "roles", message: e.message, fix: e.fix }], warnings: [] };
+  }
 }
 
 /** Spec D10: how strongly the backend holds a role to its access mode. */

package/src/services/routing-service.ts

@@ -1,3 +1,4 @@
+import { assertNativeHost } from "./backends.ts";
 import { BUDGET_CHEAP_AT } from "../domain/budget.ts";
 import { errorMessage } from "../domain/errors.ts";
 import {
@@ -171,7 +172,11 @@ async function verdict<T extends string>(
 /** The routing port over the 1.0 catalog and Jev (spec §5); `o` lets tests inject Jev's transport. */
 export function routingService(o: RoutingOpts = {}): RoutingPort {
   return {
-    route: (req) => route(req, o),
+    route: async (req) => {
+      const result = await route(req, o);
+      assertNativeHost(result.rung, req.host ?? "unknown");
+      return result;
+    },
     finding: (runDir, laneText, finding, use) =>
       verdict(
         runDir,

package/src/services/run-debug.ts

@@ -1,15 +1,107 @@
-import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, openSync, readSync } from "node:fs";
+import { sessionKey, type HostContext, type HostSessionRef } from "../domain/host.ts";
+import { deliveryState, readDelivery, type DeliveryState } from "../infra/delivery.ts";
 import type { ExitInfo, RunRecord } from "../domain/record.ts";
-import { dispatchPaths, readExit } from "../infra/dispatch-dir.ts";
+import { awaitsCollect, dispatchPaths, readExit } from "../infra/dispatch-dir.ts";
 import { redact } from "../infra/log.ts";
-import { listDispatches } from "./dispatches.ts";
+import { type Dispatch, listDispatches } from "./dispatches.ts";
 import { registerSavedSecrets } from "./jev-service.ts";
+import { runOwner } from "./sessions.ts";
 import { readRecords, type Run } from "./run-store.ts";
 
 /** How many trailing lines of stderr, events and the supervisor log `runs show --debug` prints. */
 export const TAIL_LINES = 20;
 
-export interface DispatchDebug {
+export function inspectionHost(host: HostContext): HostContext {
+  const target = host.session;
+  return {
+    host: host.host,
+    conflict: host.conflict,
+    session: target
+      ? {
+          host: target.host,
+          sessionId: target.sessionId,
+          hostSessionId: target.hostSessionId,
+          name: target.name,
+        }
+      : null,
+  };
+}
+
+export interface DeliveryInspection {
+  eventId: string;
+  delivery: DeliveryState;
+  receipt: { msgId: string; target: HostSessionRef; at: string } | null;
+}
+
+export function inspectDelivery(
+  run: Run,
+  d: Dispatch,
+  recorded: boolean,
+  eventId = JSON.stringify([
+    run.id,
+    d.admit.dispatchId,
+    !recorded && existsSync(dispatchPaths(d.dir).stall) ? "stalled" : "finished",
+  ]),
+): DeliveryInspection {
+  const owner = runOwner(run);
+  const target = owner
+    ? { host: owner.host, sessionId: owner.sessionId, hostSessionId: null, name: null }
+    : null;
+  const finished = eventId === JSON.stringify([run.id, d.admit.dispatchId, "finished"]);
+  const collected = finished && recorded && !awaitsCollect(d.dir);
+  try {
+    const receipt = target
+      ? readDelivery(d.dir).findLast(
+          (a) =>
+            a.status === "accepted" &&
+            a.eventIds.includes(eventId) &&
+            sessionKey(a.target) === sessionKey(target),
+        )
+      : undefined;
+    return {
+      eventId,
+      delivery: collected
+        ? "collected"
+        : (recorded || !finished) && target
+          ? deliveryState(d.dir, target, eventId)
+          : "pending",
+      receipt: receipt?.msgId
+        ? {
+            msgId: receipt.msgId,
+            at: receipt.at,
+            target: {
+              host: receipt.target.host,
+              sessionId: receipt.target.sessionId,
+              hostSessionId: receipt.target.hostSessionId,
+              name: receipt.target.name,
+            },
+          }
+        : null,
+    };
+  } catch {
+    return { eventId, delivery: collected ? "collected" : "ambiguous", receipt: null };
+  }
+}
+
+/**
+ * Stored stalled and finished events are separate; only finished records can be collected. A stall the role
+ * outlived that is still pending for the current owner can never go out (the notifier drops it and retry
+ * refuses it), so it is not shown; one with an outcome for this owner (accepted, ambiguous) still is.
+ */
+export function inspectDeliveries(run: Run, d: Dispatch, recorded: boolean): DeliveryInspection[] {
+  const exited = existsSync(dispatchPaths(d.dir).exit);
+  return [...(recorded ? ["finished"] : []), ...(existsSync(dispatchPaths(d.dir).stall) ? ["stalled"] : [])]
+    .map((kind) => ({
+      kind,
+      ...inspectDelivery(run, d, recorded, JSON.stringify([run.id, d.admit.dispatchId, kind])),
+    }))
+    .filter((e) => !(e.kind === "stalled" && exited && e.delivery === "pending"))
+    .map(({ kind: _kind, ...e }) => e);
+}
+
+export interface DispatchDebug extends DeliveryInspection {
+  deliveries: DeliveryInspection[];
   name: string;
   dispatchId: string;
   rung: string;
@@ -65,6 +157,8 @@ export function runDebug(run: Run, name?: string): DispatchDebug[] {
     .map((d) => {
       const p = dispatchPaths(d.dir);
       return redact({
+        ...inspectDelivery(run, d, records.has(d.admit.dispatchId)),
+        deliveries: inspectDeliveries(run, d, records.has(d.admit.dispatchId)),
         name: d.admit.name,
         dispatchId: d.admit.dispatchId,
         rung: d.admit.rung,

package/src/services/run-service.ts

@@ -15,9 +15,11 @@ import {
   recordHints,
 } from "./dispatches.ts";
 import type { Deps } from "./ports.ts";
+import { assertNativeHost } from "./backends.ts";
 import {
   type AgentRun,
   appendAgentRun,
+  appendKnowledge,
   createRun,
   findRun,
   knowledgeFile,
@@ -166,6 +168,7 @@ export function recordAgentRun(
     throw new CatherdError("E_ADMIT_RUNG", `${i.rung} is not a native Claude rung`, {
       fix: "record_agent_run is for Agent subagents; dispatch records every other run itself",
     });
+  assertNativeHost(i.rung, deps.host.conflict ? "unknown" : deps.host.host);
   const row: AgentRun = {
     at: new Date(deps.now()).toISOString(),
     name: i.name,
@@ -182,13 +185,45 @@ export function recordAgentRun(
   return row;
 }
 
-/** What past runs of the repo learned; `repo` may be any path inside it. */
-export async function readKnowledge(repo: string): Promise<string> {
+/** The git toplevel of `repo`, any path inside it; refused outside a repository. */
+async function repoTop(repo: string): Promise<string> {
   const top = await gitToplevel(repo);
   if (!top)
     throw new CatherdError("E_IO_PATH", `${repo} is not inside a git repository`, {
       fix: "pass the path of the repository",
     });
-  const file = knowledgeFile(top);
-  return existsSync(file) ? readFileSync(file, "utf8") : "catherd: no knowledge recorded yet for this repo";
+  return top;
+}
+
+/** What past runs of the repo learned; `repo` may be any path inside it. */
+export async function readKnowledge(repo: string): Promise<string> {
+  const file = knowledgeFile(await repoTop(repo));
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  return text.trim() ? text : "catherd: no knowledge recorded yet for this repo";
+}
+
+/** Where the repo's knowledge.md is (it may not exist yet); `repo` may be any path inside it. */
+export async function knowledgePath(repo: string): Promise<{ repo: string; path: string }> {
+  const top = await repoTop(repo);
+  return { repo: top, path: knowledgeFile(top) };
+}
+
+/** The repo's knowledge.md as its lines, none when it is missing or blank; `repo` may be any path inside it. */
+export async function knowledgeLines(repo: string): Promise<{ repo: string; path: string; lines: string[] }> {
+  const at = await knowledgePath(repo);
+  const text = existsSync(at.path) ? readFileSync(at.path, "utf8") : "";
+  return { ...at, lines: text.split("\n").filter((l) => l.trim()) };
+}
+
+/** The source a line added by hand carries, where a landing puts its run's title and milestone. */
+const BY_HAND = "by hand";
+
+/** Appends one line of the user's own to the repo's knowledge.md, as `land`'s `learned` does; returns it. */
+export async function addKnowledge(repo: string, text: string, now: Date = new Date()): Promise<string> {
+  const top = await repoTop(repo);
+  if (!text.trim())
+    throw new CatherdError("E_INPUT_INVALID", "the knowledge line is empty", {
+      fix: 'pass one line of text, e.g. catherd knowledge add "the targeted test is bun test <file>"',
+    });
+  return appendKnowledge(top, now, BY_HAND, text);
 }