@staix/agent-hub 0.12.31 → 0.12.33

package/src/hub/deferred-hub.ts

@@ -0,0 +1,60 @@
+import { HUB, MAX_HOP, type Envelope } from "./envelope.ts";
+
+/** ponytail: cap recovery at 2048 unpublished hub originals; replace with a paged durable outbox if measured recovery workloads exceed it. */
+export const MAX_DEFERRED_HUB = 2048;
+
+/** Refuses admission without dropping already accepted deferred work. */
+export class RecoveryDeferredHubError extends Error {
+  readonly code = "recovery_deferred_hub";
+  constructor(message = "recovery deferred hub notice limit reached; release or abort recovery before publishing more notices") {
+    super(message);
+    this.name = "RecoveryDeferredHubError";
+  }
+}
+
+/** Journal-less restore uses the same bounded core envelope shape as durable deferred work. */
+export function validateDeferredEnvelope(value: unknown, name: string): Envelope {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new RecoveryDeferredHubError(`${name} must be an envelope`);
+  const env = value as Record<string, unknown>;
+  const text = (value: unknown, max: number) => typeof value === "string" && value.length > 0 && value.length <= max;
+  if (!text(env.id, 256) || !text(env.trace, 256) || env.from !== HUB ||
+      typeof env.body !== "string" || env.body.length > 1_000_000 ||
+      !Number.isSafeInteger(env.hop) || (env.hop as number) < 0 || (env.hop as number) > MAX_HOP ||
+      !Number.isSafeInteger(env.ts) || (env.ts as number) < 0 ||
+      !["chat", "task", "review", "status", "budget", "presence"].includes(env.kind as string) ||
+      !["important", "status", "fyi"].includes(env.priority as string) ||
+      (!Array.isArray(env.to) || env.to.length > 256 || !env.to.every(peer => text(peer, 256))) ||
+      (env.private !== undefined && typeof env.private !== "boolean"))
+    throw new RecoveryDeferredHubError(`${name} is invalid`);
+  if (env.refs !== undefined) {
+    if (!env.refs || typeof env.refs !== "object" || Array.isArray(env.refs)) throw new RecoveryDeferredHubError(`${name}.refs is invalid`);
+    const refs = env.refs as Record<string, unknown>;
+    for (const key of ["repo", "branch", "commit", "task"])
+      if (refs[key] !== undefined && !text(refs[key], 4096)) throw new RecoveryDeferredHubError(`${name}.refs.${key} is invalid`);
+    if (refs.paths !== undefined && (!Array.isArray(refs.paths) || refs.paths.length > 256 || !refs.paths.every(path => text(path, 4096))))
+      throw new RecoveryDeferredHubError(`${name}.refs.paths is invalid`);
+  }
+  return value as Envelope;
+}
+
+/** Callers keep their existing envelope validation; this leaf checks deferred-only invariants. */
+export function validateDeferredHub(
+  value: unknown,
+  envelope: (value: unknown, name: string) => Envelope = validateDeferredEnvelope,
+  occupied: ReadonlySet<string> = new Set(),
+  name = "bus.deferredHub",
+): Envelope[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_DEFERRED_HUB)
+    throw new RecoveryDeferredHubError(`${name} must be an array of at most ${MAX_DEFERRED_HUB} hub envelopes`);
+  const ids = new Set<string>();
+  return value.map((item, index) => {
+    validateDeferredEnvelope(item, `${name}[${index}]`);
+    const env = envelope(item, `${name}[${index}]`);
+    if (env.from !== HUB) throw new RecoveryDeferredHubError(`${name}[${index}] is not hub-originated`);
+    if (ids.has(env.id) || occupied.has(env.id)) throw new RecoveryDeferredHubError(`${name}[${index}] repeats an accepted envelope id`);
+    ids.add(env.id);
+    return env;
+  });
+}

package/src/hub/delivery-journal.ts

@@ -6,6 +6,7 @@ import { HUB, USER, type Envelope, type Kind } from "./envelope.ts";
 import { heldDeliveryHints } from "./delivery-hints.ts";
 import { processLiveness } from "../pi/process-signature.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { validateDeferredHub } from "./deferred-hub.ts";
 
 export type JournalDeliveryState =
   | "queued"
