@staix/agent-hub 0.12.32 → 0.12.34

package/src/adapters/definitions/native-cli-preview-pi.ts

@@ -0,0 +1,36 @@
+import { join, resolve } from "node:path";
+import type { Launch } from "../../cli/launch.ts";
+import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+
+export function previewPi(ctx: NativePreviewContext) {
+  const { args, stateDir, cliDir, config } = ctx;
+  const { relayModelIds, buildPiLaunch, startModeOf } = ctx.helpers;
+  const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
+  let envNames = state.envNames;
+  let launch: Launch;
+  const mode = value("--mode") ?? startModeOf(config.peers, "pi"); // #269: the same default `ahub pi` takes
+  const backend = value("--backend") ?? config.pi.backend;
+  if (!["headless", "tui"].includes(mode) || !["auto", "dgx", "mlx"].includes(backend) || (value("--session-id") && value("--session-file"))) throw new Error("invalid Pi options");
+  if (args.includes("--replace-session") && (!value("--session-file") || value("--session-id"))) throw new Error("--replace-session requires --session-file, without --session-id");
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--replace-session") continue;
+    if (!["--mode", "--backend", "--model", "--session-id", "--session-file"].includes(args[i]!) || !value(args[i]!)) throw new Error("unknown Pi option");
+    i++;
+  }
+  if (args.includes("--replace-session")) unresolved.push({ field: "session replacement", reason: "requires a person, a validated managed file and an offline settled owner at runtime; preview changes nothing" });
+  const models = relayModelIds({ enableHubAuto: true, mlx: config.mlx.enabled === false ? undefined : config.mlx, mlxAlias: "mlx/fast", allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast } });
+  const pi = buildPiLaunch({
+    stateDir, cmd: nativeCommand(config.pi.cmd, ["pi"]), mode: mode as "headless" | "tui", backend: backend as "auto" | "dgx" | "mlx",
+    ...(value("--model") ? { model: REDACTED } : {}),
+    ...(value("--session-id") ? { sessionId: REDACTED } : {}),
+    ...(value("--session-file") ? { sessionFile: REDACTED } : {}),
+    relay: { url: UNRESOLVED, token: UNRESOLVED, models: models.map(id => ({ id })) },
+    tools: [], preamble: REDACTED, maxSteps: config.pi.max_steps,
+  }, {}, resolve(join(cliDir, "../pi/extension.ts")), UNRESOLVED, UNRESOLVED);
+  launch = pi;
+  envNames = Object.keys(pi.env).concat(["PATH", "HOME", "USER", "SHELL", "TMPDIR", "TERM", "TERM_PROGRAM", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "CODEX_HOME"].filter(key => process.env[key] !== undefined));
+  if (mode === "tui") envNames.push("AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR");
+  unresolved.push({ field: "bridge/relay endpoints and owner credentials", reason: "assigned at runtime; preview does not bind a server or start a model" });
+  if (!value("--session-id") && !value("--session-file")) unresolved.push({ field: "sessionId", reason: "new native session identity is not allocated by preview" });
+  return finishPreview(ctx, launch, envNames, unresolved, undefined);
+}

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

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import type { Launch } from "../../cli/launch.ts";
+import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+
+export function previewQwen(ctx: NativePreviewContext) {
+  const { tool, args, cwd, stateDir, cliDir, config } = ctx;
+  const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
+  let envNames = state.envNames;
+  let launch: Launch;
+  const mode = value("--mode") ?? "headless", model = value("--model");
+  const adapter = ctx.definition;
+  if (!(adapter.start.forms as readonly string[]).includes(mode)) throw new Error("Qwen TUI is not offered before verification");
+  for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Qwen option");
+  const sessionId = value("--session-id");
+  if (sessionId !== undefined && !adapter.session.crashIdentity?.({ sessionId }).sessionId) throw new Error("invalid Qwen session identity");
+  if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
+  launch = adapter.start.launch({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
+    userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
+  unresolved.push({ field: "nativeIdentity", reason: "Qwen Code 0.25.0 identity and permission modes are checked at ACP initialization; preview starts nothing" });
+
+  return finishPreview(ctx, launch, envNames, unresolved, undefined);
+}

package/src/adapters/definitions/native-cli-preview.ts

@@ -0,0 +1,16 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+import type { NativePreviewBuilder } from "./native-cli-preview-common.ts";
+import { previewClaude } from "./native-cli-preview-claude.ts";
+import { previewCodex } from "./native-cli-preview-codex.ts";
+import { previewKimi } from "./native-cli-preview-kimi.ts";
+import { previewPi } from "./native-cli-preview-pi.ts";
+import { previewQwen } from "./native-cli-preview-qwen.ts";
+import { previewJcode } from "./native-cli-preview-jcode.ts";
+
+// Private implementations of the fixed builtin set; neither config nor an external definition can add callbacks.
+const previews: Readonly<Record<string, NativePreviewBuilder>> = Object.freeze({
+  claude: previewClaude, codex: previewCodex, kimi: previewKimi, pi: previewPi, qwen: previewQwen, jcode: previewJcode,
+});
+export function builtinPreview(definition: AdapterDefinition): NativePreviewBuilder | undefined {
+  return Object.hasOwn(previews, definition.kind) ? previews[definition.kind] : undefined;
+}

package/src/adapters/definitions/native-config-defaults.ts

@@ -0,0 +1,19 @@
+import { join } from "node:path";
+import type { HubConfig } from "../../hub/daemon.ts";
+import type { Routing } from "../../hub/routing.ts";
+
+/** Preserve the legacy config block order and shallow native merges. */
+export const NATIVE_CONFIG_BLOCKS = ["local", "pi"] as const;
+export function nativeConfigurationDefaults(ctx: { home: string; env: Readonly<Record<string, string | undefined>>; networkAllow: string[] }) {
+  return {
+    commands: { kimi_cmd: ["kimi", "acp"], qwen_cmd: ["qwen", "--acp"], jcode_cmd: ["jcode"], jcode_home: ctx.env.JCODE_HOME ?? join(ctx.home, ".jcode"), jcode_provider_profile: "" },
+    proxy: { codex_bin: "codex" },
+    rpc: { pi: { enabled: false, auto_start: false, cmd: ["pi"], backend: "auto" as const, dgx_coding: "coding", dgx_fast: "fast", max_steps: 30 } },
+    sandbox: { local: { deny: [] as string[], bash_network: false, network_allow: ctx.networkAllow, max_steps: 30, read_allow: [] as string[] } },
+  };
+}
+export function mergeNativeConfiguration(file: Record<string, any>, defaults: HubConfig): Pick<HubConfig, "local" | "pi"> {
+  return { local: { ...defaults.local, ...file.local }, pi: { ...defaults.pi, ...file.pi } };
+}
+/** The published RPC relay stays bound while other routing leaves are reloaded. */
+export function retainNativeRouting(running: Routing): Pick<Routing, "pi"> { return { pi: running.pi }; }

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

@@ -0,0 +1,35 @@
+import type { NativeConfigCheck, NativeConfigValidators } from "../registry-types.ts";
+import type { SettingDef } from "../../hub/settings.ts";
+
+/** Native config uses the host's checked schema vocabulary, retaining its shape/path introspection. */
+export function piConfigSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
+  return { pi: v.block({ enabled: v.bool, auto_start: v.bool, cmd: v.argv, backend: v.words(["auto", "dgx", "mlx"]), dgx_coding: v.text, dgx_fast: v.text, max_steps: v.number(1, 1_000_000, true) }) };
+}
+export function localConfigSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
+  return { local: v.block({ deny: v.strings, bash_network: (value, key) => { if (value !== "direct") v.bool(value, key); }, network_allow: v.strings, max_steps: v.number(1, 1_000_000, true), read_allow: v.strings }) };
+}
+export function piRoutingSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
+  return { pi: v.block({ dgx_max_context_tokens: v.number(), mlx_max_context_tokens: v.number(), efficient_wait_ms: v.number(0, 119999) }) };
+}
+export function localRoutingSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
+  return { local: v.block({ route: v.text, fixed_model: v.text }) };
+}
+export const PI_SETTINGS: readonly SettingDef[] = [
+  { key: "pi.auto_start", group: "Start", label: "Start Pi with the hub", type: "boolean", store: "config", applies: "next use", risk: "raises", floor: false, path: ["pi", "auto_start"] },
+];
+export const PI_RESTART_REASONS: Readonly<Record<string, string>> = {
+  "pi.dgx_coding": "Published Pi relay model catalogue requires a new daemon relay",
+  "pi.dgx_fast": "Published Pi relay model catalogue requires a new daemon relay",
+  "routing.pi": "Pi relay context and model publication are bound to the running relay",
+};
+export const LOCAL_RESTART_REASONS: Readonly<Record<string, string>> = {
+  "local.deny": "Existing native sessions retain their sandbox deny policy", "local.read_allow": "Existing native sessions retain their sandbox read grants",
+  "local.bash_network": "Existing sandbox and egress proxy contracts require a new instance", "local.network_allow": "Existing egress proxy ownership requires a new instance",
+};
+export function piEffectiveConfig(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void {
+  const object = (value: unknown, key: string): Record<string, unknown> => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return fail(key, "must be an object");
+    return value as Record<string, unknown>;
+  };
+  if (object(raw.mlx, "mlx").enabled === false && object(raw.pi, "pi").backend === "mlx") fail("pi.backend", "conflicts with disabled mlx");
+}

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

