@staix/agent-hub 0.12.22 → 0.12.24

package/src/cli/pet.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { recoveryLock, recoveryRunner } from "../hub/recovery-store.ts";
+import { processLiveness } from "../pi/process-signature.ts";
+import { characterAttentionLine } from "./attention.ts";
+import type { CharacterId } from "../pet/frame.ts";
+import type { NeedItem, NeedsSummary } from "../ui/needs.ts";
+
+const id = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9_.:-]{1,128}$/.test(value);
+const count = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+
+/** Parsed status metadata is copied by allowlist; source text and extra fields are never rendered. */
+export function parseNeedsSummary(raw: unknown): NeedsSummary | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+  const row = raw as Record<string, unknown>;
+  if (!count(row.act) || !count(row.watch) || typeof row.state !== "string" || !["waiting", "blocked", "review", "working", "idle", "sleeping"].includes(row.state)) return;
+  let first: NeedItem | undefined;
+  if (row.first !== undefined) {
+    if (!row.first || typeof row.first !== "object" || Array.isArray(row.first)) return;
+    const item = row.first as Record<string, unknown>;
+    if (typeof item.kind !== "string" || typeof item.level !== "string" || !["approval", "default", "storage", "recovery", "delivery", "review", "budget", "offline"].includes(item.kind) || !["act", "watch"].includes(item.level)) return;
+    if (item.peer !== undefined && !id(item.peer)) return;
+    if (item.id !== undefined && !id(item.id) && !(count(item.id) && item.id > 0)) return;
+    if (item.until !== undefined && !count(item.until) || item.since !== undefined && !count(item.since)) return;
+    first = { kind: item.kind as NeedItem["kind"], level: item.level as NeedItem["level"],
+      ...(item.peer !== undefined ? { peer: item.peer as string } : {}), ...(item.id !== undefined ? { id: item.id as string | number } : {}),
+      ...(item.until !== undefined ? { until: item.until as number } : {}), ...(item.since !== undefined ? { since: item.since as number } : {}) };
+  }
+  if ((row.act + row.watch > 0) !== !!first) return;
+  if (row.act > 0 && first?.level !== "act" || row.act === 0 && first?.level === "act") return;
+  if (row.act === 0 && ["waiting", "blocked", "review"].includes(row.state) || row.act > 0 && ["working", "idle", "sleeping"].includes(row.state)) return;
+  if (first?.level === "watch" && !["recovery", "budget", "offline"].includes(first.kind) || first?.level === "act" && ["budget", "offline"].includes(first.kind)) return;
+  if (row.state === "waiting" && !["approval", "default"].includes(first?.kind ?? "")) return;
+  if (row.state === "blocked" && !["storage", "recovery", "delivery"].includes(first?.kind ?? "")) return;
+  if (row.state === "review" && first?.kind !== "review") return;
+  return { act: row.act, watch: row.watch, state: row.state as NeedsSummary["state"], ...(first ? { first } : {}) };
+}
+
+export interface PetView { summary?: NeedsSummary; unavailable: boolean; runnerUnknown?: boolean }
+export interface PetRecoveryReader { lock(): string | undefined; runner(id: string): number | "unknown" | undefined }
+const recoveryReader: PetRecoveryReader = { lock: recoveryLock, runner: recoveryRunner };
+
+/** A recovery lock is read-only evidence; this function never resumes or changes an operation. */
+export function petView(status: unknown, reader: PetRecoveryReader = recoveryReader): PetView {
+  const row = status && typeof status === "object" && !Array.isArray(status) ? status as Record<string, unknown> : undefined;
+  const base = parseNeedsSummary(row?.needs);
+  let operation: string | undefined;
+  try { operation = reader.lock(); }
+  catch { return { summary: base, unavailable: true, runnerUnknown: true }; }
+  if (!operation) return { summary: base, unavailable: !base };
+  if (!id(operation)) return { summary: base, unavailable: true, runnerUnknown: true };
+  let runner: number | "unknown" | undefined;
+  try { runner = reader.runner(operation); } catch { runner = "unknown"; }
+  const active = runner !== undefined;
+  const item: NeedItem = { kind: "recovery", level: active ? "watch" : "act", id: operation };
+  const reported = row?.recovery;
+  const included = base && reported && typeof reported === "object" && (reported as Record<string, unknown>).operationId === operation && base.watch > 0 ? 1 : 0;
+  const act = (base?.act ?? 0) + (active ? 0 : 1), watch = (base?.watch ?? 0) - included + (active ? 1 : 0);
+  const first = base?.first;
+  const precedes = !active && (!first || first.level === "watch" || !["approval", "default", "storage"].includes(first.kind));
+  const selected = precedes || first?.kind === "recovery" && first.id === operation ? item : first ?? item;
+  const state = !active && base?.state !== "waiting" ? "blocked" : base?.state ?? "sleeping";
+  return { summary: { act, watch, state, first: selected }, unavailable: !base, ...(runner === "unknown" ? { runnerUnknown: true } : {}) };
+}
+
+export function readPet(stateDir: string, reader: PetRecoveryReader = recoveryReader, alive = processLiveness): PetView {
+  let status: unknown;
+  try {
+    const row = JSON.parse(readFileSync(join(stateDir, "status.json"), "utf8"));
+    const summary = parseNeedsSummary(row.needs);
+    const expired = summary?.first?.kind === "approval" && summary.first.until !== undefined && summary.first.until <= Date.now();
+    if (!expired && Number.isSafeInteger(row.pid) && row.pid > 0 && alive(row.pid, row.pidSignature) === "live") status = row;
+  } catch { /* Missing, malformed or unconfirmed owner data is unavailable, never an empty live hub. */ }
+  return petView(status, reader);
+}
+
+export function renderPet(view: PetView, short = false, character: CharacterId = "stai"): string {
+  if (short) return view.summary?.act ? `ahub!${view.summary.act}` : "";
+  if (!view.summary) return "attention unavailable";
+  const value = view.summary;
+  const line = characterAttentionLine({ ...value, items: value.first ? [value.first] : [] }, character, 0, false, false);
+  return line + (view.unavailable ? " (status unavailable)" : "") + (view.runnerUnknown ? " (runner unknown)" : "");
+}