@@ -167,6 +168,11 @@ function validateBus(value: unknown, name = "bus"): BusSnapshot {
     list(b.manualPaused, `${name}.manualPaused`, 4096).forEach((id) =>
       text(id, `${name}.manualPaused[]`, 256),
     );
+  const occupied = new Set<string>([
+    ...(b.seen as Envelope[]).map(env => env.id),
+    ...Object.values(queues).flatMap(items => (items as Envelope[]).map(env => env.id)),
+  ]);
+  validateDeferredHub(b.deferredHub, validateEnvelope, occupied, `${name}.deferredHub`);
   if (b.journal !== undefined) fail("nested journal snapshot is invalid");
   return b as unknown as BusSnapshot;
 }

package/src/hub/events.ts

@@ -14,9 +14,9 @@ export const EVENTS_SCHEMA = 1;
  */
 export type HubEvent =
   | { type: "permission_mode"; peer: string; from: import("./permission-mode.ts").PermissionMode; to: import("./permission-mode.ts").PermissionMode }
-  /** A settings change (#269): the registry key, the value in force before and after (closed words, ids or booleans, never free text) and where it came from. */
   | { type: "role"; peer?: string; task?: number; actor: string; stage: "prepared" | "assigned"; roles: { id: string; layer: "shipped" | "project"; hash: string }[] }
-  | { type: "settings"; key: string; from: import("./settings.ts").SettingValue; to: import("./settings.ts").SettingValue; source: "dashboard" | "terminal"; undo?: boolean }
+  /** A settings change (#269): the registry key, the bounded registry values before/after and their source; an optional person reason is sanitized and capped at 400 UTF-8 bytes. */
+  | { type: "settings"; key: string; from: import("./settings.ts").SettingValue; to: import("./settings.ts").SettingValue; source: "dashboard" | "terminal"; undo?: boolean; reason?: string }
   | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }

package/src/hub/manager.ts

@@ -155,7 +155,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
           return { ok: true };
         }
         // The settings actions (#269) reach the project hub as an ordinary session's: this dashboard opens no settings session.
-        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
+        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
         client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
         const deliveryRead = input.action === "sdlc_queue" || input.action === "sdlc_release";
         let nominalMs = 10_000;

package/src/hub/peer-catalog.ts

@@ -1,4 +1,8 @@
-/** Native peers the hub knows; membership checks share this list. */
+import { definitionOf } from "../adapters/registry.ts";
+
+// ponytail: older staged coordinators read these literal declarations to probe target support.
+// A2 replaces that source probe with a published capability before deleting the compatibility exports.
+/** Native peers the hub knows; membership checks share the registry. */
 export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
 /** Optional production peers are added explicitly; legacy defaults remain stable. */
 export const OPTIONAL_PEERS = ["qwen", "jcode"] as const;
@@ -6,25 +10,18 @@ export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
 export type KnownPeer = typeof SUPPORTED_PEERS[number];
 
 export const isKnownPeer = (value: unknown): value is KnownPeer =>
-  typeof value === "string" && (KNOWN_PEERS as readonly string[]).includes(value);
+  typeof value === "string" && !!definitionOf(value) && !definitionOf(value)!.optional;
 
 export const isSupportedPeer = (value: unknown): value is KnownPeer =>
-  typeof value === "string" && (SUPPORTED_PEERS as readonly string[]).includes(value);
+  typeof value === "string" && !!definitionOf(value);
 
 // Policy metadata, not a membership list. Preserve DEFAULT_ROLES' existing key order.
-const PEER_ROLES: Record<KnownPeer, readonly string[]> = {
-  claude: ["planner", "reviewer"],
-  codex: ["implementer"],
-  kimi: ["implementer", "verifier"],
-  local: ["implementer", "verifier"],
-  pi: ["implementer", "verifier"],
-  qwen: ["implementer", "verifier"],
-  jcode: ["implementer", "verifier"],
-};
+const ROLE_ORDER: readonly KnownPeer[] = ["claude", "codex", "kimi", "local", "pi", "qwen", "jcode"];
 
 /** Each caller owns its role arrays; changing a project's defaults cannot change another's. */
 export function defaultPeerRoles(includeOptional = false): Record<string, string[]> {
-  return Object.fromEntries(Object.entries(PEER_ROLES).filter(([peer]) => includeOptional || !(OPTIONAL_PEERS as readonly string[]).includes(peer)).map(([peer, roles]) => [peer, [...roles]]));
+  return Object.fromEntries(ROLE_ORDER.filter(peer => includeOptional || !definitionOf(peer)!.optional)
+    .map(peer => [peer, [...definitionOf(peer)!.roles]]));
 }
 
 /** #455: who may hold the planner role, in the order automatic assignment tries them; the hub-sandboxed pi and local never plan. */

