@staix/agent-hub 0.12.44 → 0.12.45

package/src/adapters/external-modules.ts

@@ -0,0 +1,240 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { isBuiltin } from "node:module";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { moduleDataObject as dataObject, moduleText as text, moduleArray as array } from "./external-metadata.ts";
+import { ADAPTER_API } from "./adapter-api.ts";
+import { CONFIGURED_ACP_RESERVED_COMMANDS } from "./configured-acp.ts";
+import { ADAPTERS, assertDefinitionCoherence, assertNativeCapabilityScope, createProjectAdapterCatalog } from "./registry.ts";
+import type { AdapterDefinition, LaunchPlan } from "./registry-types.ts";
+import { configRefusal } from "../hub/config-trust.ts";
+import { realPath } from "../hub/project.ts";
+import { scanModuleSource } from "./external-module-scan.ts";
+
+export interface AdapterModuleDeclaration { readonly path: string; readonly sha256: string }
+interface ModuleConfigLayer { name: string; raw: Record<string, unknown> }
+const MAX_MODULES = 16, MAX_MODULE_BYTES = 2 * 1024 * 1024;
+const ADAPTER_IMPORT = "@staix/agent-hub/adapter";
+class ExternalAdapterRefusal extends Error {}
+const fail = (reason: string): never => { throw new ExternalAdapterRefusal(`external adapter: ${reason}`); };
+const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+export function adapterModuleDeclarations(raw: unknown): readonly AdapterModuleDeclaration[] {
+  if (raw === undefined) return Object.freeze([]);
+  return Object.freeze(array(raw, MAX_MODULES).map(value => {
+    const row = dataObject(value);
+    if (Object.keys(row).some(key => !["path", "sha256"].includes(key))) return fail("unknown module declaration field");
+    const path = text(row.path, 4096), hash = row.sha256;
+    if (typeof hash !== "string" || !/^[a-f0-9]{64}$/i.test(hash)) return fail("a SHA-256 content pin is required");
+    return Object.freeze({ path, sha256: hash.toLowerCase() });
+  }));
+}
+
+/** This reads declarations only. It never imports code, including for reloads and CLI reads. */
+export function readAdapterModuleDeclarations(cwd: string, layers: readonly ModuleConfigLayer[]) {
+  const ignored: string[] = [];
+  let modules: readonly AdapterModuleDeclaration[] = Object.freeze([]);
+  for (const { name, raw } of layers) {
+    if (raw.adapter_modules === undefined) continue;
+    const refusal = name !== "config.local.json" ? "modules are machine-local config.local.json values" : configRefusal(cwd, name);
+    if (refusal) { ignored.push(`adapter_modules in .agenthub/${name} ignored: ${refusal}`); continue; }
+    modules = adapterModuleDeclarations(raw.adapter_modules);
+  }
+  return { modules, ignored };
+}
+
+const inside = (root: string, file: string) => { const part = relative(root, file); return part !== "" && part !== ".." && !part.startsWith(`..${sep}`) && !isAbsolute(part); };
+function regularPath(root: string, file: string) {
+  if (!inside(root, file)) return fail("module must be inside the project root");
+  let at = root;
+  const parts = relative(root, file).split(sep);
+  for (let index = 0; index < parts.length; index++) {
+    at = join(at, parts[index]!);
+    const stat = lstatSync(at);
+    if (stat.isSymbolicLink() || (index < parts.length - 1 ? !stat.isDirectory() : !stat.isFile())) return fail("symlinked or nonregular module path refused");
+  }
+  return lstatSync(file);
+}
+function captureBundle(cwd: string, declaration: AdapterModuleDeclaration): Buffer {
+  const root = realPath(cwd), file = resolve(root, declaration.path);
+  const observed = regularPath(root, file);
+  if ((observed.mode & 0o002) !== 0) return fail("world-writable module refused");
+  if (observed.size > MAX_MODULE_BYTES) return fail("module exceeds the size bound");
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.dev !== observed.dev || before.ino !== observed.ino || (before.mode & 0o002) !== 0) return fail("module changed before capture");
+    const buffer = Buffer.alloc(MAX_MODULE_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) { const n = readSync(fd, buffer, length, buffer.length - length, length); if (!n) break; length += n; }
+    if (length > MAX_MODULE_BYTES) return fail("module exceeds the size bound");
+    const after = fstatSync(fd), current = regularPath(root, file);
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+      || current.dev !== before.dev || current.ino !== before.ino || !inside(root, realPath(file))) return fail("module changed during capture");
+    const bytes = buffer.subarray(0, length);
+    if (digest(bytes) !== declaration.sha256) return fail("content hash mismatch");
+    return bytes;
+  } finally { closeSync(fd); }
+}
+
+/** Conservative code-loading rejection, not an isolation boundary for approved daemon-privileged code. */
+export function assertModuleBundle(source: string): void {
+  for (const dependency of scanModuleSource(source)) {
+    const allowed = dependency.path === ADAPTER_IMPORT || dependency.path !== "bun:test" && dependency.path !== "bun:ffi"
+      && /^(?:node|bun):/.test(dependency.path) && (isBuiltin(dependency.path) || dependency.path === "bun:sqlite");
+    if (dependency.kind !== "import-statement" || !allowed) return fail("only static builtin and public adapter imports are supported");
+  }
+}
+
+/** Resolve scanned SDK imports against this running package, never project node_modules or process.cwd(). */
+async function executableBundle(source: string): Promise<Uint8Array> {
+  const imports = scanModuleSource(source);
+  const compiled = await Bun.build({ entrypoints: ["a4-pin:entry"], target: "bun", format: "esm",
+    plugins: [{ name: "host-bound-adapter-imports", setup(build) {
+      build.onResolve({ filter: /^a4-pin:/ }, () => ({ path: "entry", namespace: "a4-pin" }));
+      build.onLoad({ filter: /.*/, namespace: "a4-pin" }, () => ({ contents: source, loader: "js" }));
+      build.onResolve({ filter: /.*/ }, args => {
+        if (!imports.some(item => item.path === args.path && item.kind === "import-statement")) return fail("unscanned import refused");
+        return { path: args.path === ADAPTER_IMPORT ? new URL("./public.ts", import.meta.url).href : args.path, external: true };
+      });
+    } }],
+  });
+  if (!compiled.success || compiled.outputs.length !== 1) return fail("bundle compilation refused (details withheld)");
+  return new Uint8Array(await compiled.outputs[0]!.arrayBuffer());
+}
+
+function snapshot(value: unknown, depth = 0): unknown {
+  if (depth > 12) return fail("definition nesting exceeds its bound");
+  if (typeof value === "function" || value === null || ["undefined", "string", "number", "boolean"].includes(typeof value)) return value;
+  if (Array.isArray(value)) return Object.freeze(array(value, 128).map(item => snapshot(item, depth + 1)));
+  return Object.freeze(Object.fromEntries(Object.entries(dataObject(value)).map(([key, member]) => [key, snapshot(member, depth + 1)])));
+}
+function only(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  const fields = dataObject(value);
+  if (Object.keys(fields).some(key => !keys.includes(key))) return fail("field is outside the supported external definition subset");
+  return fields;
+}
+export function validateExternalDefinition(raw: unknown): AdapterDefinition {
+  const definition = snapshot(raw) as AdapterDefinition;
+  if (definition.api !== ADAPTER_API) return fail("adapter API mismatch");
+  const reserved = [...ADAPTERS.map(item => item.kind), ...CONFIGURED_ACP_RESERVED_COMMANDS, "user", "hub", "digest", "constructor", "prototype", "__proto__"];
+  if (typeof definition.kind !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(definition.kind) || reserved.includes(definition.kind)
+    || ADAPTERS.some(builtin => definition.kind.startsWith(`${builtin.kind}-`))) return fail("kind is reserved, invalid or collides with a builtin");
+  text(definition.displayName, 256);
+  if (definition.family !== definition.kind || definition.trust?.onPrem !== false || definition.trust.hubSandboxed !== false
+    || definition.defaultOnRoster !== false || definition.optional !== true) return fail("external kinds must retain their own family and optional off-roster cloud trust");
+  if (!Array.isArray(definition.roles) || !definition.roles.length || definition.roles.some(role => !["planner", "implementer", "verifier", "reviewer"].includes(role)) || new Set(definition.roles).size !== definition.roles.length) return fail("unsupported default roles");
+  if (definition.instances !== undefined) return fail("external adapter instances are unsupported in A4");
+  try { assertNativeCapabilityScope(definition); } catch { return fail("fixed-builtin capability refused"); }
+  only(definition, ["api", "kind", "family", "displayName", "transport", "roles", "optional", "defaultOnRoster", "trust", "start", "identity", "permission", "session", "turnEnd", "cli", "display"]);
+  only(definition.trust, ["onPrem", "hubSandboxed"]);
+  const start = only(definition.start, ["forms", "defaultForm", "daemonPort", "launch", "create", "preflight", "version", "conductorStartable", "hubSwitches", "ownedFlags", "exclusiveStartRefusal"]);
+  if (definition.transport !== "acp" || definition.turnEnd !== "adapter" || definition.start.daemonPort !== "acp"
+    || array(definition.start.forms, 1).length !== 1 || definition.start.forms[0] !== "headless" || definition.start.defaultForm !== "headless"
+    || typeof definition.start.conductorStartable !== "boolean" || typeof definition.start.create !== "function" || typeof definition.start.launch !== "function") return fail("A4 requires a headless ACP transport factory and launch plan");
+  for (const field of ["preflight", "version"] as const) if (start[field] !== undefined && typeof start[field] !== "function") return fail("invalid start callback");
+  if (array(start.hubSwitches, 0).length || array(start.ownedFlags, 0).length) return fail("external launch switches are unsupported");
+  if (start.exclusiveStartRefusal !== undefined) text(start.exclusiveStartRefusal, 2048);
+  if (only(definition.identity, ["mcp"]).mcp !== "acp-session") return fail("external ACP identity must be session-bound");
+  const permission = only(definition.permission, ["genericAcp", "grants", "unmanaged"]);
+  if (permission.genericAcp !== undefined) {
+    const policy = only(permission.genericAcp, ["modes", "readOnly"]);
+    if (policy.modes !== undefined) for (const value of Object.values(only(policy.modes, ["ask", "ask-when-needed", "never-ask"]))) text(value, 256);
+    if (policy.readOnly !== undefined) text(policy.readOnly, 256);
+  }
+  if (permission.grants !== undefined) for (const value of Object.values(only(permission.grants, ["ask", "ask-when-needed", "never-ask"]))) text(value, 2048);
+  if (permission.unmanaged !== undefined) text(permission.unmanaged, 2048);
+  const session = only(definition.session, ["idField", "currentId", "resumeById", "launchKind"]);
+  if (session.idField !== "sessionId" || typeof session.currentId !== "function" || session.resumeById !== undefined && typeof session.resumeById !== "boolean") return fail("invalid external session contract");
+  if (session.launchKind !== undefined && session.launchKind !== definition.kind) return fail("external launch kind must match its own kind");
+  const cli = only(definition.cli, ["command", "startWords"]);
+  if (cli.command !== definition.kind || typeof cli.startWords !== "function") return fail("external command must match its own kind");
+  let words: unknown;
+  try { words = definition.cli.startWords("headless"); } catch { return fail("command metadata refused (details withheld)"); }
+  const commandWords = array(words, 1).map(word => text(word, 64));
+  if (commandWords.length !== 1 || commandWords[0] !== definition.kind) return fail("headless command words must name only their bound kind");
+  const palette = only(only(definition.display, ["palette"]).palette, ["fg", "bg"]);
+  for (const color of [palette.fg, palette.bg]) if (typeof color !== "string" || !/^(?:[a-z]{1,32}|#[a-f0-9]{3,8})$/i.test(color)) return fail("invalid external display color");
+  try { assertDefinitionCoherence(definition); } catch { return fail("definition contracts are incoherent"); }
+  const invoke = <T>(name: string, callback: () => T): T => {
+    try { return callback(); } catch { return fail(`${name} refused (details withheld)`); }
+  };
+  return snapshot({ ...definition,
+    start: { ...definition.start,
+      create: (context: Parameters<NonNullable<AdapterDefinition["start"]["create"]>>[0]) => invoke("factory", () => definition.start.create!(context)),
+      launch: (context: Parameters<NonNullable<AdapterDefinition["start"]["launch"]>>[0]): LaunchPlan => invoke("launch", () => {
+        const plan = only(definition.start.launch!(context), ["cmd", "args", "metadata"]);
+        const cmd = text(plan.cmd, 4096), args = array(plan.args, 128).map(arg => text(arg, 4096));
+        const metadata = only(plan.metadata, ["packageEntrypoint", "command", "argv", "env"]);
+        text(metadata.packageEntrypoint, 4096); text(metadata.command, 16384);
+        array(metadata.argv, 129).forEach(arg => text(arg, 4096));
+        if (Object.keys(dataObject(metadata.env)).length) return fail("external native-home overrides are unsupported");
+        return snapshot({ cmd, args, metadata }) as LaunchPlan;
+      }),
+      ...(definition.start.preflight ? { preflight: (context: Parameters<NonNullable<AdapterDefinition["start"]["preflight"]>>[0]) => {
+        try { if (definition.start.preflight!(context) === undefined) return undefined; } catch { /* Never forward module-authored exception/refusal bodies. */ }
+        return "external adapter preflight refused (details withheld)";
+      } } : {}),
+      ...(definition.start.version ? { version: (context: Parameters<NonNullable<AdapterDefinition["start"]["version"]>>[0]) => {
+        try { if (definition.start.version!(context) === undefined) return undefined; } catch { /* Unknown is a refusal for an external native version check. */ }
+        return "external adapter version refused (details withheld)";
+      } } : {}),
+    },
+    session: { ...definition.session,
+      // ponytail: A4 has no verified controlled-recovery driver; bind native session/group restoration receipts before enabling it.
+      recoveryRefusal: () => "external module has no verified controlled-recovery driver; stop it explicitly and restart with its recorded native session id",
+      currentId: (peer: Parameters<AdapterDefinition["session"]["currentId"]>[0]) => {
+      try {
+        const value = definition.session.currentId(peer);
+        return typeof value === "string" && value.trim() && Buffer.byteLength(value) <= 4096 && !/[\p{Cc}\p{Cf}]/u.test(value) ? value : undefined;
+      } catch { return undefined; }
+    } },
+    // UI polls and CLI metadata never execute plugin code to render a headless command.
+    cli: { command: definition.kind, startWords: () => [definition.kind] },
+  }) as AdapterDefinition;
+}
+
+const MODULE_IMPORT_TIMEOUT_MS = 2000;
+async function importVerifiedModule(executable: Uint8Array): Promise<unknown> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    // ponytail: a deadline stops waiting, not privileged module side effects; cancellation needs an isolated host-port engine.
+    return await Promise.race([
+      import(`data:text/javascript;nonce=${randomUUID()};base64,${Buffer.from(executable).toString("base64")}`),
+      new Promise<never>((_resolve, reject) => { timer = setTimeout(() => reject(new ExternalAdapterRefusal("external adapter: module import timed out")), MODULE_IMPORT_TIMEOUT_MS); }),
+    ]);
+  } finally { clearTimeout(timer); }
+}
+
+/** Only daemon startup calls this. Hash-checked bytes, not the mutable source path, reach import(). */
+export interface ExternalAdapterRefusalRecord { readonly index: number; readonly reason: string }
+export async function loadExternalAdapterDefinitions(cwd: string, layers: readonly ModuleConfigLayer[], onRefusal?: (refusal: ExternalAdapterRefusalRecord) => void): Promise<readonly AdapterDefinition[]> {
+  const { modules } = readAdapterModuleDeclarations(cwd, layers);
+  if (!modules.length) return Object.freeze([]);
+  let rawAdapters: unknown;
+  for (const { name, raw } of layers) if (name === "config.local.json" && !configRefusal(cwd, name) && raw.adapters !== undefined) rawAdapters = raw.adapters;
+  const existingKinds = new Set(createProjectAdapterCatalog(rawAdapters).definitions.map(definition => definition.kind));
+  const definitions: AdapterDefinition[] = [];
+  for (const [index, declaration] of modules.entries()) {
+    try {
+      if (configRefusal(cwd, "config.local.json")) return fail("module configuration provenance changed");
+      const local = regularPath(realPath(cwd), join(realPath(cwd), ".agenthub", "config.local.json"));
+      if ((local.mode & 0o002) !== 0) return fail("world-writable module configuration refused");
+      const bytes = captureBundle(cwd, declaration);
+      const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      assertModuleBundle(source);
+      const executable = await executableBundle(source);
+      if (digest(bytes) !== declaration.sha256 || configRefusal(cwd, "config.local.json")) return fail("module pin or provenance changed before import");
+      const imported = await importVerifiedModule(executable);
+      const definition = validateExternalDefinition((imported as { definition?: unknown }).definition);
+      if ([...existingKinds].some(kind => definition.kind === kind || definition.kind.startsWith(`${kind}-`))) return fail("kind collides with a configured adapter namespace");
+      if (definitions.some(item => item.kind === definition.kind)) return fail("duplicate external kind");
+      definitions.push(definition);
+    } catch (error) {
+      const refusal = error instanceof ExternalAdapterRefusal ? error : new ExternalAdapterRefusal("external adapter: module could not be verified or loaded (details withheld)");
+      if (!onRefusal) throw refusal;
+      onRefusal(Object.freeze({ index, reason: refusal.message }));
+    }
+  }
+  return Object.freeze(definitions);
+}
+