package/src/cli/preview.ts

@@ -1,10 +1,14 @@
+import { jcodeCommand } from "../adapters/jcode.ts";
+import { qwenSessionId } from "../hub/crash.ts";
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { loadConfig } from "../hub/daemon.ts";
 import { childEnv } from "../hub/child-process.ts";
 import { relayModelIds } from "../models/relay.ts";
 import { buildPiLaunch } from "../pi/launch.ts";
-import { buildLaunch, buildKimiLaunch, claudeObservationHooks, type Launch } from "./launch.ts";
+import { startModeOf } from "../hub/start-mode.ts";
+import { buildLaunch, buildKimiLaunch, buildQwenLaunch, buildKimiTuiLaunch, nativeLaunchEnv, claudeObservationHooks, type Launch } from "./launch.ts";
+import { kimiMcpPlan } from "./kimi-mcp.ts";
 
 const REDACTED = "[redacted]";
 const UNRESOLVED = "[unresolved]";
@@ -18,11 +22,12 @@ function nativeCommand(command: string[], trusted: string[]): string[] {
   return command.map((value, i) => value === trusted[i] ? value : REDACTED);
 }
 /** Read-only preview. Inputs passed to shared native builders are redacted before serialization. */
-export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi", raw: string[], cwd: string, stateDir: string, unattended: boolean) {
+export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen" | "jcode", raw: string[], cwd: string, stateDir: string, unattended: boolean) {
   const args = raw.filter(arg => !["--print-command", "--dry-run", "--json"].includes(arg));
   const config = loadConfig(cwd);
   const unresolved: { field: string; reason: string }[] = [];
   let launch: Launch;
+  let kimiMetadata: { mode: "tui" | "headless"; mcp: { file: string; action: string; changed: boolean; tracked: boolean } } | undefined;
   let envNames = Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]);
   const value = (flag: string) => {
     const at = args.indexOf(flag);
@@ -57,12 +62,41 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi", raw: s
     const passthrough = args.filter(arg => !["--unattended", "--safe", "--new"].includes(arg));
     launch.args = launch.args.slice(0, launch.args.length - passthrough.length).concat(passthrough.map(publicArg));
     unresolved.push({ field: "proxyUrl", reason: "assigned when the native adapter starts; preview does not start it" });
+  } else if (tool === "jcode") {
+    const mode = value("--mode") ?? "headless", model = value("--model"), profile = value("--provider-profile"), session = value("--session-id");
+    if (mode !== "headless") throw new Error("Jcode TUI driving is unverified");
+    for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--provider-profile", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Jcode option");
+    if (session !== undefined && !qwenSessionId(session)) throw new Error("invalid Jcode session identity");
+    const cmd = jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
+    launch = { cmd: cmd[0]!, args: cmd.slice(1) };
+    unresolved.push({ field: "ownedDaemon", reason: "private daemon/socket and source-pinned native identity verified at start; preview starts nothing" });
+    unresolved.push({ field: "hubTools", reason: "project MCP bridge required; native tool-call receipt remains unverified" });
+  } else if (tool === "qwen") {
+    const mode = value("--mode") ?? "headless", model = value("--model");
+    if (mode !== "headless") 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 && !qwenSessionId(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 = buildQwenLaunch(nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), 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" });
   } else if (tool === "kimi") {
     const model = value("--model");
-    launch = buildKimiLaunch(nativeCommand(config.kimi_cmd, ["kimi", "acp"]), model ? REDACTED : undefined);
-    unresolved.push({ field: "sessionId", reason: "ACP session identity is available only after native initialization" });
+    const mode = value("--mode") ?? startModeOf(config.peers, "kimi");
+    if (mode !== "tui" && mode !== "headless") throw new Error("invalid Kimi mode");
+    for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Kimi option");
+    if (mode === "headless") {
+      launch = buildKimiLaunch(nativeCommand(config.kimi_cmd, ["kimi", "acp"]), model ? REDACTED : undefined);
+      unresolved.push({ field: "sessionId", reason: "ACP session identity is available only after native initialization" });
+    } else {
+      const native = buildKimiTuiLaunch(config.kimi_cmd, model ? REDACTED : undefined);
+      launch = { ...native, cmd: native.cmd === "kimi" ? "kimi" : REDACTED, args: native.args.map(arg => arg === "--model" || arg === REDACTED ? arg : REDACTED) };
+      envNames = Object.keys(nativeLaunchEnv("kimi", childEnv())).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]);
+    }
+    const { file, action, changed, tracked } = kimiMcpPlan(cwd, stateDir, join(import.meta.dir, "../../plugins/agent-hub/server.js"), mode);
+    kimiMetadata = { mode, mcp: { file, action, changed, tracked } };
   } else {
-    const mode = value("--mode") ?? "headless";
+    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");
     for (let i = 0; i < args.length; i += 2) if (!["--mode", "--backend", "--model", "--session-id", "--session-file"].includes(args[i]!)) throw new Error("unknown Pi option");
@@ -87,5 +121,5 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi", raw: s
     unresolved.push({ field: "env.AGENTHUB_INSTANCE_ID", reason: tool === "claude" ? "injected when an existing daemon instance is read at launch; preview does not read runtime state" : "injected when a verified Orca terminal launch is recorded against the daemon; preview does not record it" });
     unresolved.push({ field: "env.AGENTHUB_LAUNCH_ID", reason: "allocated only for a verified Orca terminal launch; preview does not query Orca, allocate identity or write launch records" });
   }