@@ -0,0 +1,35 @@
+import type { ContextReading } from "../../hub/context-window.ts";
+
+export const nonnegative = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 0;
+export const positive = (n: unknown): n is number => nonnegative(n) && n > 0;
+const record = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+const object = (v: unknown): Record<string, unknown> => record(v) ? v : {};
+export function claudeContext(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const c = object(value);
+  const current = object(c.current_usage);
+  const parts = [current.input_tokens, current.cache_creation_input_tokens, current.cache_read_input_tokens];
+  const window = positive(c.context_window_size) ? c.context_window_size : null;
+  const sum = c.current_usage != null && parts.every(nonnegative) ? parts.reduce<number>((sum, n) => sum + (n as number), 0) : null;
+  const tokens = nonnegative(sum) ? sum : null;
+  const used = record(c.current_usage) && tokens !== null && nonnegative(c.used_percentage) && c.used_percentage <= 100 && window !== null ? c.used_percentage / 100 : null;
+  return { source: "claude_statusline", sessionId, measuredAt, tokens, window, used };
+}
+export function codexContext(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const c = object(value), last = object(c.last);
+  const window = positive(c.modelContextWindow) ? c.modelContextWindow : null;
+  const tokens = nonnegative(last.totalTokens) ? last.totalTokens : null;
+  return { source: "codex_token_usage", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
+}
+/** An ACP `usage_update` of the `{ used, size }` shape (Kimi 2.x): context occupancy, not consumption (#167, #285). */
+export function acpContext(usage: { used: number; size: number }, sessionId: string, measuredAt: number): ContextReading {
+  const window = positive(usage.size) ? usage.size : null;
+  const tokens = nonnegative(usage.used) ? usage.used : null;
+  // If a report ever shows used > size, the fraction clamps so a bar renders; tokens keeps the reported number.
+  return { source: "acp_usage_update", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
+}
+
+/** The coordinator supplies validated occupancy; malformed public input remains unknown. */
+export function acpContextValue(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const raw = object(value);
+  return acpContext({ used: raw.used as number, size: raw.size as number }, sessionId, measuredAt);
+}

package/src/adapters/definitions/native-daemon-kimi.ts

@@ -0,0 +1,5 @@
+/** Kimi puts its optional model switch before the configured ACP subcommand. */
+export function kimiAcpCommand(command: readonly string[], model?: string): string[] {
+  const [cmd, ...args] = command;
+  return [cmd!, ...(model ? ["--model", model, ...args] : args)];
+}

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

@@ -0,0 +1,18 @@
+import type { StartForm, StartRequest, VersionContext } from "../registry-types.ts";
+
+/** Native serialization and person-facing guidance only; the daemon retains every ownership decision. */
+export const claudeRecoveryLaunch = (instance: string): Record<string, unknown> => ({ kind: "claude-channel", peer: instance });
+export const kimiRecoveryLaunch = (instance: string): Record<string, unknown> => ({ kind: "kimi-tui", peer: instance, mode: "tui" });
+export const claudeRetainedTerminalNotice = (instance: string): string =>
+  `Stop ${instance}'s existing work in its retained terminal; removal detaches the hub connection and does not stop that terminal's work.`;
+export const piRetainedTerminalNotice = (instance: string, form: StartForm | undefined): string | undefined =>
+  form === "tui" ? claudeRetainedTerminalNotice(instance) : undefined;
+export const codexRetainedTerminalNotice = (_instance: string, _form: StartForm | undefined, resumeCommand: string): string =>
+  `Check codex's existing terminal and stop any remaining work. Its app-server and proxy stay available, but Codex 0.146.0 exits its TUI on disconnect and does not reconnect automatically; after ahub roster add codex, resume the previous session with ${resumeCommand}.`;
+export const codexRosterReturnNotice = (resumeCommand: string): string =>
+  `Codex 0.146.0 needs a manual return: resume the previous native session with ${resumeCommand}.`;
+export const jcodeStartPreflight = (request: StartRequest): string | undefined =>
+  request.form !== undefined && request.form !== "headless" ? "Jcode native TUI driving is unverified; use headless" : undefined;
+export const claudeObservedVersion = (context: VersionContext): string | undefined => context.observedVersion;
+export const codexObservedVersion = (context: VersionContext): string | undefined =>
+  (context.peer as { version?: string } | undefined)?.version ?? context.observedVersion;

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

@@ -0,0 +1,18 @@
+/** Existing native identity swatches; hub and unknown-peer styling stays in the UI. */
+export const CLAUDE_DISPLAY = { palette: { fg: "#6495ed", bg: "transparent", tone: "peerClaude", ansi: "\x1b[94m" } } as const;
+export const CODEX_DISPLAY = { palette: { fg: "#22b8cf", bg: "transparent", tone: "peerCodex", ansi: "\x1b[96m" } } as const;
+export const KIMI_DISPLAY = { palette: { fg: "#bc73ca", bg: "transparent", tone: "taskKeyword", ansi: "\x1b[35m" } } as const;
+export const PI_DISPLAY = { palette: { fg: "#c79936", bg: "transparent", tone: "attention", ansi: "\x1b[33m" } } as const;
+export const LOCAL_DISPLAY = { palette: { fg: "#4caa77", bg: "transparent", tone: "success", ansi: "\x1b[32m" } } as const;
+// These two kinds deliberately retain the existing 'other' fallback, not new public swatches.
+export const QWEN_DISPLAY = { palette: { fg: "#8a8f99", bg: "transparent", tone: "muted", ansi: "\x1b[90m" } } as const;
+export const JCODE_DISPLAY = { palette: { fg: "#8a8f99", bg: "transparent", tone: "muted", ansi: "\x1b[90m" } } as const;
+
+/** Kinds with a public named swatch; keep their exact literal types in compatibility projections. */
+export const NATIVE_DISPLAYS = { claude: CLAUDE_DISPLAY, codex: CODEX_DISPLAY, kimi: KIMI_DISPLAY, pi: PI_DISPLAY, local: LOCAL_DISPLAY } as const;
+
+const STREAM_TONES = { claude: "peerClaude", codex: "peerCodex" } as const;
+/** Stream headers historically color only these speakers, independently of their board palette. */
+export function nativeStreamTone(peer: string): (typeof STREAM_TONES)[keyof typeof STREAM_TONES] | undefined {
+  return Object.hasOwn(STREAM_TONES, peer) ? STREAM_TONES[peer as keyof typeof STREAM_TONES] : undefined;
+}

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

@@ -0,0 +1,48 @@
+import type { CreateContext, DaemonEngine, DaemonPorts } from "../registry-types.ts";
+import type { PeerAdapter } from "../../hub/peers.ts";
+
+// Load only fixed builtin modules after the pre-effect guards. A top-level LocalPeer import would
+// cycle through hub-tools and the registry while its definitions are still being initialized.
+export function createCodex(ctx: CreateContext): PeerAdapter {
+  if (!("codex" in ctx.daemon)) throw new Error("Codex requires its Codex transport options");
+  if (ctx.permission === "read-only") throw new Error("Codex has no verified read-only permission mapping");
+  const { CodexPeer } = require("../codex-appserver.ts") as typeof import("../codex-appserver.ts");
+  return new CodexPeer(ctx.instance, ctx.daemon.codex);
+}
+
+export function createKimi(ctx: CreateContext): PeerAdapter {
+  if (!("acp" in ctx.daemon)) throw new Error("Kimi requires its ACP transport options");
+  if (ctx.permission === "read-only") throw new Error("Kimi has no verified read-only permission mapping");
+  const { AcpPeer } = require("../acp.ts") as typeof import("../acp.ts");
+  return new AcpPeer(ctx.instance, ctx.daemon.acp);
+}
+
+export function createJcode(ctx: CreateContext): PeerAdapter {
+  if (!("jcode" in ctx.daemon)) throw new Error("Jcode requires its Jcode transport options");
+  if (ctx.permission === "read-only") throw new Error("Jcode has no verified read-only permission mapping");
+  const { JcodePeer } = require("../jcode.ts") as typeof import("../jcode.ts");
+  return new JcodePeer(ctx.daemon.jcode);
+}
+
+export function createPi(ctx: CreateContext): PeerAdapter {
+  if (!("pi" in ctx.daemon)) throw new Error("Pi requires its Pi transport options");
+  if (ctx.permission === "read-only") throw new Error("Pi has no verified read-only permission mapping");
+  const { PiPeer } = require("../pi.ts") as typeof import("../pi.ts");
+  return new PiPeer(ctx.instance, ctx.daemon.pi);
+}
+
+export function createLocal(ctx: CreateContext): PeerAdapter {
+  if (!("local" in ctx.daemon)) throw new Error("Local worker requires its local transport options");
+  if (ctx.permission === "read-only") throw new Error("Local worker has no verified read-only permission mapping");
+  const { LocalPeer } = require("../local-worker.ts") as typeof import("../local-worker.ts");
+  return new LocalPeer(ctx.instance, ctx.daemon.local);
+}
+
+/** Preserve existing transport option types and object identity; selection stays host-owned. */
+export const DAEMON_PORTS = {
+  "codex-appserver": (options: Extract<DaemonPorts, { codex: unknown }>["codex"]) => ({ codex: options }),
+  acp: (options: Extract<DaemonPorts, { acp: unknown }>["acp"]) => ({ acp: options }),
+  "owned-acp": (options: Extract<DaemonPorts, { jcode: unknown }>["jcode"]) => ({ jcode: options }),
+  "pi-rpc": (options: Extract<DaemonPorts, { pi: unknown }>["pi"]) => ({ pi: options }),
+  "local-worker": (options: Extract<DaemonPorts, { local: unknown }>["local"]) => ({ local: options }),
+} satisfies Record<DaemonEngine, unknown>;

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 === "codex") {
+        current = e.thread;
+        if (e.thread === binding.sessionId && e.fresh) started = true;
+      } else if (e.type === "turn_start" && e.peer === "codex" && 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.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" },
 };