package/src/hub/peers.ts

@@ -44,18 +44,28 @@ export abstract class BasePeer implements PeerAdapter {
   onDelivery?: (receipt: DeliveryReceipt) => void;
   private _state: PeerState = "offline";
   private timer: ReturnType<typeof setTimeout> | undefined;
+  private nextWatchdogMs: number | undefined;
 
   constructor(
     readonly id: PeerId,
-    protected readonly watchdogMs = DEFAULT_WATCHDOG_MS,
+    protected watchdogMs = DEFAULT_WATCHDOG_MS,
   ) {}
 
   get state(): PeerState {
     return this._state;
   }
 
+  /** Keep the active turn's inactivity bound; a changed setting belongs to the next busy turn. */
+  configureWatchdog(ms: number): void {
+    if (!Number.isFinite(ms) || ms <= 0 || ms > 2_147_483_647) throw new Error("invalid watchdog interval");
+    this.nextWatchdogMs = ms;
+  }
+
   protected setState(next: PeerState): void {
-    if (next === "busy") this.touch();
+    if (next === "busy") {
+      if (this._state !== "busy" && this.nextWatchdogMs !== undefined) this.watchdogMs = this.nextWatchdogMs;
+      this.touch();
+    }
     else this.clearWatchdog();
     if (next === this._state) return;
     this._state = next;

package/src/hub/permission-mode.ts

@@ -1,12 +1,13 @@
 import { isSupportedPeer } from "./peer-catalog.ts";
+import { definitionOf } from "../adapters/registry.ts";
 import { lstatSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 
 /** Operator-selected approval frequency; agent sandboxes remain separate. */
 export const PERMISSION_MODES = ["ask", "ask-when-needed", "never-ask"] as const;
 export type PermissionMode = typeof PERMISSION_MODES[number];
-export const KIMI_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "yolo", "never-ask": "auto" };
-export const QWEN_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "auto-edit", "never-ask": "yolo" };
+export { KIMI_MODE_IDS } from "../adapters/definitions/kimi-native.ts";
+export { QWEN_MODE_IDS } from "../adapters/definitions/qwen-native.ts";
 export const isPermissionMode = (value: unknown): value is PermissionMode => typeof value === "string" && (PERMISSION_MODES as readonly string[]).includes(value);
 export function permissionDefaults(value: unknown): Record<string, PermissionMode> {
   if (value === undefined) return {};
@@ -29,9 +30,10 @@ export function permissionBoundary(peer: string): string {
 }
 /** What a mode lets a peer do without asking, in one line a person reads before choosing it (#269). */
 export function permissionGrant(peer: string, mode: PermissionMode): string {
+  const grant = definitionOf(peer)?.permission.grants?.[mode];
+  if (grant !== undefined) return grant;
   if (peer === "jcode") return "no verified hub mode mapping; native policy only";
   if (mode === "ask") return peer === "codex" ? "the session's own approval policy applies again" : peer === "kimi" ? "Kimi asks as it does on its own" : peer === "claude" ? "Claude's own permission rules decide" : "every write, edit and shell command asks";
-  if (peer === "qwen") return mode === "never-ask" ? "Qwen yolo approves every tool; NO hub sandbox" : "Qwen auto-edit approves file edits; shell commands ask; NO hub sandbox";
   if (peer === "kimi") return mode === "never-ask" ? "Kimi's auto mode: nothing asks" : "Kimi's yolo mode: it asks only where it judges it must";
   if (peer === "codex") return mode === "never-ask" ? "approval policy never on every turn: nothing asks" : "approval policy on-request on every turn";
   if (peer === "claude") return mode === "never-ask" ? "every tool runs without asking" : "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules";

package/src/hub/recovery-continuity.ts

@@ -0,0 +1,152 @@
+import { Database } from "bun:sqlite";
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
+import { realPath } from "./project.ts";
+import { atomicPrivateJSON, operationIdPattern } from "./recovery-store.ts";
+
+export const RECOVERY_CONTINUITY_BUSY_TIMEOUT_MS = 3000;
+const MAX_BOOKMARK_BYTES = 16 * 1024;
+const BOOKMARK = "recovery-continuity.json", LOCK = "recovery-continuity-lock.db";
+
+export interface RecoveryContinuityBookmark {
+  schema: 1;
+  operationId: string;
+  projectId: string;
+  projectRoot: string;
+  at: number;
+  pi: { sessionId: string; sessionFile?: string; backend?: "auto" | "dgx" | "mlx"; model?: string };
+}
+export interface RecoveryContinuityExpected { projectId: string; projectRoot: string; operationId?: string }
+export type ContinuityRetirementReason = "authenticated_session_changed" | "resume_unavailable" | "recovery_released";
+export type RecoveryContinuityReading =
+  | { state: "absent" }
+  | { state: "invalid"; reason: "unavailable" | "invalid_shape" | "invalid_path" | "identity_mismatch" | "oversized" }
+  | { state: "ready"; bookmark: RecoveryContinuityBookmark; digest: string };
+
+const unavailable = (): never => { throw new Error("recovery continuity metadata unavailable or invalid"); };
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const keys = (value: Record<string, unknown>, allowed: readonly string[]): boolean => Object.keys(value).every(key => allowed.includes(key));
+const text = (value: unknown, max: number): value is string => typeof value === "string" && value.length > 0 && value.length <= max && !/[\x00-\x1f\x7f]/.test(value);
+const id = (value: unknown): value is string => text(value, 256) && /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value);
+const absolute = (value: unknown): value is string => text(value, 4096) && isAbsolute(value) && normalize(value) === value;
+function canonicalRoot(value: unknown): string {
+  if (!absolute(value)) return unavailable();
+  const root = realPath(value);
+  if (!lstatSync(root).isDirectory()) return unavailable();
+  return root;
+}
+function checked(value: unknown): RecoveryContinuityBookmark {
+  if (!record(value) || !keys(value, ["schema", "operationId", "projectId", "projectRoot", "at", "pi"]) || value.schema !== 1 || typeof value.operationId !== "string" || !operationIdPattern.test(value.operationId) || !id(value.projectId) || !absolute(value.projectRoot) || !Number.isSafeInteger(value.at) || (value.at as number) < 0) return unavailable();
+  const pi = value.pi;
+  if (!record(pi) || !keys(pi, ["sessionId", "sessionFile", "backend", "model"]) || !id(pi.sessionId) || pi.sessionFile !== undefined && !absolute(pi.sessionFile) || pi.backend !== undefined && !["auto", "dgx", "mlx"].includes(String(pi.backend)) || pi.model !== undefined && !text(pi.model, 4096)) return unavailable();
+  const projectRoot = canonicalRoot(value.projectRoot);
+  return { schema: 1, operationId: value.operationId, projectId: value.projectId, projectRoot, at: value.at as number,
+    pi: { sessionId: pi.sessionId, ...(pi.sessionFile === undefined ? {} : { sessionFile: pi.sessionFile as string }), ...(pi.backend === undefined ? {} : { backend: pi.backend as "auto" | "dgx" | "mlx" }), ...(pi.model === undefined ? {} : { model: pi.model as string }) } };
+}
+function stateDirectory(stateDir: string): void {
+  if (!absolute(stateDir)) return unavailable();
+  const stat = lstatSync(stateDir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) return unavailable();
+}
+function privateFile(path: string, missing = false): void {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.mode & 0o077) return unavailable();
+  } catch (error) { if (!missing || (error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+}
+const digest = (bytes: Buffer): string => createHash("sha256").update(bytes).digest("hex");
+
+/** Read one bounded project-local file; invalid evidence is deliberately distinct from no bookmark. */
+export function readRecoveryContinuity(stateDir: string, expected: RecoveryContinuityExpected): RecoveryContinuityReading {
+  let fd: number | undefined;
+  let expectedRoot: string;
+  try { expectedRoot = canonicalRoot(expected.projectRoot); }
+  catch { return { state: "invalid", reason: "identity_mismatch" }; }
+  try {
+    stateDirectory(stateDir);
+    const file = join(stateDir, BOOKMARK);
+    privateFile(file);
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.mode & 0o077) return { state: "invalid", reason: "invalid_path" };
+    if (stat.size > MAX_BOOKMARK_BYTES) return { state: "invalid", reason: "oversized" };
+    const buffer = Buffer.alloc(MAX_BOOKMARK_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) { const n = readSync(fd, buffer, length, buffer.length - length, null); if (!n) break; length += n; }
+    if (length > MAX_BOOKMARK_BYTES) return { state: "invalid", reason: "oversized" };
+    const bytes = buffer.subarray(0, length);
+    let bookmark: RecoveryContinuityBookmark;
+    try {
+      const raw: unknown = JSON.parse(bytes.toString("utf8"));
+      bookmark = checked(raw);
+      if (!record(raw) || raw.projectRoot !== bookmark.projectRoot) return { state: "invalid", reason: "invalid_path" };
+    } catch { return { state: "invalid", reason: "invalid_shape" }; }
+    if (!id(expected.projectId) || expected.operationId !== undefined && !operationIdPattern.test(expected.operationId) || bookmark.projectId !== expected.projectId || bookmark.projectRoot !== expectedRoot || expected.operationId !== undefined && bookmark.operationId !== expected.operationId) return { state: "invalid", reason: "identity_mismatch" };
+    return { state: "ready", bookmark, digest: digest(bytes) };
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT" ? { state: "absent" } : { state: "invalid", reason: "unavailable" };
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+
+/** A crash releases SQLite's lock; no lockfile ownership or stale-process inference is needed. */
+function withWriter<T>(stateDir: string, action: () => T): T {
+  stateDirectory(stateDir);
+  const file = join(stateDir, LOCK);
+  privateFile(file, true);
+  for (const suffix of ["-journal", "-wal", "-shm"]) privateFile(file + suffix, true);
+  const db = new Database(file, { create: true });
+  db.run(`PRAGMA busy_timeout = ${RECOVERY_CONTINUITY_BUSY_TIMEOUT_MS}`);
+  try {
+    chmodSync(file, 0o600);
+    db.run("BEGIN IMMEDIATE");
+    try { return action(); } finally { db.run("ROLLBACK"); }
+  } finally { db.close(); }
+}
+
+/** Called only after the coordinator confirmed its target stopped and archived that operation's snapshot. */
+export function writeRecoveryContinuity(stateDir: string, value: RecoveryContinuityBookmark): { digest: string } {
+  const bookmark = checked(value), bytes = Buffer.from(JSON.stringify(bookmark, null, 2) + "\n");
+  if (bytes.length > MAX_BOOKMARK_BYTES) return unavailable();
+  return withWriter(stateDir, () => {
+    privateFile(join(stateDir, BOOKMARK), true);
+    atomicPrivateJSON(join(stateDir, BOOKMARK), bookmark);
+    return { digest: digest(bytes) };
+  });
+}
+
+/** Consume only the exact bookmark whose recorded session has authenticated; stale receipts retain newer data. */
+export function consumeRecoveryContinuity(stateDir: string, expected: RecoveryContinuityExpected & { operationId: string; digest: string }): boolean {
+  if (!operationIdPattern.test(expected.operationId) || !/^[a-f0-9]{64}$/.test(expected.digest)) return false;
+  return withWriter(stateDir, () => {
+    const current = readRecoveryContinuity(stateDir, { projectId: expected.projectId, projectRoot: expected.projectRoot });
+    if (current.state === "absent") return false;
+    if (current.state === "invalid") return unavailable();
+    if (current.bookmark.operationId !== expected.operationId || current.digest !== expected.digest) return false;
+    unlinkSync(join(stateDir, BOOKMARK));
+    return true;
+  });
+}
+
+/** Preserve superseded evidence privately; only a matching project/operation/digest may retire the active file. */
+export function retireRecoveryContinuity(
+  stateDir: string,
+  expected: RecoveryContinuityExpected & { operationId: string; digest: string },
+  reason: ContinuityRetirementReason,
+): { retired: boolean; archive?: string } {
+  if (!["authenticated_session_changed", "resume_unavailable", "recovery_released"].includes(reason)) return unavailable();
+  if (!operationIdPattern.test(expected.operationId) || !/^[a-f0-9]{64}$/.test(expected.digest)) return { retired: false };
+  return withWriter(stateDir, () => {
+    const current = readRecoveryContinuity(stateDir, { projectId: expected.projectId, projectRoot: expected.projectRoot });
+    if (current.state === "absent") return { retired: false };
+    if (current.state === "invalid") return unavailable();
+    if (current.bookmark.operationId !== expected.operationId || current.digest !== expected.digest) return { retired: false };
+    // A unique destination preserves an earlier retirement even when the same bookmark was explicitly restored.
+    const archive = join(stateDir, `recovery-continuity.retired.${reason}.${current.digest}.${randomUUID()}.json`);
+    try { lstatSync(archive); return unavailable(); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    renameSync(join(stateDir, BOOKMARK), archive);
+    chmodSync(archive, 0o600);
+    return { retired: true, archive };
+  });
+}

package/src/hub/recovery-store.ts

@@ -69,15 +69,21 @@ export function assertLifecycleAvailable(): void {
  * lacks dispose, refuses abort and resume on a lapsed hold and shows no next actions: then the running release is
  * named, which does all of that in-process (its resume still runs the operation's own runner).
  */
-export function recoveryCommand(op: { id: string; sourceRoot?: string }, action: "status" | "resume" | "abort" | "dispose", flags = ""): string {
-  const entry = !op.sourceRoot ? undefined : coordinatorCurrent(op.sourceRoot) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
+export type RecoveryAction = "status" | "resume" | "abort" | "dispose" | "reattach";
+export function supportsAction(sourceRoot: string, action: RecoveryAction): boolean {
+  if (!coordinatorCurrent(sourceRoot)) return false;
+  if (action !== "reattach") return true;
+  try { return readFileSync(join(sourceRoot, "src/cli/upgrade.ts"), "utf8").includes("export async function reattachRecovery"); } catch { return false; }
+}
+export function recoveryCommand(op: { id: string; sourceRoot?: string }, action: RecoveryAction, flags = ""): string {
+  const entry = !op.sourceRoot ? undefined : supportsAction(op.sourceRoot, action) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
   const cli = !entry ? "ahub" : /^[\w./@+-]+$/.test(entry) ? `bun ${entry}` : `bun '${entry.replace(/'/g, `'\\''`)}'`;
   return `${cli} recovery ${action} ${op.id}${flags ? ` ${flags}` : ""}`;
 }
 
 /** #272: the command above as an argv for `bun`, which a screen runs instead of printing; with no coordinator of its own, this release's. */
-export function recoveryArgv(op: { id: string; sourceRoot?: string }, action: "status" | "resume" | "abort" | "dispose", flags: string[] = []): string[] {
-  const entry = op.sourceRoot && coordinatorCurrent(op.sourceRoot) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
+export function recoveryArgv(op: { id: string; sourceRoot?: string }, action: RecoveryAction, flags: string[] = []): string[] {
+  const entry = op.sourceRoot && supportsAction(op.sourceRoot, action) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
   return [entry, "recovery", action, op.id, ...flags];
 }
 

package/src/hub/restart.ts

@@ -2,10 +2,11 @@ import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSy
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import type { BusSnapshot } from "./bus.ts";
-import type { PeerId, PeerState } from "./envelope.ts";
+import type { Envelope, PeerId, PeerState } from "./envelope.ts";
 import { MAX_HOP } from "./envelope.ts";
 import { validateJournalSnapshot } from "./delivery-journal.ts";
 import { atomicPrivateJSON } from "./recovery-store.ts";
+import { RecoveryDeferredHubError, validateDeferredHub } from "./deferred-hub.ts";
 
 export const RESTART_SCHEMA_VERSION = 1;
 
@@ -75,6 +76,16 @@ export function readRestartSnapshot(stateDir: string, expected: RestartReadExpec
   const bus = s.bus as Partial<BusSnapshot>;
   if (bus.schemaVersion !== 1 || !bus.queues || typeof bus.queues !== "object" || !bus.prefaces || typeof bus.prefaces !== "object" || !Array.isArray(bus.seen) || !bus.attempts || typeof bus.attempts !== "object" || !Array.isArray(bus.withdrawn)) return undefined;
   if (!Object.keys(bus.queues).every(peerId) || !Object.keys(bus.prefaces).every(peerId) || !Object.values(bus.queues).every((queue) => Array.isArray(queue) && queue.every((e) => isEnvelope(e))) || !Object.values(bus.prefaces).every((e) => isEnvelope(e)) || !bus.seen.every((e) => isEnvelope(e, true)) || !bus.withdrawn.every((id) => typeof id === "string" && id.length > 0) || !Object.values(bus.attempts).every((n) => Number.isSafeInteger(n) && n > 0)) return undefined;
+  try {
+    const occupied = new Set<string>([
+      ...bus.seen.map(env => env.id),
+      ...Object.values(bus.queues).flatMap(queue => queue.map(env => env.id)),
+    ]);
+    validateDeferredHub(bus.deferredHub, (value, name) => {
+      if (!isEnvelope(value)) throw new Error(`${name} is invalid`);
+      return value as Envelope;
+    }, occupied);
+  } catch (error) { if (error instanceof RecoveryDeferredHubError) throw error; return undefined; }
   if (!Array.isArray(s.manualPaused) || !s.manualPaused.every((id) => typeof id === "string") || !Array.isArray(s.peers) || !s.peers.every((peer) => peer && typeof peer === "object" && typeof peer.id === "string" && ["idle", "busy", "paused", "offline"].includes(peer.state as string) && Array.isArray(peer.queueIds) && peer.queueIds.every((id) => typeof id === "string"))) return undefined;
   if (s.integrity !== undefined && (!s.integrity || typeof s.integrity !== "object" || typeof s.integrity.boardDigest !== "string" || typeof s.integrity.budgetDigest !== "string" || !Array.isArray(s.integrity.manualPaused) || !s.integrity.manualPaused.every((id) => typeof id === "string") || !s.integrity.queues || typeof s.integrity.queues !== "object" || !Object.values(s.integrity.queues).every((ids) => Array.isArray(ids) && ids.every((id) => typeof id === "string")))) return undefined;
   if (bus.journal !== undefined) { try { validateJournalSnapshot(bus.journal); } catch { return undefined; } }

package/src/hub/sdlc.ts

@@ -3,6 +3,7 @@ import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { childEnv, stopOwnedProcess } from "./child-process.ts";
+import { hostExecutable } from "./host-executable.ts";
 
 export const SDLC_STAGES = ["spec", "plan", "implement", "review", "verify", "merge", "release"] as const;
 export type SdlcBaseStage = typeof SDLC_STAGES[number];
@@ -219,7 +220,10 @@ export type SdlcGh = (args: string[], timeoutMs?: number, cwd?: string, maxOutpu
 /** Read-only, fixed argv. Output and time are bounded; diagnostics never expose credentials or remote text. */
 export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 256 * 1024) => new Promise((resolve) => {
   const outputLimit = Number.isSafeInteger(maxOutputBytes) ? Math.min(2 * 1024 * 1024, Math.max(1, maxOutputBytes)) : 256 * 1024;
-  const child = spawn("gh", args, { ...(cwd ? { cwd } : {}), env: childEnv(), detached: true, stdio: ["ignore", "pipe", "ignore"] });
+  let child: ReturnType<typeof spawn>;
+  try {
+    child = spawn(hostExecutable("gh", cwd ?? process.cwd()), args, { ...(cwd ? { cwd } : {}), env: childEnv(), detached: true, stdio: ["ignore", "pipe", "ignore"] });
+  } catch { resolve({ code: 1, stdout: "" }); return; }
   let stdout = "", failed = false;
   const stop = () => { failed = true; void stopOwnedProcess(child, { group: true }).catch(() => {}); };
   const timer = setTimeout(stop, Math.max(1, Math.min(10_000, timeoutMs)));