-  return { tool, cmd: launch.cmd, args: launch.args, settings: tool === "claude" && launch.args.includes("--settings") ? launch.args[launch.args.indexOf("--settings") + 1] : undefined, envNames: [...new Set(envNames)].sort(), ...(launch.warning ? { warning: launch.warning } : {}), unresolved, redaction: "Arbitrary user arguments, settings, commands and configured executable overrides are redacted. Environment values are never displayed.", needs: ["Native executable, accounts and runtime readiness are not checked."] };
+  return { tool, ...(kimiMetadata ?? {}), cmd: launch.cmd, args: launch.args, settings: tool === "claude" && launch.args.includes("--settings") ? launch.args[launch.args.indexOf("--settings") + 1] : undefined, envNames: [...new Set(envNames)].sort(), ...(launch.warning ? { warning: launch.warning } : {}), unresolved, redaction: "Arbitrary user arguments, settings, commands and configured executable overrides are redacted. Environment values are never displayed.", needs: ["Native executable, accounts and runtime readiness are not checked."] };
 }

package/src/cli/reset.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { Bus } from "../hub/bus.ts";
 import { DeliveryJournal } from "../hub/delivery-journal.ts";
 import type { Project } from "../hub/registry.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "../hub/db-timeout.ts";
 
 /** Agent session resume pointers. `pi-sessions/` holds Pi transcripts, history rather than pointers, and stays. */
 export const SESSION_POINTERS = ["sessions.json", "claude-session.json", "claude-context.json"];
