@staix/agent-hub 0.12.33 → 0.12.35

package/src/adapters/definitions/native-policy-aux.ts

@@ -0,0 +1,130 @@
+import { closeSync, constants, fstatSync, openSync, readdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
+import type { Addon, AddonName } from "../../hub/tooling.ts";
+
+/** Native crash recovery keeps each adapter's exact restart and guidance contract. */
+interface NativeCrashPlan { resume?: Record<string, string>; how: string; fresh?: Record<string, string>; tui?: true }
+const str = (value: unknown): string | undefined => typeof value === "string" && value ? value : undefined;
+
+export function claudeCrashPlan(_meta: Record<string, unknown>): NativeCrashPlan {
+  return { how: "claude: the Claude Code plugin reconnects by itself while that session is still open" };
+}
+
+export function codexCrashPlan(meta: Record<string, unknown>): NativeCrashPlan {
+  return { how: `codex: its app-server died with the hub; run ahub codex again${str(meta.threadId) ? ` (its conversation was thread ${meta.threadId})` : ""}` };
+}
+
+export function jcodeCrashPlan(_meta: Record<string, unknown>): NativeCrashPlan {
+  return { how: "jcode: native 0.94.0 load does not prove the restored id; reopen the original conversation with its native client, no automatic fresh replacement" };
+}
+
+export function kimiCrashPlan(meta: Record<string, unknown>): NativeCrashPlan {
+  const launch = (meta.launch && typeof meta.launch === "object" ? meta.launch : {}) as Record<string, unknown>;
+  const model = str(launch.model);
+  const sessionId = str(meta.sessionId);
+  if (!sessionId) return { how: "kimi: no session id was recorded; start it again with ahub kimi" };
+  return { resume: { sessionId, ...(model ? { model } : {}) }, how: `kimi: session ${sessionId} can be loaded again (ACP session/load)` };
+}
+
+export function piCrashPlan(meta: Record<string, unknown>): NativeCrashPlan {
+  const launch = (meta.launch && typeof meta.launch === "object" ? meta.launch : {}) as Record<string, unknown>;
+  const model = str(launch.model);
+  // `fresh`: what a new headless session keeps of the recorded one (pi.auto_start's fallback, #66).
+  const fresh: Record<string, string> = {};
+  for (const k of ["backend", "model"] as const) if (str(launch[k])) fresh[k] = str(launch[k])!;
+  const sessionFile = str(meta.sessionFile) ?? str(launch.sessionFile);
+  // #269: a terminal Pi stays marked as one without a session file too, so nothing headless is started in its place.
+  if (!sessionFile) return { fresh, ...(str(launch.mode) === "tui" ? { tui: true } : {}), how: "pi: no session file was recorded; start it again with ahub pi" };
+  // A terminal Pi is run by the CLI that launched it, not by the hub: nothing here could start it again.
+  if (str(launch.mode) === "tui") return { fresh, tui: true, how: `pi: it ran in a terminal; start it again with ahub pi --mode tui --session-file ${sessionFile}` };
+  const args: Record<string, string> = { sessionFile };
+  for (const k of ["mode", "backend", "model"] as const) if (str(launch[k])) args[k] = str(launch[k])!;
+  return { fresh, resume: args, how: `pi: its session file can be resumed (${sessionFile})` };
+}
+
+export function localCrashPlan(meta: Record<string, unknown>): NativeCrashPlan {
+  const launch = (meta.launch && typeof meta.launch === "object" ? meta.launch : {}) as Record<string, unknown>;
+  const model = str(launch.model);
+  // `model` is also recorded as the route's fallback, and a model given at start pins it: pass one or the other.
+  const route = str(launch.route);
+  const args: Record<string, string> = route ? { route } : model ? { model } : {};
+  return { resume: args, how: "local: starts again without its history (the worker keeps none across a hub stop)" };
+}
+
+/** Plugin names (before the `@marketplace`) that stand for an add-on. */
+// Maps, not objects: a plugin named `constructor` or `toString` must find nothing, not an inherited property.
+const PLUGINS = new Map<string, AddonName>([["claude-mem", "claude-mem"], ["ponytail", "ponytail"], ["open-code-review", "open-code-review"]]);
+/** Claude Code only: the Codex plugin is a Claude plugin named `codex` from the `openai-codex` marketplace. */
+const CLAUDE_ONLY = new Map<string, AddonName>([["codex@openai-codex", "codex-plugin"]]);
+/** A regular file of at most 1 MiB, opened without blocking: a FIFO or device under a project's `.claude/` reads as absent. */
+const text = (file: string): string | undefined => {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > 1024 * 1024) return undefined;
+    return readFileSync(fd, "utf8");
+  } catch { return undefined; } finally { if (fd !== undefined) closeSync(fd); }
+};
+const json = (file: string): Record<string, unknown> | undefined => {
+  try { const v = JSON.parse(text(file) ?? ""); return v && typeof v === "object" ? v as Record<string, unknown> : undefined; } catch { return undefined; }
+};
+const version = (v: unknown): string | null => typeof v === "string" && /^[0-9A-Za-z.+_-]{1,40}$/.test(v) ? v : null;
+
+function claudePlugins(root: string, cwd: string | undefined): Addon[] {
+  const enabled = new Map<string, boolean>();
+  for (const file of [join(root, "settings.json"), ...(cwd ? [join(cwd, ".claude", "settings.json"), join(cwd, ".claude", "settings.local.json")] : [])]) {
+    const map = json(file)?.enabledPlugins;
+    if (map && typeof map === "object") for (const [key, on] of Object.entries(map)) enabled.set(key, on === true);
+  }
+  const installed = (json(join(root, "plugins", "installed_plugins.json"))?.plugins ?? {}) as Record<string, { scope?: string; projectPath?: string; version?: unknown }[]>;
+  const out: Addon[] = [];
+  for (const [key, on] of enabled) {
+    if (!on) continue;
+    const name = CLAUDE_ONLY.get(key) ?? PLUGINS.get(key.split("@")[0]!);
+    const entries = Array.isArray(installed[key]) ? installed[key]! : [];
+    // An install for another project is not this one's.
+    const entry = entries.find((e) => e?.scope === "user") ?? entries.find((e) => e?.projectPath === cwd);
+    if (name && entry) out.push({ name, version: version(entry.version) });
+  }
+  return out;
+}
+
+function codexPlugins(root: string): Addon[] {
+  const config = text(join(root, "config.toml"));
+  if (config === undefined) return [];
+  const found = new Map<string, string>(), disabled = new Set<string>(); // plugin name -> marketplace
+  // `[plugins."name@market"]` with no `enabled = false` below it, and plugins whose hooks Codex was told to trust
+  // unless their plugin entry disables them: a trust entry outlives the plugin's own switch.
+  for (const m of config.matchAll(/^\[plugins\."([^"@]+)@([^"]+)"\]\s*\n((?:(?!\[)[^\n]*\n?)*)/gm)) if (!/^\s*enabled\s*=\s*false\b/m.test(m[3] ?? "")) found.set(m[1]!, m[2]!); else disabled.add(m[1]! + "@" + m[2]!);
+  for (const m of config.matchAll(/^\[hooks\.state\."([^"@]+)@([^":]+):/gm)) if (!disabled.has(m[1]! + "@" + m[2]!)) found.set(m[1]!, m[2]!);
+  const out: Addon[] = [];
+  for (const [plugin, market] of found) {
+    const name = PLUGINS.get(plugin);
+    if (!name) continue;
+    let versions: string[] = [];
+    try { versions = readdirSync(join(root, "plugins", "cache", market, plugin)); } catch { /* no cache: version unknown */ }
+    out.push({ name, version: versions.length === 1 ? version(versions[0]) : null });
+  }
+  return out;
+}
+
+interface PluginInventoryContext { home: string; cwd?: string; env: Readonly<Record<string, string | undefined>> }
+export const claudePluginInventory = (ctx: PluginInventoryContext): Addon[] => claudePlugins(ctx.env.CLAUDE_CONFIG_DIR?.trim() || join(ctx.home, ".claude"), ctx.cwd);
+export const codexPluginInventory = (ctx: PluginInventoryContext): Addon[] => codexPlugins(ctx.env.CODEX_HOME?.trim() || join(ctx.home, ".codex"));
+
+/** A persisted native identity decoder; the coordinator retains envelope, path and operation checks. */
+export function parsePiContinuity(value: unknown): { sessionId: string; sessionFile?: string; backend?: "auto" | "dgx" | "mlx"; model?: string } | undefined {
+  const record = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+  const text = (v: unknown, max: number): v is string => typeof v === "string" && v.length > 0 && v.length <= max && !/[\x00-\x1f\x7f]/.test(v);
+  const id = (v: unknown): v is string => text(v, 256) && /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(v);
+  if (!record(value) || Object.keys(value).some(key => !["sessionId", "sessionFile", "backend", "model"].includes(key)) || !id(value.sessionId)
+    || value.sessionFile !== undefined && !absoluteContinuityPath(value.sessionFile) || value.backend !== undefined && !["auto", "dgx", "mlx"].includes(String(value.backend))
+    || value.model !== undefined && !text(value.model, 4096)) return undefined;
+  return { sessionId: value.sessionId, ...(value.sessionFile === undefined ? {} : { sessionFile: value.sessionFile as string }), ...(value.backend === undefined ? {} : { backend: value.backend as "auto" | "dgx" | "mlx" }), ...(value.model === undefined ? {} : { model: value.model as string }) };
+}
+function absoluteContinuityPath(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 4096 && !/[\x00-\x1f\x7f]/.test(value) && isAbsolute(value) && normalize(value) === value;
+}
+
+export const codexToolSemantic = (name: string, _command?: string): "edit" | undefined => name.toLowerCase() === "filechange" ? "edit" : undefined;

package/src/adapters/definitions/native-quota.ts

@@ -0,0 +1,29 @@
+import type { UsageWindow } from "../../hub/budget.ts";
+
+/** Codex `rateLimits` snapshot (account/rateLimits/read, account/rateLimits/updated) -> windows. */
+export function codexWindows(rateLimits: any): UsageWindow[] {
+  const out: UsageWindow[] = [];
+  // The slot decides (primary = short window, secondary = long one) and the duration overrides it when present:
+  // readings are keyed by window id, so two windows must never both come out as "5h".
+  for (const [w, slot] of [[rateLimits?.primary, "5h"], [rateLimits?.secondary, "week"]] as const) {
+    if (!w || typeof w.usedPercent !== "number") continue;
+    const mins = typeof w.windowDurationMins === "number" ? w.windowDurationMins : undefined;
+    const id = mins === undefined ? slot : mins > 600 ? "week" : "5h";
+    if (out.some((o) => o.id === id)) continue; // both slots claim the same window: keep the first, never overwrite
+    out.push({ id, used: w.usedPercent / 100, ...(w.resetsAt ? { resetsAt: w.resetsAt * 1000 } : {}), ...(mins ? { windowMins: mins } : {}), source: "codex rateLimits" });
+  }
+  if (rateLimits?.rateLimitReachedType && !out.some((w) => w.used >= 1)) out.push({ id: "5h", used: 1, source: `codex ${rateLimits.rateLimitReachedType}` });
+  return out;
+}
+
+/** Claude Code status line `rate_limits` -> windows. */
+export function claudeWindows(rateLimits: any): UsageWindow[] {
+  const out: UsageWindow[] = [];
+  for (const [key, id, mins] of [["five_hour", "5h", 300], ["seven_day", "week", 10_080]] as const) {
+    const w = rateLimits?.[key];
+    if (!w || typeof w.used_percentage !== "number") continue;
+    const resets = Number(w.resets_at);
+    out.push({ id, used: w.used_percentage / 100, ...(resets ? { resetsAt: resets < 1e12 ? resets * 1000 : resets } : {}), windowMins: mins, source: "claude status line" });
+  }
+  return out;
+}

package/src/adapters/definitions/native-recovery-continuity.ts

@@ -0,0 +1,12 @@
+import type { RecoveryPeer } from "../../cli/upgrade.ts";
+import type { TerminalBinding } from "../../cli/terminal-recovery.ts";
+import type { RecoveryContinuityBookmark } from "../../hub/recovery-continuity.ts";
+
+/** Native continuity payload only; archival evidence and persistence remain with the recovery coordinator. */
+export function piRecoveryContinuity(peer: RecoveryPeer, binding?: TerminalBinding): Pick<RecoveryContinuityBookmark, "pi"> {
+  const sessionId = binding?.sessionId ?? peer.sessionId;
+  if (!sessionId) throw new Error("Pi recorded session unavailable; archive continuity bookmark was not written");
+  const backend = binding?.backend ?? peer.args?.backend;
+  return { pi: { sessionId, sessionFile: binding?.sessionFile ?? peer.sessionFile ?? peer.args?.sessionFile,
+    ...(backend === "auto" || backend === "dgx" || backend === "mlx" ? { backend } : {}), model: binding?.model ?? peer.args?.model } };
+}

package/src/adapters/definitions/native-recovery.ts

@@ -0,0 +1,88 @@
+import { readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { readEvents } from "../../hub/events.ts";
+import { checkedSessionPath, recordedFileState } from "../../cli/recovery-session-file.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import type { TerminalBinding } from "../../cli/terminal-recovery.ts";
+import type { RecoveryPeer } from "../../cli/upgrade.ts";
+
+type SessionPolicy = Partial<AdapterDefinition["session"]>;
+const rolloutState = (binding: TerminalBinding): boolean | "unknown" => {
+  try { return readdirSync(checkedSessionPath(binding, "rollout"), { recursive: true }).some(name => String(name).endsWith(".jsonl") && basename(String(name)).includes(binding.sessionId)); }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? false : "unknown"; }
+};
+const transcriptState = (binding: TerminalBinding): boolean | "unknown" => {
+  const state = recordedFileState(checkedSessionPath(binding, "transcript"));
+  return state === "unknown" ? "unknown" : state === "found";
+};
+/** Preserve the driver's explicit evidence-kind dispatch, including historical typed receipt reads. */
+export function nativeRecordedSessionState(binding: TerminalBinding, kind: "rollout" | "transcript"): "found" | "missing" | "unknown" {
+  const state = kind === "rollout" ? rolloutState(binding) : transcriptState(binding);
+  return state === "unknown" ? "unknown" : state ? "found" : "missing";
+}
+const startupArgs = (peer: RecoveryPeer): Record<string, string> => Object.fromEntries(["mode", "backend", "model", "route"]
+  .flatMap(key => typeof peer.args?.[key] === "string" ? [[key, peer.args[key]!]] : []));
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+const object = (value: unknown): Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+
+export const CODEX_RECOVERY_SESSION: SessionPolicy = {
+  resumeArgv: (binding, fresh) => ["codex", ...(fresh ? [] : ["resume", binding.sessionId])],
+  transcriptPath: binding => checkedSessionPath(binding, "rollout"), transcriptExists: rolloutState,
+  personFresh: true, missingEvidence: "rollout",
+  zeroTurn: ({ stateDir, binding, phase }) => {
+    if (phase !== "plan") return false;
+    let current: string | undefined, started = false, turned = false;
+    for (const e of readEvents(join(stateDir, "events.jsonl"))) {
+      if (e.type === "native_thread" && e.peer === binding.peer) {
+        current = e.thread;
+        if (e.thread === binding.sessionId && e.fresh) started = true;
+      } else if (e.type === "turn_start" && e.peer === binding.peer && current === binding.sessionId) turned = true;
+    }
+    return started && !turned;
+  },
+};
+export const CLAUDE_RECOVERY_SESSION: SessionPolicy = {
+  resumeArgv: (binding, fresh) => ["claude", ...(fresh ? [] : ["--resume", binding.sessionId])],
+  transcriptPath: binding => checkedSessionPath(binding, "transcript"), transcriptExists: transcriptState,
+  zeroTurn: ({ binding, phase }) => phase !== "plan" && transcriptState(binding) !== true,
+  personFresh: true, missingEvidence: "transcript",
+};
+export const PI_RECOVERY_SESSION: SessionPolicy = {
+  resumeArgv: binding => ["pi", "--mode", "tui", ...(binding.backend ? ["--backend", binding.backend] : []), ...(binding.model ? ["--model", binding.model] : []),
+    ...(binding.sessionFile ? ["--session-file", binding.sessionFile] : ["--session-id", binding.sessionId])],
+  personFresh: false,
+  restoreArgs: peer => {
+    const args = startupArgs(peer);
+    if (typeof peer.args?.mode !== "string") args.mode = "headless";
+    const file = peer.sessionFile ?? peer.args?.sessionFile;
+    if (typeof file === "string") args["session-file"] = file;
+    else if (peer.sessionId) args["session-id"] = peer.sessionId;
+    return args;
+  },
+  crashIdentity: row => {
+    const value = object(row), args = object(value.args), session = object(value.session);
+    const sessionId = [value.sessionId, value.agentSessionId, value.resumeSessionId, session.id, session.sessionId].find(text);
+    const sessionFile = [value.sessionFile, value.sessionPath, args.sessionFile, session.file, session.path].find(text);
+    return { ...(sessionId ? { sessionId } : {}), ...(sessionFile ? { sessionFile } : {}) };
+  },
+};
+export const KIMI_RECOVERY_SESSION: SessionPolicy = {
+  legacyHeadlessArgv: { file: "src/hub/start-mode.ts", exportName: "START_MODE_PEERS", argv: ["--mode", "headless"] },
+  restoreArgs: peer => { const args = startupArgs(peer); delete args.mode; return args; },
+  recoveryRefusal: (peer, phase = "plan") => peer.args?.mode === "tui"
+    ? phase === "restore" ? "Kimi's pull-only terminal cannot be restored as a headless worker; end it in that terminal and make a new recovery plan"
+      : "kimi: its pull-only terminal has no automatic restore; end it in that terminal, then make a new recovery plan (its session is not resumed by the hub)" : undefined,
+};
+export const LOCAL_RECOVERY_SESSION: SessionPolicy = { restoreArgs: startupArgs };
+export const JCODE_RECOVERY_SESSION: SessionPolicy = {
+  legacyTargetSupport: { file: "src/hub/peer-catalog.ts", exportName: "OPTIONAL_PEERS", refusal: "target does not support Jcode; end it and make a new plan, or choose a supporting target; runtimes unchanged" },
+  recoveryRefusal: (_peer, phase = "plan") => phase === "restore" ? undefined : "jcode: source-pinned native load cannot prove conversation identity; end the peer and make a new recovery plan before effects",
+  restoreArgs: peer => ({ ...startupArgs(peer), ...(peer.sessionId ? { "session-id": peer.sessionId } : {}), ...(peer.args?.providerProfile ? { "provider-profile": peer.args.providerProfile } : {}) }),
+};
+export const QWEN_RECOVERY_SESSION: SessionPolicy = {
+  legacyTargetSupport: { file: "src/hub/peer-catalog.ts", exportName: "OPTIONAL_PEERS", refusal: "target does not support Qwen; end Qwen and make a new plan, or choose a supporting target; runtimes unchanged" },
+  restoreArgs: peer => ({ ...startupArgs(peer), ...(peer.sessionId ? { "session-id": peer.sessionId } : {}) }),
+};
+
+/** Fixed legacy native probes: callers retain their existing source-text capability checks. */
+export const SHARED_CHANNEL_VERSION_ARGV = ["claude", "--version"] as const;

package/src/adapters/definitions/qwen-native.ts

@@ -7,9 +7,9 @@ export class QwenIdentityError extends Error {
   constructor() { super("Qwen Code 0.25.0 native identity is not verified; check the executable and its advertised ACP version"); }
 }
 
-export function qwenNativeIdentity(instance: string, production: boolean | undefined, init: unknown): boolean {
+export function qwenNativeIdentity(instance: string, production: boolean | undefined, init: unknown, kind?: string): boolean {
   const native = init as { agentInfo?: { name?: unknown; version?: unknown } } | null | undefined;
-  const verified = production === true && instance === "qwen" && native?.agentInfo?.name === "qwen-code" && native?.agentInfo?.version === "0.25.0";
+  const verified = production === true && (kind ?? instance) === "qwen" && native?.agentInfo?.name === "qwen-code" && native?.agentInfo?.version === "0.25.0";
   if (production && !verified) throw new QwenIdentityError();
   return verified;
 }

package/src/adapters/definitions/qwen.ts

@@ -1,7 +1,9 @@
+import { QWEN_DISPLAY } from "./native-display.ts";
+import { QWEN_RECOVERY_SESSION } from "./native-recovery.ts";
 import { AcpPeer } from "../acp.ts";
 import type { AdapterDefinition } from "../registry-types.ts";
 import { buildQwenLaunch, qwenNativeIdentity, qwenSessionId, QWEN_MODE_IDS } from "./qwen-native.ts";
-import { shellQuote } from "../../cli/terminal-recovery.ts";
+import { shellQuote } from "../../cli/shell-quote.ts";
 
 /** Production Qwen policy. Legacy AcpPeer callers opt in separately through qwen025. */
 export const QWEN_DEFINITION: AdapterDefinition = {
@@ -15,6 +17,7 @@ export const QWEN_DEFINITION: AdapterDefinition = {
   defaultOnRoster: false,
   trust: { onPrem: false, hubSandboxed: false },
   start: {
+    daemonPort: "acp",
     forms: ["headless"],
     defaultForm: "headless",
     ownsTerminal: () => false,
@@ -34,7 +37,7 @@ export const QWEN_DEFINITION: AdapterDefinition = {
       if (context.permission === "read-only") throw new Error("Qwen has no verified read-only permission mapping");
       return new AcpPeer(context.instance, { ...context.daemon.acp, qwen025: true, permissionMode: context.permission, mcpServers: context.mcpServers });
     },
-    conductorStartArgs: args => args.length ? new Error("Qwen start takes no conductor overrides") : {},
+    conductorStartArgs: args => args.length ? new Error("conductor starts accept no launch overrides; use ahub qwen") : {},
   },
   identity: { mcp: "acp-session" },
   permission: {
@@ -55,8 +58,9 @@ export const QWEN_DEFINITION: AdapterDefinition = {
       const sessionId = peer.recoveryMetadata?.().sessionId;
       return typeof sessionId === "string" ? sessionId : undefined;
     },
+    ...QWEN_RECOVERY_SESSION,
     launchKind: "acp",
-    restoreOnStart: true,
+    resumeById: true,
     crashIdentity: row => {
       const sessionId = row && typeof row === "object" ? (row as { sessionId?: unknown }).sessionId : undefined;
       return qwenSessionId(sessionId) ? { sessionId } : {};
@@ -66,6 +70,6 @@ export const QWEN_DEFINITION: AdapterDefinition = {
   budget: { account: "qwen" },
   capabilities: { watch: true },
   cli: { command: "qwen", startWords: () => ["qwen"] },
-  display: { palette: { fg: "#8a8f99", bg: "transparent" } },
+  display: QWEN_DISPLAY,
   hooks: { agentIdentity: init => { qwenNativeIdentity("qwen", true, init); }, recallPlatform: "qwen" },
 };

package/src/adapters/local-worker.ts

@@ -18,6 +18,7 @@ import type { ExecutionBudgetDecision } from "../hub/execution-budget.ts";
 export interface LocalOptions {
   profile?: import("../hub/profiles.ts").ProfileSelection;
   sdlcStages?: readonly string[];
+  sdlcCriteria?: boolean;
   cwd: string;
   omni: OmniRoute;
   /** Absent = always the fixed model on OmniRoute. */
@@ -108,7 +109,7 @@ export class LocalPeer extends BasePeer {
         await this.requireBudget(envs, "model_calls");
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
         if (signal.aborted) throw new Error("turn cancelled before model request");
-        const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+        const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
         const result = await this.opts.omni.chat({ model, messages, ...(tools ? { tools } : {}), ...(judge ? { max_tokens: maxTokens ?? 2048 } : {}) }, { signal, ...(pii ? { onCampusOnly: true } : {}) });
         this.recordUsage(result, model, task);
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
@@ -378,7 +379,7 @@ export class LocalPeer extends BasePeer {
     const route = policy?.route ?? this.opts.route;
     const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
     const task = policy?.task === undefined ? undefined : Number(policy.task);
-    const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+    const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
     const signal = this.abort!.signal;
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
     const routed = await this.hubCall(route, messages, policy, signal);

package/src/adapters/pi.ts

@@ -33,6 +33,8 @@ class PiPromptNotStarted extends Error {
 }
 class PiPromptUncertain extends Error {}
 export interface PiOptions {
+  /** stateDir owns this native instance; hubStateDir retains the canonical daemon binding. */
+  hubStateDir?: string;
   cwd: string; stateDir: string; cmd?: string[]; mode: "headless" | "tui"; backend: "auto" | "dgx" | "mlx"; sessionFile?: string; sessionId?: string;
   model?: string;
   relay: PiRelay; executeTool: (name: string, args: unknown, toolCallId: string, sessionId?: string, signal?: AbortSignal, context?: PiToolContext) => Promise<string | PiToolResult>; tools: PiToolSchema[];
@@ -385,7 +387,7 @@ export class PiPeer extends BasePeer {
     const extension = resolve(join(import.meta.dir, "../pi/extension.ts"));
     const inherited: NodeJS.ProcessEnv = {};
     for (const key of ["PATH", "HOME", "USER", "SHELL", "TMPDIR", "TERM", "TERM_PROGRAM", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "CODEX_HOME"]) if (process.env[key]) inherited[key] = process.env[key];
-    this._tuiLaunch = buildPiLaunch(this.opts, inherited, extension, bridge.port!, token);
+    this._tuiLaunch = buildPiLaunch({ ...this.opts, instance: this.id }, inherited, extension, bridge.port!, token);
     const { cmd: bin, args, env } = this._tuiLaunch;
     if (this.opts.mode === "tui") { return; }
     // Its own process group, stopped as a whole (#115, as Codex's in #113).

package/src/adapters/registry-types.ts

@@ -1,5 +1,9 @@
+import type { SettingDef } from "../hub/settings.ts";
+import type { Addon } from "../hub/tooling.ts";
+import type { RecoveryContinuityBookmark } from "../hub/recovery-continuity.ts";
+import type { RecoveryPeer } from "../cli/upgrade.ts";
 import type { Launch, StatusLineTee, FactsHook } from "../cli/launch.ts";
-import type { LaunchMetadata, TerminalBinding } from "../cli/terminal-recovery.ts";
+import type { LaunchMetadata, TerminalBinding, SessionRef } from "../cli/terminal-recovery.ts";
 import type { UsageWindow } from "../hub/budget.ts";
 import type { ContextReading } from "../hub/context-window.ts";
 import type { PeerAdapter } from "../hub/peers.ts";
@@ -11,6 +15,7 @@ import type { LocalOptions } from "./local-worker.ts";
 import type { PiOptions } from "./pi.ts";
 
 export type StartForm = "tui" | "headless";
+export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker";
 
 /** Existing buildLaunch inputs plus the startup-bound instance and project identity. */
 export interface LaunchContext {
@@ -31,9 +36,16 @@ export interface LaunchContext {
   env: Readonly<Record<string, string>>;
   /** Existing validated config argv (or the existing redacted preview), never model input. */
   nativeCommand?: readonly string[];
+  /** Existing trusted Pi builder inputs; never populated from a request or model. */
+  pi?: {
+    options: Pick<PiOptions, "stateDir" | "cmd" | "mode" | "backend" | "model" | "relay" | "tools" | "preamble" | "maxSteps" | "sessionFile" | "sessionId">;
+    extension: string;
+    bridgePort: number | string;
+    bridgeToken: string;
+  };
 }
 
-export type LaunchPlan = Launch & { metadata: LaunchMetadata; mcpFile?: { path: string; entry: unknown } };
+export type LaunchPlan = Launch & { env?: NodeJS.ProcessEnv; metadata: LaunchMetadata; mcpFile?: { path: string; entry: unknown } };
 
 /** A factory receives exactly its existing transport options, with no cross-transport callback widening. */
 export type DaemonPorts =
@@ -65,6 +77,9 @@ export interface StartRequest {
 
 export interface VersionContext {
   instance: string;
+  observedVersion?: string;
+  nativeCommand?: readonly string[];
+  projectRoot?: string;
   peer?: PeerAdapter;
   env: Readonly<Record<string, string>>;
 }
@@ -78,13 +93,13 @@ export type NativeModeSpec =
 
 export interface QuotaReader {
   source: string;
-  read(peer: PeerAdapter): UsageWindow[] | undefined;
+  read(value: unknown): UsageWindow[];
   resetOnWindow?: boolean;
 }
 
 export interface ContextReader {
   source: ContextReading["source"];
-  read(peer: PeerAdapter): ContextReading | undefined;
+  read(value: unknown, sessionId: string, measuredAt: number): ContextReading;
 }
 
 export interface CapabilityManifest {
@@ -106,10 +121,21 @@ export interface NativeHooks {
   factsHook: (msg: unknown) => unknown;
   conversationRevert(turnId: string): Promise<void>;
   replaceSession(req: StartRequest): Promise<unknown>;
-  pluginInventory(env: Readonly<Record<string, string>>): string[];
+  pluginInventory(ctx: { home: string; cwd?: string; env: Readonly<Record<string, string | undefined>> }): Addon[];
+  recallSource: string;
+  recallInjected: boolean;
+  classifyTool(name: string, command?: string): "edit" | undefined;
   recallPlatform: string;
 }
 
+export type NativeConfigCheck = (value: unknown, key: string) => void;
+export interface NativeConfigValidators {
+  bool: NativeConfigCheck; text: NativeConfigCheck; strings: NativeConfigCheck; argv: NativeConfigCheck;
+  number(min?: number, max?: number, integer?: boolean): NativeConfigCheck;
+  words(values: readonly string[]): NativeConfigCheck;
+  block(fields: Record<string, NativeConfigCheck>): NativeConfigCheck;
+}
+
 /** Adapter API 1, including the merged revision-3 members frozen in issue #451. */
 export interface AdapterDefinition {
   api: 1;
@@ -120,6 +146,8 @@ export interface AdapterDefinition {
   roles: readonly string[];
   optional?: boolean;
   defaultOnRoster?: boolean;
+  /** A legacy enable switch gates new starts, not retained sockets or queues. */
+  enabledSwitchStartOnly?: boolean;
   trust: { onPrem: boolean; hubSandboxed: boolean };
   start: {
     forms: readonly StartForm[];
@@ -127,17 +155,30 @@ export interface AdapterDefinition {
     ownsTerminal(form: StartForm): boolean;
     launch(ctx: LaunchContext): LaunchPlan;
     create?(ctx: CreateContext): PeerAdapter;
+    daemonPort?: DaemonEngine;
     preflight?(ctx: StartRequest): string | undefined;
     version?(ctx: VersionContext): string | undefined;
     conductorStartable: boolean;
+    passthrough?: boolean;
     autoStart?: "pi.auto_start";
+    exclusiveStartRefusal?: string;
+    refreshTools?: boolean;
+    explicitHeadlessMode?: boolean;
+    planCommand?(form: StartForm): string;
+    acpCommand?(command: readonly string[], model?: string): string[];
+    reconfigureWhileAttached?: boolean;
     unattended?: boolean;
     hubSwitches: readonly string[];
     ownedFlags: readonly string[];
     conductorStartArgs?(args: string[]): { mode?: StartForm } | Error;
   };
   identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin" };
-  attach?: { pullOnlyForms?: readonly StartForm[] };
+  attach?: {
+    pullOnlyForms?: readonly StartForm[];
+    recoveryLaunch?(instance: string): Record<string, unknown>;
+    pullOnlyNotice?: string;
+    admission?: { reservedRefusal: string; watchRefusal: string };
+  };
   permission: {
     modes: Partial<Record<PermissionMode, NativeModeSpec>>;
     grants?: Partial<Record<PermissionMode, string>>;
@@ -145,30 +186,79 @@ export interface AdapterDefinition {
     unmanaged?: string;
     unmanagedForms?: readonly StartForm[];
     unmanagedNote?: string;
+    unmanagedStatusNote?: string;
+    trackUnattended?: boolean;
   };
   session: {
+    nativeRevert?: boolean;
+    crashPlan?(meta: Record<string, unknown>): { resume?: Record<string, string>; how: string; fresh?: Record<string, string>; tui?: true };
+    unrecordedTerminal?: "always" | "tui";
+    continuityBookmark?(peer: RecoveryPeer, binding?: TerminalBinding): Pick<RecoveryContinuityBookmark, "pi">;
+    continuity?: { key: string; parse(value: unknown): unknown | undefined };
     idField: "sessionId" | "threadId";
     currentId(peer: PeerAdapter): string | undefined;
     configDirEnv?: "CODEX_HOME" | "CLAUDE_CONFIG_DIR";
-    resumeArgv?(binding: TerminalBinding, fresh: boolean): string[];
+    resumeArgv?(binding: SessionRef, fresh: boolean): string[];
     transcriptPath?(binding: TerminalBinding): string | undefined;
     transcriptExists?(binding: TerminalBinding): boolean | "unknown";
     zeroTurnFresh?: boolean;
+    zeroTurn?(ctx: { stateDir: string; binding: TerminalBinding; phase: "plan" | "attach" | "verify" }): boolean;
+    restoreArgs?(peer: RecoveryPeer): Record<string, string>;
+    recoveryRefusal?(peer: RecoveryPeer, phase?: "plan" | "restore"): string | undefined;
+    personFresh?: boolean;
+    missingEvidence?: "rollout" | "transcript";
+    /** Fixed source-only compatibility reads used by released recovery coordinators. */
+    legacyTargetSupport?: { file: "src/hub/peer-catalog.ts"; exportName: "OPTIONAL_PEERS"; refusal: string };
+    legacyHeadlessArgv?: { file: "src/hub/start-mode.ts"; exportName: "START_MODE_PEERS"; argv: readonly string[] };
     freshOnRestore?: boolean;
+    /** The daemon restores recorded startup options before auto-starting this kind. */
     restoreOnStart?: boolean;
+    /** Recovery passes the verified native session id to this kind's start command. */
+    resumeById?: boolean;
     launchKind?: string;
     launchRecord?: boolean;
     crashIdentity?(row: unknown): { sessionId?: string; sessionFile?: string };
   };
   turnEnd: "adapter" | "native-hook";
-  budget?: { account: string; reader?: QuotaReader; context?: ContextReader; checkpoint?: boolean };
+  reporting?: { tokensNotReported?: boolean };
+  /** Legacy native routing policy; external definitions cannot claim these host-specific policies. */
+  routing?: {
+    localAllowedRefusal?: string;
+    longContext?: "backend-limit" | "skip-owner";
+    preferredTier?: boolean;
+    handoffPriority?: number;
+    trace?: "route" | "backend";
+    backendLabel?: string;
+  };
+  budget?: { account: string; quotaExempt?: boolean; instrumented?: boolean; reader?: QuotaReader; context?: ContextReader; checkpoint?: boolean; resetSoftTokensOnResume?: boolean };
+  configuration?: {
+    schema?(ports: NativeConfigValidators): Record<string, NativeConfigCheck>;
+    routingSchema?(ports: NativeConfigValidators): Record<string, NativeConfigCheck>;
+    settings?: readonly SettingDef[];
+    restartReasons?: Readonly<Record<string, string>>;
+    validateEffective?(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void;
+  };
   capabilities?: { manifest?(peer: PeerAdapter): Promise<CapabilityManifest>; watch?: boolean };
-  init?: { templateFragment?: string; mcpFile?: string };
+  init?: {
+    templateFragment?: string;
+    mcpFile?: string;
+    /** Pure planner; the CLI host owns every write and cleanup. */
+    mcpPlan?(ctx: { projectRoot: string; stateDir: string; entrypoint: string; form: StartForm }): { file: string; tracked: boolean; changed: boolean; action: string };
+  };
   cli: {
     command: string;
+    /** Restrictions only; core identity remains authoritative. */
+    authority?: "person" | "conductor";
+    personOnlyFlags?: readonly string[];
     startWords(form: StartForm): string[];
     stopNotice?(form: StartForm, owner: PeerAdapter | undefined): string;
+    previewArgs?: readonly string[];
+    retainedTerminalNotice?(instance: string, form: StartForm | undefined, resumeCommand: string): string | undefined;
+    rosterReturnNotice?(resumeCommand: string): string;
   };
-  display: { palette: { fg: string; bg: string } };
+  display: { palette: { fg: string; bg: string; tone?: string; ansi?: string } };
   hooks?: Partial<NativeHooks>;
 }
+
+/** Explicit project declarations, passed by the bound host. No process-global instance registration. */
+export type KindMap = Readonly<Record<string, { readonly kind: string }>>;