package/src/adapters/pi.ts

@@ -157,6 +157,8 @@ export class PiPeer extends BasePeer {
   get sessionGeneration(): string | undefined {
     return this.ownerClaimed && this.ownerPid && this.ownerSignature ? `${this.ownerPid}:${this.ownerSignature}:${this.sessionId ?? ""}` : undefined;
   }
+  // ponytail: retain Pi's owner/session-only checkpoint fence in this slice; a later native-proof port can strengthen it.
+  readonly checkpointUsesSessionGeneration = false;
 
   recoveryMetadata(): Record<string, unknown> {
     const exists = !!this.sessionFile && existsSync(this.sessionFile);

package/src/adapters/public.ts

@@ -0,0 +1,7 @@
+export { ADAPTER_API } from "./adapter-api.ts";
+export { AcpPeer } from "./acp.ts";
+export type { AcpOptions, PermissionRequest, PermissionOption } from "./acp.ts";
+export { BasePeer } from "../hub/peers.ts";
+export type { PeerAdapter, DeliveryReceipt } from "../hub/peers.ts";
+export type { Envelope, PeerId, PeerState } from "../hub/envelope.ts";
+export type * from "./registry-types.ts";

package/src/adapters/registry-types.ts

@@ -16,6 +16,9 @@ import type { LocalOptions } from "./local-worker.ts";
 import type { PiOptions } from "./pi.ts";
 import type { ClaudePrintOptions } from "./claude-print.ts";
 
+import type { BuiltinCliEntry } from "./definitions/native-cli-entry-types.ts";
+import type { NativePreviewBuilder } from "./definitions/native-cli-preview-common.ts";
+
 export type StartForm = "tui" | "headless";
 export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print" | "reviewer-print";
 
@@ -272,8 +275,14 @@ export interface AdapterDefinition {
     validateEffective?(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void;
   };
   capabilities?: { manifest?(peer: PeerAdapter): Promise<CapabilityManifest>; watch?: boolean };
+  /** Stable host projection order and planner eligibility, independent of default task roles. */
+  projection?: { roleRank?: number; startRank?: number; helpRank?: number; plannerEligible?: boolean };
   cli: {
     command: string;
+    /** Fixed builtin CLI ports; project definitions cannot supply these callbacks. */
+    entry?: Readonly<Omit<BuiltinCliEntry, "command">>;
+    preview?: NativePreviewBuilder;
+    usage?: readonly (readonly [usage: string, description: string])[];
     /** Configuration leaves that select this peer's next native launch command or provider profile. */
     launchConfigKeys?: readonly string[];
     /** Restrictions only; core identity remains authoritative. */
@@ -299,6 +308,7 @@ export type KindMap = Readonly<Record<string, { readonly kind: string; readonly
 /** Immutable per-project resolver; exported globals remain builtin-only. */
 export interface ProjectAdapterCatalog {
   readonly definitions: readonly AdapterDefinition[];
+  readonly externalDefinitions: readonly AdapterDefinition[];
   definitionOf(id: string, instances?: KindMap): AdapterDefinition | undefined;
   kindOf(id: string, instances?: KindMap): string | undefined;
   familyOf(id: string, instances?: KindMap): string | undefined;

package/src/adapters/registry.ts

@@ -11,14 +11,9 @@ import type { AdapterDefinition, KindMap, ProjectAdapterCatalog } from "./regist
 import { types } from "node:util";
 
 export type * from "./registry-types.ts";
-export const ADAPTER_API = 1;
+import { ADAPTER_API } from "./adapter-api.ts";
+export { ADAPTER_API };
 
-/** Ordered compatibility projections stay typed independently of definition implementation inference. */
-export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
-export const OPTIONAL_PEERS = ["qwen", "jcode", "agy"] as const;
-export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
-export const START_MODE_PEERS = ["pi", "codex", "kimi", "jcode"] as const;
-export const OFFICE_PEER_ORDER: readonly string[] = KNOWN_PEERS;
 
 
 function immutable<T>(value: T, seen = new WeakSet<object>()): T {
@@ -38,6 +33,31 @@ export const ADAPTERS: readonly AdapterDefinition[] = immutable([
   ...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind === "jcode"),
   AGY_DEFINITION,
 ]);
+export interface AdapterLists {
+  readonly KNOWN_PEERS: readonly string[]; readonly OPTIONAL_PEERS: readonly string[]; readonly SUPPORTED_PEERS: readonly string[];
+  readonly START_MODE_PEERS: readonly string[]; readonly ROLE_ORDER: readonly string[]; readonly HELP_ORDER: readonly string[]; readonly PLANNER_PEERS: readonly string[];
+}
+/** Pure builtin projections. Unranked definitions retain their source order after ranked definitions. */
+export function deriveAdapterLists(definitions: readonly AdapterDefinition[]): AdapterLists {
+  const ordered = (field: "roleRank" | "startRank" | "helpRank", eligible = (_definition: AdapterDefinition) => true) => definitions
+    .map((definition, index) => ({ definition, index })).filter(({ definition }) => eligible(definition))
+    .sort((left, right) => {
+      const a = left.definition.projection?.[field], b = right.definition.projection?.[field];
+      if (a === undefined) return b === undefined ? left.index - right.index : 1;
+      if (b === undefined) return -1;
+      return a - b || left.index - right.index;
+    }).map(({ definition }) => definition.kind);
+  const KNOWN_PEERS = definitions.filter(definition => !definition.optional).map(definition => definition.kind);
+  const OPTIONAL_PEERS = definitions.filter(definition => definition.optional).map(definition => definition.kind);
+  return immutable({ KNOWN_PEERS, OPTIONAL_PEERS, SUPPORTED_PEERS: [...KNOWN_PEERS, ...OPTIONAL_PEERS],
+    START_MODE_PEERS: ordered("startRank", definition => definition.start.forms.includes("tui") && definition.start.forms.includes("headless")),
+    ROLE_ORDER: ordered("roleRank"), HELP_ORDER: ordered("helpRank"),
+    PLANNER_PEERS: definitions.filter(definition => definition.projection?.plannerEligible === true).map(definition => definition.kind),
+  });
+}
+export const { KNOWN_PEERS, OPTIONAL_PEERS, SUPPORTED_PEERS, START_MODE_PEERS, ROLE_ORDER, PLANNER_PEERS } = deriveAdapterLists(ADAPTERS);
+export const OFFICE_PEER_ORDER: readonly string[] = KNOWN_PEERS;
+
 // Unavailable declarations are metadata, not supported native peers or launchers.
 const declarationOnlyDefinitions: readonly AdapterDefinition[] = immutable([]);
 const definitions = new Map<string, AdapterDefinition>();
@@ -101,14 +121,21 @@ export function familyOf(id: string, instances?: KindMap): string | undefined {
 }
 
 /** Compile one captured, host-trusted declaration set; never register native policy globally. */
-export function createProjectAdapterCatalog(rawAdapters?: unknown): ProjectAdapterCatalog {
+export function createProjectAdapterCatalog(rawAdapters?: unknown, externalDefinitions: readonly AdapterDefinition[] = []): ProjectAdapterCatalog {
   const configured = configuredAcpDefinitions(rawAdapters, [...definitions.keys()]);
   for (const definition of configured) { assertDefinitionCoherence(definition); assertNativeCapabilityScope(definition); }
-  const entries = Object.freeze([...ADAPTERS, ...configured]);
-  const catalog = new Map([...definitions, ...configured.map(definition => [definition.kind, definition] as const)]);
+  const seen = new Set([...definitions.keys(), ...configured.map(item => item.kind)]);
+  for (const definition of externalDefinitions) {
+    if (definition.api !== ADAPTER_API || seen.has(definition.kind)) throw new Error("external adapter kind or API collision");
+    assertDefinitionCoherence(definition); assertNativeCapabilityScope(definition);
+    seen.add(definition.kind);
+  }
+  const external = immutable([...externalDefinitions]);
+  const entries = Object.freeze([...ADAPTERS, ...configured, ...external]);
+  const catalog = new Map([...definitions, ...[...configured, ...external].map(definition => [definition.kind, definition] as const)]);
   const kindOf = (id: string, instances?: KindMap): string | undefined => catalog.has(id) ? id : typeof id === "string" ? declaredKind(id, instances, catalog) : undefined;
   const definitionOf = (id: string, instances?: KindMap): AdapterDefinition | undefined => resolvedDefinition(id, kindOf(id, instances), instances, catalog);
-  return Object.freeze({ definitions: entries, kindOf, definitionOf,
+  return Object.freeze({ definitions: entries, externalDefinitions: external, kindOf, definitionOf,
     familyOf: (id: string, instances?: KindMap) => definitionOf(id, instances)?.family,
     isSupportedPeer: (id: unknown, instances?: KindMap): id is string => {
       if (typeof id !== "string") return false;
@@ -119,8 +146,7 @@ export function createProjectAdapterCatalog(rawAdapters?: unknown): ProjectAdapt
 }
 
 /** Compatibility projection order is observable in default role maps and planner selection. */
-const ROLE_ORDER = ["claude", "codex", "kimi", "local", "pi", "qwen", "jcode", "agy"] as const;
-export const PLANNER_PEERS = ["claude", "codex", "kimi", "qwen", "jcode"] as const;
+
 
 /** Callers own their role arrays, independent of immutable native policy. */
 export function defaultPeerRoles(includeOptional = false): Record<string, string[]> {
@@ -159,6 +185,12 @@ export function assertDefinitionCoherence(definition: AdapterDefinition): void {
   if (definition.turnEnd === "native-hook" && definition.transport !== "claude-channel" && !definition.hooks?.factsHook) {
     fail("turnEnd", "native-hook requires the Claude transport or a native factsHook");
   }
+  const projection = definition.projection;
+  if (projection !== undefined) {
+    if (!projection || typeof projection !== "object" || Array.isArray(projection) || Object.keys(projection).some(key => !["roleRank", "startRank", "helpRank", "plannerEligible"].includes(key))) fail("projection", "invalid projection metadata");
+    for (const field of ["roleRank", "startRank", "helpRank"] as const) if (projection[field] !== undefined && (typeof projection[field] !== "number" || !Number.isFinite(projection[field]))) fail(`projection.${field}`, "rank must be finite");
+    if (projection.plannerEligible !== undefined && typeof projection.plannerEligible !== "boolean") fail("projection.plannerEligible", "boolean required");
+  }
   const attach = definition.attach, pullOnly = attach?.pullOnlyForms;
   if (pullOnly !== undefined) {
     if (!Array.isArray(pullOnly) || pullOnly.some(form => !definition.start.forms.includes(form))) fail("attach.pullOnlyForms", "each pull-only form must be a supported start form");
@@ -199,9 +231,13 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["session.crashIdentity", declared(definition.session, "crashIdentity")],
     ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
     ["routing", definition.routing !== undefined],
+    ["projection", definition.projection !== undefined],
     ["reviewerVariant", definition.reviewerVariant !== undefined],
     ["reviewer", definition.reviewer !== undefined],
     ["hooks.factsHook", declared(definition.hooks, "factsHook")],
+    ["cli.entry", declared(definition.cli, "entry")],
+    ["cli.preview", declared(definition.cli, "preview")],
+    ["cli.usage", declared(definition.cli, "usage")],
   ];
   const field = restricted.find(([, present]) => present)?.[0];
   if (field) throw new Error(`${field} is restricted to fixed builtin adapter definitions`);
@@ -236,8 +272,8 @@ export function builtinPreviewOf(id: string) {
 /** Fixed builtin doctor metadata and pure observed-value projections; the CLI retains all probe effects. */
 export { DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "./definitions/native-cli-doctor.ts";
 
-/** Internal fixed builtin CLI entries; public AdapterDefinition and NativeHooks expose no execution extension. */
-export const BUILTIN_CLI_ENTRIES = Object.freeze(builtinCliEntries.map(entry => {
+/** Definition-owned CLI entries are restricted to fixed builtins, never config or external execution extensions. */
+export const BUILTIN_CLI_ENTRIES = Object.freeze(builtinCliEntries(ADAPTERS).map(entry => {
   const definition = definitionOf(entry.command);
   if (!definition) throw new Error("builtin CLI entry has no adapter definition");
   return Object.freeze({ ...entry, definition });

package/src/cli/help.ts

@@ -1,3 +1,4 @@
+import { ADAPTERS, deriveAdapterLists, type AdapterDefinition } from "../adapters/registry.ts";
 import { VERSION } from "../version.ts";
 import { paint, wrap, type Span } from "./console-state.ts";
 
@@ -26,9 +27,10 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub sdlc status [task] | explain <task> | export <task> | record <task> <receipt-json>", "read head-bound lifecycle gates and the next actor/action (person only)"],
     ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...]", "read-only merge and release evidence (person only)"],
     ["ahub sdlc accept <task> --issue <n> [--repo owner/repo]", "accept the task's spec issue at its current body; build entry needs it in enforce (person only)"],
-    ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N --ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
+    ["ahub sdlc accept-departure <task> <head> <reason...>", "accept current plan departures on that exact PR head (person only)"],
+    ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N] [--ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
     ["ahub sdlc train report|configure|cut <release-id> [revision] [json]", "plan a release and freeze its approved scope after resource/quota admission"],
-    ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason>", "assign approved/in-flight work without changing execution"],
+    ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason...>", "assign approved/in-flight work without changing execution"],
     ["ahub sdlc costs [owner/repo]", "read bounded planner cost metrics for linked merged PRs"],
     ["ahub backlog groom | return <task> <revision> <reason...>", "read grooming findings or return accepted untouched work to backlog (planner/person)"],
     ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
@@ -49,15 +51,6 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ]],
   ["Agents", [
     ["ahub <configured-kind> [--mode headless] [--as <instance>] [--session-id <id>] [--print-command | --dry-run]", "start a trusted config.local.json ACP kind (default off roster); native argv is withheld in previews"],
-    ["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"],
-    ["ahub codex [--print-command] [--unattended] [args...]", "start the Codex adapter and attach the TUI"],
-    ["ahub kimi [--print-command] [--mode tui|headless] [--model <alias>]", "default: Kimi's own TUI, pull-only via hub_inbox; no push, steer, watchdog, console approvals or automatic quota handoff. Select headless for ACP"],
-    ["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"],
-    ["ahub agy [--print-command | --dry-run] [args...]", "optional Antigravity CLI 1.4.x TUI (1.4.2 verified) in this terminal (roster.agy, default off): pull-only via hub_inbox, implementer/verifier only; native permissions unmanaged, no hub sandbox"],
-    ["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", "start optional Qwen Code 0.25.0 ACP (roster.qwen, default off)"],
-    ["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"],
-    ["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
-    ["ahub claude|codex|kimi|qwen|pi|local --as <instance> [options...]", "start an extra instance of that kind declared under instances in .agenthub/config.local.json"],
     ["ahub role list [--group <group>] | show <id>", "read bounded catalog guidance with layer and content hash"],
     ["ahub role assign <peer> <id> | clear <peer> [<id>]", "person only: add or clear catalog guidance, applied at the next peer start"],
     ["ahub stop <peer>", "human only: stop a hub-owned headless peer; end TUI agents in their terminals"],
@@ -71,7 +64,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]", "human only: inspect or set a running peer mode; never-ask requires --yes; config never-ask waits for console y"],
     ["ahub permit <id> <option>", "answer a permission request shown by tail (\"deny\" cancels)"],
     ["ahub roster [--json] [--color=auto|always|never]", "human only: every known peer, participation, start mode and retained work"],
-    ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff"],
+    ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff; remove also deletes the roster key of an instance no longer declared"],
     ["ahub settings [list] [--json] | get <key> [--json]", "human only: the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
     ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "human only: change or reload validated settings, written to .agenthub/config.local.json or routing.local.toml (never a tracked file); --preview shows the effect and saves nothing; undo puts back the last write"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
@@ -94,7 +87,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub task unassign <id> [--role owner|reviewer] [--revision N]", "person only: remove the owner/reservation or reviewer without routing a replacement or stopping native work"],
     ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]", "person only: close obsolete work with a reason; retain its history without stopping native work or releasing dependents"],
     ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned [--created <time>]", "your later verdict on an approved task, kept in the research records (research must be on)"],
-    ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>]", "give a review verdict on a task"],
+    ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>] [--findings <json>]", "give a review verdict on a task"],
     ["ahub review brief <id>", "print the review brief of a task's commit: reviewable and excluded files, rules, coverage to account for"],
     ["ahub route explain <id>", "why a task went where it went, its reserved owner included"],
     ["ahub route explain --class <c> <title...>", "what would happen to such a task now"],
@@ -145,7 +138,18 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub manager", "internal: the dashboard manager process that ahub ui --all starts"],
   ]],
 ];
-export const HELP: readonly HelpEntry[] = SECTIONS.flatMap(([section, rows]) => rows.map(([usage, description]) => ({ section, usage, description })));
+export function helpEntries(definitions: readonly AdapterDefinition[] = ADAPTERS): readonly HelpEntry[] {
+  const byKind = new Map(definitions.map(definition => [definition.kind, definition]));
+  const order = deriveAdapterLists(definitions).HELP_ORDER;
+  const native = order.flatMap(kind => byKind.get(kind)?.cli.usage ?? []);
+  const instanceKinds = order.filter(kind => byKind.get(kind)?.instances !== undefined);
+  const instances: readonly [string, string] = [`ahub ${instanceKinds.join("|")} --as <instance> [options...]`, "start an extra instance of that kind declared under instances in .agenthub/config.local.json"];
+  return SECTIONS.flatMap(([section, rows]) => {
+    const entries: readonly (readonly [string, string])[] = section === "Agents" ? [rows[0]!, ...native, ...(instanceKinds.length ? [instances] : []), ...rows.slice(1)] : rows;
+    return entries.map(([usage, description]) => ({ section, usage, description }));
+  });
+}
+export const HELP = helpEntries();
 
 const COMMAND = /^ahub (-{0,2}[a-z][a-z-]*(?: ?\| ?-{0,2}[a-z][a-z-]*)*)/;
 /** The command words a usage documents: `ahub pause|resume <peer>` documents pause and resume. */
@@ -159,9 +163,10 @@ const DESCRIPTION = 34;
  * (80 to 100 columns). A usage too long for that column puts its description on the next line.
  * With a command, only its entries; an unknown command renders nothing.
  */
-export function renderHelp(columns: number, color: boolean, command?: string): string {
+export function renderHelp(columns: number, color: boolean, command?: string, definitions?: readonly AdapterDefinition[]): string {
   const width = Math.min(100, Math.max(80, columns || 80));
-  const entries = command === undefined ? HELP : HELP.filter(entry => helpCommands(entry).includes(command));
+  const model = definitions === undefined ? HELP : helpEntries(definitions);
+  const entries = command === undefined ? model : model.filter(entry => helpCommands(entry).includes(command));
   const lines: Span[][] = command === undefined ? wrap(`agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one project directory`, width, 0).map(text => [{ text }]) : [];
   let section = "";
   for (const entry of entries) {

package/src/cli/identity.ts

@@ -21,7 +21,7 @@ export function liveTestRefusal(command: string, args: readonly string[], contex
     || (command === "backlog" && sub !== "list") || (command === "release" && !["list", "show"].includes(sub ?? ""))
     || (command === "memory" && sub !== "graph")
     || (command === "recovery" && (sub === "reattach" || sub === "dispose" && context.repairedFresh === true))
-    || (command === "board" && args[0] === "import") || (command === "sdlc" && (args[0] === "record" || args[0] === "accept"))
+    || (command === "board" && args[0] === "import") || (command === "sdlc" && (args[0] === "record" || args[0] === "accept" || args[0] === "accept-departure"))
     || (command === "bench" && args.find(arg => arg !== "--json") === "run") || command === "pet";
 }
 

package/src/cli/main.ts

@@ -3,6 +3,7 @@ import { claudePeer as defaultChannelPeer } from "../hub/claude-state.ts";
 import { effectiveInstanceRoles } from "../hub/instances.ts";
 import { resolveInstanceExecutionCwd } from "../hub/instance-execution.ts";
 import { readInstanceRoleConfig, readInstanceConfig, type InstanceRoleConfig } from "../hub/instance-config.ts";
+import { staleInstanceKey } from "../hub/roster.ts";
 import { parseConfiguredAcpArguments, runConfiguredAcpEntry, requireActiveConfiguredAcp } from "./configured-acp-entry.ts";
 import type { NativeCliEntryContext } from "../adapters/definitions/native-cli-entry-types.ts";
 import { BUILTIN_CLI_ENTRIES, createProjectAdapterCatalog, definitionOf, DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "../adapters/registry.ts";
@@ -1230,6 +1231,17 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (!flags.rest.length || (scope === undefined) !== (reviewers === undefined)) fail("plan-review needs a reason and both --review and --reviewers when supplying review scope");
       return console.log(await taskOp("hub_plan_review", { id, revision, reason: flags.rest.join(" "), ...(scope !== undefined ? { review: { scope, reviewers: Number(reviewers) } } : {}), ...(flags.one["--ci"] !== undefined ? { ci: flags.one["--ci"] } : {}) }));
     }
+    if (sub === "accept-departure") {
+      const head = args[2], rawReason = args.slice(3).join(" "), reason = rawReason.trim();
+      if (!Number.isSafeInteger(id) || id! <= 0 || typeof head !== "string" || !/^[a-f0-9]{40}$/.test(head) || !reason || rawReason.length > 2048) fail("usage: ahub sdlc accept-departure <task> <head> <reason...>");
+      const hub = await connect();
+      try {
+        const reply = await hub.request({ t: "sdlc", op: "accept-departure", id, head, reason }, 30_000);
+        if (!reply.ok) fail(reply.error);
+        console.log(`task #${id}: plan departure accepted for the reviewed head`);
+      } finally { hub.close(); }
+      return;
+    }
     if (sub === "accept") {
       // #481 S1: the person accepts the task's spec issue at its current body; agent shells are refused before this runs.
       const flags = takeFlags(args.slice(2), ["--issue", "--repo"], []);
@@ -1315,10 +1327,15 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (args.length !== 2 || !/^\d+$/.test(args[1]!)) fail("usage: ahub review brief <task id>");
       return console.log(await taskOp("review_brief", { id: Number(args[1]) }));
     }
-    const { one, many, rest } = takeFlags(args, ["--head"], ["--unmet"]);
+    const { one, many, rest } = takeFlags(args, ["--head", "--findings"], ["--unmet"]);
     const [id, verdict, ...note] = rest;
-    if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]... | ahub review brief <id>");
-    console.log(await taskOp("hub_review", { id: Number(id), verdict, ...(one["--head"] ? { head: one["--head"] } : {}), note: note.join(" "), ...(many["--unmet"]?.length ? { unmet: many["--unmet"] } : {}) }));
+    if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>] [--findings <json>] | ahub review brief <id>");
+    let findings: unknown;
+    if (one["--findings"] !== undefined) {
+      try { findings = JSON.parse(one["--findings"]); } catch { fail("--findings must be a JSON array"); }
+      if (!Array.isArray(findings)) fail("--findings must be a JSON array");
+    }
+    console.log(await taskOp("hub_review", { id: Number(id), verdict, ...(one["--head"] ? { head: one["--head"] } : {}), note: note.join(" "), ...(findings === undefined ? {} : { findings }), ...(many["--unmet"]?.length ? { unmet: many["--unmet"] } : {}) }));
   },
 
   remember: async () => console.log(await taskOp("hub_remember", { text: freeText(args, "ahub remember <text>") })),
@@ -1390,7 +1407,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   roster: async () => {
     const options = outputOptions(), flags = args.filter(arg => arg.startsWith("--")), positional = outputArguments().filter(arg => arg !== "--yes" && arg !== "--now");
     const [sub = "list", peer, ...extra] = positional;
-    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !peerDefinition(peer)) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
+    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !peerDefinition(peer) && !(sub === "remove" && typeof peer === "string" && staleInstanceKey(peer, projectCatalog))) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
     const hub = await connect();
     try {
       requireNamedPeerFeature(hub, peer);
@@ -1400,7 +1417,8 @@ const commands: Record<string, () => Promise<void> | void> = {
         if (!Array.isArray(view.roster)) fail("upgrade the running hub to use ahub roster");
         return options.json ? console.log(JSON.stringify(view.roster, null, 2)) : printOutput(renderRoster(view.roster, options.columns), options.color);
       }
-      const key = `roster.${peer}`, value = sub === "add";
+      // A key whose instance is no longer declared is deleted (null), never set to false: there is no peer left for it to switch off (#225).
+      const key = `roster.${peer}`, stale = sub === "remove" && !peerDefinition(peer) && staleInstanceKey(peer!, projectCatalog), value = stale ? null : sub === "add";
       const preview = await request({ t: "settings_preview", key, value });
       printOutput((preview.lines ?? []).map((text: string) => [{ text }]), options.color);
       if (sub === "remove" && !flags.includes("--yes")) {

package/src/cli/upgrade-labels.ts

@@ -20,7 +20,7 @@ export function operationLines(op: RecoveryOperation, runner: number | "unknown"
   const held = runner === "unknown" ? "; whether a runner holds it cannot be read" : runner ? `; runner ${runner} is working` : op.phase === "running" ? "; no runner holds it (the last one stopped mid-step)" : "";
   const lines = [`${op.plan.kind} to ${op.plan.version}: operation ${op.id}`, `  ${op.phase} at "${stepLabel(op.step)}", updated ${ago(now - op.updatedAt)} ago${held}`];
   for (const p of op.projects) {
-    const effects = Object.entries(p.terminals).map(([key, value]) => key.startsWith("restored:") ? `${key} ${restoreReceiptStatus(value)}` : value === "pending" || value === "failed" ? `${key} ${value}` : key);
+    const effects = Object.entries(p.terminals).map(([key, value]) => key.startsWith("restored:") ? `${key} ${restoreReceiptStatus(value, { authority: "historical" })}` : value === "pending" || value === "failed" ? `${key} ${value}` : key);
     lines.push(`  ${p.id}  ${p.phase}${effects.length ? `  (${effects.join(", ")})` : ""}${p.restarts?.length ? `  restarts ${p.restarts.length}` : ""}`);
   }
   // The error ends with the commands status would print; the menu below offers them instead.

package/src/cli/upgrade-presentation.ts

@@ -76,7 +76,7 @@ export function renderOperation(op: RecoveryOperation, runner: number | "unknown
       if (key.startsWith("restored:")) {
         let outcome = "recorded outcome unavailable";
         try {
-          const state = restoreReceiptStatus(value);
+          const state = restoreReceiptStatus(value, { authority: "historical" }); // display only: a revoked declaration must not hide the receipt (#225)
           outcome = state === "done" ? "session restored" : state === "failed" ? "session restoration needs attention" : state.startsWith("waiting:") ? "waiting for the recorded session to attach" : "session restoration is pending";
         } catch { /* Malformed historical metadata is unknown, never successful. */ }
         output.push(...lines(`  ${key.slice("restored:".length)}: ${outcome}`, "muted", options));