@@ -60,6 +61,7 @@ export function planReset(stateDir: string, projectId: string): ResetPlan {
   const quiet = !existsSync(`${file}-wal`) || !existsSync(`${file}-shm`);
   const db = quiet ? new Database(`file:${file.replace(/[%?#]/g, (c) => `%${c.charCodeAt(0).toString(16)}`)}?immutable=1`, constants.SQLITE_OPEN_READONLY | constants.SQLITE_OPEN_URI) : new Database(file, { readonly: true });
   try {
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     const has = (table: string) => !!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
     const peers = (table: string) => has(table) ? (db.query(`SELECT peer FROM ${table} ORDER BY peer`).all() as { peer: string }[]).map((row) => row.peer) : [];
     plan.budgetPauses = peers("budget_pauses");
@@ -121,6 +123,7 @@ export function resetRuntime(stateDir: string, project: Project): { settled: str
     } finally { bus.closeJournal(); }
     const db = new Database(file);
     try {
+      db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
       db.transaction(() => {
         for (const table of ["budget_pauses", "conductor_holds"]) {
           if (db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table)) db.run(`DELETE FROM ${table}`);

package/src/cli/status-lines.ts

@@ -1,7 +1,7 @@
 import type { ContextView } from "../hub/context-window.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; toolsOnly?: string; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string; coolingUntil?: string; failures?: number; failingUntil?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */
@@ -15,31 +15,3 @@ export function backendLabel(backend: BackendRow): string {
 export function contextLine(reading: ContextView, time = (at: number) => new Date(at).toISOString()): string {
   return `context ${reading.used === null ? "unknown" : `${Math.round(reading.used * 100)}%`} (${reading.freshness}${reading.source ? `, ${reading.source}` : ""}${reading.measuredAt !== null ? `, measured ${time(reading.measuredAt)}` : ""})`;
 }
-
-export function peerLine(id: string, p: PeerRow): string {
-  return `  ${id.padEnd(8)} ${(p.state ?? "unknown").padEnd(8)} queued ${p.queued ?? 0}` +
-    // Which queued messages the peer will not wait out the batch window for (issue #41).
-    (p.queuedImportant ? ` (${p.queuedImportant} important)` : "") +
-    (p.needsReview ? `  needs review ${p.needsReview}` : "") +
-    (p.liveAccepted?.length ? `  awaiting settlement ${p.liveAccepted.join(", ")} (adapter completion; Claude: reply or hub_delivery_done; task state is independent)` : "") +
-    (p.heldBy ? `  ${p.holdNote ?? `held by needs_review ${p.heldBy}; ahub queue resolve ${p.heldBy} --action completed|retry|discard --reason <text>`}` : "") +
-    (p.oldestQueuedAt !== undefined ? `  oldest ${Math.max(0, Math.floor((Date.now() - p.oldestQueuedAt) / 1000))}s` : "") +
-    (p.attached === false ? "  disconnected" : "") +
-    (p.toolsOnly ? `  ${p.toolsOnly}` : "") +
-    (p.permissionMode && p.permissionMode !== "ask" ? `  permission: ${p.permissionMode}` : "") +
-    (p.paused ? `  (${p.paused})` : "") +
-    (p.servedBy ? `  last call: ${p.servedBy}` : "") +
-    // Which backend the peer asked for on its last turn: without it, telling a Pi DGX turn from an MLX one
-    // meant reading status.json by hand.
-    (p.requestedModel ? `  model: ${p.requestedModel}` : "") +
-    (p.context ? `  ${contextLine(p.context)}` : "");
-}
-
-export function backendLine(backend: BackendRow): string {
-  return `  model    ${backendLabel(backend)} ${backend.state ?? "unknown"} active ${backend.active ?? 0}` +
-    (backend.requestedModel ? ` requested ${backend.requestedModel}` : "") +
-    (backend.actualModel ? ` actual ${backend.actualModel}` : "") +
-    (backend.provider ? ` provider ${backend.provider}` : "") +
-    (backend.coolingUntil ? ` cooling down until ${backend.coolingUntil} after ${backend.failures ?? "?"} failures` : "") +
-    (backend.failingUntil ? ` last dispatch failed, no load moves until ${backend.failingUntil}` : "");
-}

package/src/cli/tail-render.ts

@@ -8,6 +8,7 @@ export function renderTailEvent(e: BusEvent): string {
   }
   if (e.t === "overflow") return `  ! ${e.peer}'s queue is full: dropped ${e.env.id} (from ${e.env.from})`;
   if (e.t === "stale") return `  . dropped ${e.env.id} (from ${e.env.from}) for ${e.peer}: ${e.reason}`;
+  if (e.t === "off_roster") return `  . ${e.env.id} retained off roster for ${e.peers.join(", ")}`;
   if (e.t === "quiet") return `  . ${e.env.id} (from ${e.env.from}) not delivered to ${e.peers.join(", ")}: turn-free cohort`;
   const { env } = e;
   const note = e.dropped === "hop" ? " [not delivered: hop limit]" : e.dropped === "fyi" ? " [fyi: record only]" : "";

package/src/cli/terminal-recovery.ts

@@ -154,7 +154,7 @@ export interface RecordedTerminalLaunch {
 }
 
 const MAX_WAIT_MS = 10 * 60 * 1000;
-const MAX_COMMAND_MS = 30_000;
+export const MAX_COMMAND_MS = 30_000;
 /** #215: a replacement's readiness is awaited in slices this long, checking between them whether its launcher still runs. */
 const EXIT_SLICE_MS = 5_000;
 const ALLOWED_ENV = ["CODEX_HOME", "CLAUDE_CONFIG_DIR"] as const;
@@ -273,6 +273,32 @@ function defaultRunner(executable: string): CommandRunner {
   };
 }
 
+/** The Orca executable a start or a recovery would run (`orca`, or what the environment pins). */
+export const orcaExecutable = (): string => resolveOrcaExecutable();
+
+/**
+ * #269: the Orca worktree a terminal for this project can be opened in: the one this process runs in, or the one the
+ * last recorded `ahub <peer>` launch of this project used. Undefined when there is none or the record does not read.
+ * ponytail: the environment's worktree is taken as this project's; a hub started from another project's Orca terminal
+ * (`ahub --project`, the dashboard manager's start, an upgrade or restart that brings several projects up from one
+ * terminal) opens the terminal there and `ahub <peer>` then fails its root readback. Ask Orca for the worktree's path
+ * and compare it if that case shows up.
+ */
+export function startTerminalWorktree(projectRoot: string, stateDir: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  if (env.ORCA_WORKTREE_ID) return env.ORCA_WORKTREE_ID;
+  const records = launchRecords(stateDir);
+  return records === "unreadable" ? undefined : records.rows.filter((row) => row.projectRoot === projectRoot).at(-1)?.worktreeId;
+}
+
+/** #269: a new Orca terminal running `command` (a complete, already quoted command line); the terminal's handle. */
+export async function openStartTerminal(worktreeId: string, command: string, title: string, options?: CommandRunner | TerminalRecoveryOptions): Promise<string> {
+  const config = normalizeOptions(options);
+  const selector = worktreeId.startsWith("id:") ? worktreeId : `id:${worktreeId}`;
+  const handle = nestedString(terminalObject(await run(config.runner, ["terminal", "create", "--worktree", selector, "--command", command, "--title", title, "--json"])), ["handle"]);
+  if (!handle) throw new Error("Orca create returned no terminal handle");
+  return handle;
+}
+
 const RECORD_FILE = "terminal-recovery.json";
 
 export function recordPath(stateDir: string): string {

package/src/cli/upgrade-runtime.ts

@@ -1,3 +1,5 @@
+import { qwenSessionId } from "../hub/crash.ts";
+import { isDatabaseBusy, isDatabaseBusyReply, RecoveryDatabaseBusy } from "../hub/recovery-error.ts";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
@@ -83,11 +85,17 @@ export function restoredTerminalArgv(entrypoint: string, projectRoot: string, bi
     ...(binding.sessionFile ? ["--session-file", binding.sessionFile] : ["--session-id", binding.sessionId])];
 }
 
+const RECOVERY_CONTROL_TIMEOUT_MS = 30_000;
+
 async function rpc(project: Project, message: Record<string, unknown>, protocol = PROTOCOL): Promise<any> {
-  const client = await ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root, projectId: project.id }, 30_000, protocol);
+  const client = await ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root, projectId: project.id }, RECOVERY_CONTROL_TIMEOUT_MS, protocol);
   try {
-    const reply = await client.request(message, 30_000);
-    if (reply.ok === false) throw new Error(reply.error ?? "recovery control request failed");
+    const reply = await client.request(message, RECOVERY_CONTROL_TIMEOUT_MS);
+    if (reply.ok === false) {
+      // An older hub has only its exact SQLite message; preserve compatibility without trusting arbitrary text.
+      if (isDatabaseBusyReply(reply)) throw new RecoveryDatabaseBusy();
+      throw new Error(reply.error ?? "recovery control request failed");
+    }
     return reply;
   } finally { client.close(); }
 }
@@ -148,7 +156,8 @@ export async function inspectRecovery(project: Project): Promise<Inspection> {
   // pid from planning time (after a reboot another process may hold it). A registry that cannot be read throws: the
   // caller reads that as not inspected, never as stopped.
   const claim = registeredProjects().find((p) => p.id === project.id);
-  const base = await inspectProject({ ...project, instanceId: claim?.instanceId ?? null, pid: claim?.pid ?? null, pidSignature: claim?.pidSignature ?? null });
+  const base = await inspectProject({ ...project, instanceId: claim?.instanceId ?? null, pid: claim?.pid ?? null, pidSignature: claim?.pidSignature ?? null }, RECOVERY_CONTROL_TIMEOUT_MS);
+  if (base.failure?.code === "database_busy") throw new RecoveryDatabaseBusy();
   const control = readControl(project.stateDir);
   const sourceProtocol = control?.protocol;
   const legacySupported = sourceProtocol !== undefined && RECOVERY_SOURCE_PROTOCOLS.includes(sourceProtocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]);
@@ -161,11 +170,16 @@ export async function inspectRecovery(project: Project): Promise<Inspection> {
     ...(control?.instanceId ? { instanceId: control.instanceId } : {}), ...(control?.protocol ? { protocol: control.protocol } : {}), ...(snapshot ? { snapshot } : {}),
   };
   let status = base.status;
-  if (!status && legacySupported) {
+  if (!status && control && sourceProtocol === PROTOCOL) return {
+    state: "unavailable", peers: [], blockers: ["runtime changed during recovery inspection"],
+    ...(control.instanceId ? { instanceId: control.instanceId } : {}), protocol: control.protocol,
+  };
+  if (!status && legacySupported && sourceProtocol !== PROTOCOL) {
     try {
       const readback = await rpc(project, { t: "status" }, sourceProtocol);
       status = readback.status;
-    } catch {
+    } catch (error) {
+      if (isDatabaseBusy(error)) throw error;
       // server.stop() runs before state-file removal, so a stopping hub briefly refuses
       // connections with its manifest still on disk. Never infer stopped from a connect
       // failure: callers poll again and see "stopped" once the manifest is gone.
@@ -176,7 +190,8 @@ export async function inspectRecovery(project: Project): Promise<Inspection> {
   if (!status || !control) return { state: "unavailable", peers: [], blockers: ["authenticated source status unavailable"] };
   let response: any;
   try { response = await rpc(project, { t: "recovery", op: "inspect", expectedInstanceId: status.instanceId }, sourceProtocol ?? PROTOCOL); }
-  catch {
+  catch (error) {
+    if (isDatabaseBusy(error)) throw error;
     // A stop can complete between authenticated status and the second read. Never infer stopped
     // from a connection failure: the coordinator will inspect the ownership manifest again.
     return { state: "unavailable", instanceId: status.instanceId, version: status.version, protocol: status.protocol,
@@ -224,6 +239,10 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     const reconnectOnly: string[] = [];
     for (const peer of source.peers) {
       if (peer.state === "offline") continue;
+      if (peer.id === "kimi" && peer.args?.mode === "tui") {
+        blockers.push("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)");
+        continue;
+      }
       if (peer.id === "claude") {
         // #206: managed means a live `ahub claude` launcher recorded for this daemon and a session record written by
         // that launch. Anything else cannot be bound to the attached session, so its record never becomes a target.
@@ -251,14 +270,17 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
           continue;
         }
       }
+      if (peer.id === "jcode") { blockers.push("jcode: source-pinned native load cannot prove conversation identity; end the peer and make a new recovery plan before effects"); continue; }
       if (peer.id === "codex" || peer.id === "claude") {
         const session = peer.id === "codex" ? peer.threadId : peer.sessionId;
         if (!session) blockers.push(`${peer.id}: original conversation ID is unknown; manual-required; next action: reconnect the original native session and make a new recovery plan`);
         else sessions[peer.id] = session;
+      } else if (peer.id === "qwen" || peer.id === "jcode") {
+        if (!qwenSessionId(peer.sessionId)) blockers.push(`${peer.id}: saved ACP session identity unavailable; end the peer and make a new recovery plan`);
       } else if (peer.id === "pi" && peer.args?.mode === "tui") {
         if (!peer.sessionId) blockers.push("pi: original session ID is unknown; manual-required; next action: reconnect the original Pi session and make a new recovery plan");
         else sessions.pi = { sessionId: peer.sessionId, ...(peer.sessionFile ? { sessionFile: peer.sessionFile } : {}), ...(peer.args.backend ? { backend: peer.args.backend } : {}), ...(peer.args.model ? { model: peer.args.model } : {}) };
-      } else if (peer.id !== "kimi" && peer.id !== "local" && peer.id !== "pi") blockers.push(`${peer.id}: no automatic recovery adapter`);
+      } else if (peer.id !== "kimi" && peer.id !== "qwen" && peer.id !== "local" && peer.id !== "pi") blockers.push(`${peer.id}: no automatic recovery adapter`);
     }
     const terminals = await inspectTerminals(project.root, sessions, {
       ...terminalOptions(run), stateDir: project.stateDir, instanceId: source.instanceId,
@@ -435,6 +457,16 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
       // A probe that did not answer (killed, a null exit code maps to 1) says nothing about the target: retry.
       if (!Number.isInteger(read)) throw new Error(`the staged target's control protocol could not be read (probe exit ${protocol.code}); staged package retained, runtimes unchanged; resume again once it can run`);
       if (read !== PROTOCOL) throw new FinalRefusal("target protocol requires a newer coordinator; staged package retained, runtimes unchanged");
+      if (op.plan.projects.some(p => p.source.peers.some(peer => peer.id === "qwen" && peer.state !== "offline"))) {
+        const catalog = join(target.root, "src/hub/peer-catalog.ts");
+        const peers = existsSync(catalog) ? /export const OPTIONAL_PEERS\s*=\s*\[([^\]]*)\]/.exec(readFileSync(catalog, "utf8"))?.[1] : undefined;
+        if (!peers || !/["']qwen["']/.test(peers)) throw new FinalRefusal("target does not support Qwen; end Qwen and make a new plan, or choose a supporting target; runtimes unchanged");
+      }
+      if (op.plan.projects.some(p => p.source.peers.some(peer => peer.id === "jcode" && peer.state !== "offline"))) {
+        const catalog = join(target.root, "src/hub/peer-catalog.ts");
+        const peers = existsSync(catalog) ? /export const OPTIONAL_PEERS\s*=\s*\[([^\]]*)\]/.exec(readFileSync(catalog, "utf8"))?.[1] : undefined;
+        if (!peers || !/["']jcode["']/.test(peers)) throw new FinalRefusal("target does not support Jcode; end it and make a new plan, or choose a supporting target; runtimes unchanged");
+      }
       // Reconnect-only (#206) and fresh sessions (#215) need a target hub that reads recovery-waivers.json.
       if (op.plan.projects.some((p) => p.reconnectOnly?.length || p.freshStart?.length) && !targetReadsWaivers({ targetRoot: target.root })) {
         throw new FinalRefusal(`target ${op.plan.version} predates recovery waivers, so its hub could never accept a reconnect-only Claude or a fresh Codex start; staged package retained, runtimes unchanged; choose a newer target once this operation is cancelled or ended`);
@@ -498,11 +530,25 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
       const live = await inspectRecovery(planned.project);
       if (live.instanceId !== progress.instanceId) throw new Error("target daemon changed before peer restore");
       if (group === "native") {
-        for (const peer of planned.source.peers.filter((p) => ["kimi", "local", "pi"].includes(p.id) && p.state !== "offline" && !(p.id === "pi" && p.args?.mode === "tui"))) {
+        for (const peer of planned.source.peers.filter((p) => ["kimi", "qwen", "jcode", "local", "pi"].includes(p.id) && p.state !== "offline" && !(p.id === "pi" && p.args?.mode === "tui"))) {
           const current = live.peers.find((p) => p.id === peer.id);
           if (current && current.state !== "offline") continue;
           const args = [peer.id];
-          for (const key of ["mode", "backend", "model", "route"]) if (typeof peer.args?.[key] === "string") args.push(`--${key}`, peer.args[key]!);
+          if (peer.id === "kimi" && peer.args?.mode === "tui") throw new Error("Kimi's pull-only terminal cannot be restored as a headless worker; end it in that terminal and make a new recovery plan");
+          for (const key of ["mode", "backend", "model", "route"]) if (!(peer.id === "kimi" && key === "mode") && typeof peer.args?.[key] === "string") args.push(`--${key}`, peer.args[key]!);
+          if (peer.id === "kimi") {
+            // ponytail: a staged target's fixed catalog is the capability signal; replace this source check with
+            // an explicit recovery capability once targets publish one. Older targets have only headless Kimi.
+            const modeFile = join(op.targetRoot!, "src/hub/start-mode.ts");
+            const modes = existsSync(modeFile) ? /export const START_MODE_PEERS\s*=\s*\[([^\]]*)\]/.exec(readFileSync(modeFile, "utf8"))?.[1] : undefined;
+            if (modes && /["']kimi["']/.test(modes)) args.push("--mode", "headless");
+          }
+          // #269: `ahub pi` without a mode now takes Pi's start mode (tui by default). This Pi ran headless (a terminal
+          // one is filtered out above), so a snapshot that recorded no mode still restores it headless.
+          if (peer.id === "pi" && typeof peer.args?.mode !== "string") args.push("--mode", "headless");
+          if (peer.id === "qwen" && peer.sessionId) args.push("--session-id", peer.sessionId);
+          if (peer.id === "jcode" && peer.sessionId) args.push("--session-id", peer.sessionId);
+          if (peer.id === "jcode" && peer.args?.providerProfile) args.push("--provider-profile", peer.args.providerProfile);
           if (peer.id === "pi") {
             const sessionFile = peer.sessionFile ?? peer.args?.sessionFile;
             if (typeof sessionFile === "string") args.push("--session-file", sessionFile);

package/src/cli/upgrade.ts

@@ -1,8 +1,9 @@
+import { databaseBusySite, isDatabaseBusy, RecoveryDatabaseBusy } from "../hub/recovery-error.ts";
 import { Database } from "bun:sqlite";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { PROJECT_COLUMNS, projectFromRow, type Project } from "../hub/registry.ts";
+import { REGISTRY_DB_BUSY_TIMEOUT_MS, PROJECT_COLUMNS, projectFromRow, type Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.ts";
 import { acquireRecoveryLock, claimRunner, coordinatorCurrent, readOperation, recoveryCommand, recoveryLock, releaseRecoveryLock, writeOperation } from "../hub/recovery-store.ts";
 
@@ -82,6 +83,7 @@ export interface RecoveryOperation {
   pluginInstalled?: boolean;
   globalInstalled?: boolean;
   error?: string;
+  failure?: { code: "database_busy"; retryable: true; site?: string[] };
   /** #215: every human disposition, in order. Operator reasons only; never task or message text. */
   audit?: { at: number; action: "fresh-session" | "stop-and-archive"; reason: string; peer?: string; projects: string[] }[];
   disposition?: { choice: "stop-and-archive"; at: number; projects: Record<string, string> };
@@ -288,6 +290,7 @@ export function registeredProjects(home = hubHome()): Project[] {
   if (!existsSync(path)) return [];
   const db = new Database(path, { readonly: true });
   try {
+    db.run(`PRAGMA busy_timeout = ${REGISTRY_DB_BUSY_TIMEOUT_MS}`);
     // #226: a registry no current release opened yet has no signature column, and this read never migrates.
     const signed = (db.query("PRAGMA table_info(projects)").all() as { name: string }[]).some((c) => c.name === "pid_signature");
     return (db.query(`SELECT ${PROJECT_COLUMNS}${signed ? ", pid_signature" : ""} FROM projects ORDER BY root`).all() as Record<string, unknown>[]).map(projectFromRow);
@@ -433,10 +436,11 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
     if (op.disposition) {
       // The stop-and-archive in progress keeps its own cause; resume never runs an operation being abandoned.
       op.error ??= `a stop-and-archive of this operation is partway; ${nextActionsText(op, await liveProjects(op, driver.inspect))}`;
+      delete op.failure;
       op.phase = "blocked"; save();
       return op;
     }
-    op.phase = "running"; delete op.error; save();
+    op.phase = "running"; delete op.error; delete op.failure; save();
     step("stage");
     const target = await driver.stage(op);
     if (op.targetDigest && (target.root !== op.targetRoot || target.digest !== op.targetDigest)) throw new FinalRefusal("staged target changed since operation started");
@@ -494,7 +498,13 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
           await driver.commit(project, id, planned.source.instanceId!);
           const deadline = driver.now() + 30_000;
           do {
-            live = await driver.inspect(project);
+            try { live = await driver.inspect(project); }
+            catch (error) {
+              if (!isDatabaseBusy(error)) throw error;
+              // A committed source may still be stopping. Contention is an
+              // unconfirmed read here, not a refusal; keep the existing bound.
+              live = { state: "unavailable", peers: [], blockers: ["database_busy"] };
+            }
             if (live.state === "stopped") break;
             if (live.instanceId && live.instanceId !== planned.source.instanceId) throw new Error(`${project.id}: another daemon started during shutdown`);
             await driver.sleep(100);
@@ -556,6 +566,7 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
     releaseRecoveryLock(id, home); op.phase = "completed"; step("completed");
   } catch (error) {
     // #215: every runner error ends with the choices status shows, read from every open source, never only this one.
+    if (isDatabaseBusy(error)) { op.failure = { code: "database_busy", retryable: true, site: databaseBusySite(error) }; error = new RecoveryDatabaseBusy(); }
     if (error instanceof FinalRefusal) op.final = true;
     const next = nextActionsText(op, await liveProjects(op, driver.inspect));
     op.phase = "blocked"; op.error = `${error instanceof Error ? error.message : "recovery failed"}; ${next}`; save();
@@ -575,7 +586,7 @@ export function publicOperation(op: RecoveryOperation, runnerPid?: number | "unk
       ...(p.restarts?.length ? { restarts: p.restarts.length } : {}) })),
     pluginInstalled: !!op.pluginInstalled, globalInstalled: !!op.globalInstalled,
     ...(!targetReadsWaivers(op) && op.projects.some((p) => failedPeers(op, p).length) ? { freshSession: `not offered: target ${op.plan.version} cannot read recovery waivers, so it could not release a new session` } : {}),
-    ...(op.error ? { error: op.error } : {}), ...(op.disposition ? { disposition: op.disposition } : {}), ...(op.audit ? { audit: op.audit } : {}), next };
+    ...(op.error ? { error: op.error } : {}), ...(op.failure ? { failure: op.failure } : {}), ...(op.disposition ? { disposition: op.disposition } : {}), ...(op.audit ? { audit: op.audit } : {}), next };
 }
 
 /** Escape a blocked preflight without abandoning a stopped runtime or an uncertain terminal mutation. */
@@ -605,8 +616,12 @@ export async function abortRecovery(id: string, driver: RecoveryDriver, home = h
       const state = live[planned.project.id];
       if (state?.recovery?.operationId === id && state.recovery.phase !== "released") await driver.abort(planned.project, id, planned.source.instanceId!);
     }
+    delete op.error; delete op.failure;
     op.phase = "cancelled"; op.step = "cancelled"; op.updatedAt = driver.now();
     writeOperation(id, op, home); releaseRecoveryLock(id, home);
+  } catch (error) {
+    if (isDatabaseBusy(error)) throw new RecoveryDatabaseBusy();
+    throw error;
   } finally { releaseRunner(); }
 }
 
@@ -658,6 +673,7 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
         (progress.fresh ??= {})[peer] = { lost: binding.sessionId, reason, at };
       }
       (op.audit ??= []).push({ at, action: "fresh-session", reason, peer, projects: failed.map((p) => p.id) });
+      delete op.error; delete op.failure;
       op.updatedAt = at; writeOperation(id, op, home);
       return op;
     }
@@ -687,6 +703,7 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
     abandoned(op); // #227: in the same write as the disposition
     (op.audit ??= []).push({ at, action: "stop-and-archive", reason, projects: acts.map((a) => a.planned.project.id) });
     // Recorded before the first act: a crash inside a stop leaves a disposition that resume refuses to override.
+    delete op.failure;
     op.updatedAt = driver.now(); writeOperation(id, op, home);
     try {
       for (const { planned, live, act } of acts) {
@@ -699,12 +716,13 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
         op.updatedAt = driver.now(); writeOperation(id, op, home);
       }
     } catch (error) {
+      if (isDatabaseBusy(error)) { op.failure = { code: "database_busy", retryable: true, site: databaseBusySite(error) }; error = new RecoveryDatabaseBusy(); }
       op.phase = "blocked"; op.updatedAt = driver.now();
       op.error = `stop-and-archive stopped partway and keeps the lock: ${error instanceof Error ? error.message : "disposition failed"} (a committed source stops by itself); ${nextActionsText(op, await liveProjects(op, driver.inspect))}`;
       writeOperation(id, op, home);
       throw error;
     }
-    delete op.error;
+    delete op.error; delete op.failure;
     op.phase = "cancelled"; op.step = "disposed: stop-and-archive (abandoned, not completed)"; op.updatedAt = driver.now();
     writeOperation(id, op, home); releaseRecoveryLock(id, home);
     return op;

package/src/cli/watch.ts

@@ -0,0 +1,31 @@
+import type { Activity } from "../hub/activity.ts";
+import { paint, stateTone, terminalText, wrap } from "./console-state.ts";
+
+export function renderActivity(peer: string, item: Activity, columns: number, color: boolean, noThoughts = false): string[] {
+  if (noThoughts && item.kind === "thought") return [];
+  const width = Math.max(20, Math.floor(columns));
+  const time = new Date(item.at).toISOString().slice(11, 19);
+  const header = `${time} ${peer} ${item.kind} (turn ${item.turn})`;
+  const tone = item.kind === "turn_end" ? stateTone("idle") : "info";
+  return [...wrap(header, width).map(text => paint([{ text, tone }], color)),
+    ...wrap(terminalText(item.text), width - 4, 0).map(text => paint([{ text: `    ${text}` }], color))];
+}
+export interface WatchClient {
+  request(msg: Record<string, unknown>): Promise<any>;
+  onPush: (msg: any) => void;
+  onClose: (code: number, reason: string) => void;
+  close(): void;
+}
+/** This view only watches and reads status. No prompt, permission or command request exists here. */
+export async function attachWatch(client: WatchClient, peer: string, write: (text: string) => void, options: { columns: () => number; color: boolean; noThoughts: boolean }): Promise<void> {
+  client.onPush = msg => {
+    if (msg.t !== "activity" || msg.peer !== peer || !msg.item || typeof msg.item.text !== "string" || !Number.isFinite(msg.item.at) || !Number.isSafeInteger(msg.item.turn)) return;
+    for (const line of renderActivity(peer, msg.item, options.columns(), options.color, options.noThoughts)) write(line);
+  };
+  const watched = await client.request({ t: "watch", peer });
+  if (watched.ok !== true) throw new Error(watched.error ?? "hub does not support watch; upgrade it before using this view");
+  const status = await client.request({ t: "status" });
+  if (status.ok === false) throw new Error(status.error ?? "watch connection closed");
+  const row = status.status?.peers?.[peer];
+  if (row) for (const line of wrap(`${peer}: ${row.state ?? "unknown"}; context ${row.context?.used ?? "unknown"}; q or Ctrl+C quits (approvals: ahub console)`, options.columns())) write(line);
+}