@staix/agent-hub 0.32.0 → 0.34.0

package/src/adapters/compat.ts

@@ -34,21 +34,21 @@ export const COMPAT = {
     parse: out => plain(out.trim()),
     trustNote: "The model-free extension load, RPC session identity and managed tool receipt path were checked on 1.4.0 and 1.5.0. Permissions remain host-owned; account-backed inference and another version's extension contract are unverified.",
     receipt: "docs/verification/2026-11-03-pi-150-compat.md" },
-  // Transport receipts: docs/verification/2026-10-23-headless-claude-permissions.md; 2.1.310: docs/verification/2026-10-26-claude-implementer-2.1.310.md; 2.1.314 (transport and wrapper): docs/verification/2026-10-31-claude-implementer-2.1.314.md; 2.1.316: docs/verification/2026-10-31-claude-implementer-2.1.316.md; 2.1.318: docs/verification/2026-11-05-claude-implementer-2.1.318.md; host-wrapper receipt below repeats with them.
-  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309", "2.1.310", "2.1.314", "2.1.316", "2.1.318"], gate: "contract", probe: ["claude", "--version"],
+  // Transport receipts: docs/verification/2026-10-23-headless-claude-permissions.md; 2.1.310: docs/verification/2026-10-26-claude-implementer-2.1.310.md; 2.1.314 (transport and wrapper): docs/verification/2026-10-31-claude-implementer-2.1.314.md; 2.1.316: docs/verification/2026-10-31-claude-implementer-2.1.316.md; 2.1.318: docs/verification/2026-11-05-claude-implementer-2.1.318.md; 2.1.319: docs/verification/2026-11-06-claude-implementer-2.1.319.md; host-wrapper receipt below repeats with them.
+  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309", "2.1.310", "2.1.314", "2.1.316", "2.1.318", "2.1.319"], gate: "contract", probe: ["claude", "--version"],
     parse: out => plain(out.trim().replace(/ \(Claude Code\)$/, "")),
     trustNote: "The native prompt-tool transport and host-wrapper rewrite, environment isolation and replay contract have isolated receipts. No dontAsk/bypass fallback exists; another version's permission or rewrite behavior is unverified.",
-    receipt: "docs/verification/2026-11-05-claude-implementer-2.1.318.md" },
-  // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md; 0.164.0 receipt: docs/verification/2026-10-24-codex-0164-reviewer-isolation.md; 0.166.0: docs/verification/2026-10-31-codex-0166-reviewer-isolation.md
+    receipt: "docs/verification/2026-11-06-claude-implementer-2.1.319.md" },
+  // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md; 0.164.0 receipt: docs/verification/2026-10-24-codex-0164-reviewer-isolation.md; 0.166.0: docs/verification/2026-10-31-codex-0166-reviewer-isolation.md; 0.167.0 model-free only, not verified until its model-backed run: docs/verification/2026-11-06-codex-0167-reviewer-isolation.md
   "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0", "0.164.0", "0.166.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
     parse: out => plain(out.trim().replace(/^codex-cli /, "")),
     trustNote: "Every launch still proves the MCP inventory, Apps/plugins/hooks disabled, sandbox read/write denial and the binary fence; a failed leg still refuses. Trust covers only the source-level claims those probes cannot see (docs/verification/2026-10-19-reviewer-isolation.md).",
-    receipt: "docs/verification/2026-10-31-codex-0166-reviewer-isolation.md" },
-  // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md; Kimi 2.3.1: docs/verification/2026-10-25-kimi-231-reviewer-compat.md; Kimi 2.3.2: docs/verification/2026-10-26-kimi-232-reviewer-compat.md; Kimi 2.4.1: docs/verification/2026-10-31-kimi-241-reviewer-compat.md
-  "kimi-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0", "2.3.1", "2.3.2", "2.4.1"], gate: "isolation", probe: ["kimi", "--version"],
+    receipt: "docs/verification/2026-11-06-codex-0167-reviewer-isolation.md" },
+  // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md; Kimi 2.3.1: docs/verification/2026-10-25-kimi-231-reviewer-compat.md; Kimi 2.3.2: docs/verification/2026-10-26-kimi-232-reviewer-compat.md; Kimi 2.4.1: docs/verification/2026-10-31-kimi-241-reviewer-compat.md; Kimi 2.5.1: docs/verification/2026-11-06-kimi-251-reviewer-compat.md
+  "kimi-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0", "2.3.1", "2.3.2", "2.4.1", "2.5.1"], gate: "isolation", probe: ["kimi", "--version"],
     parse: out => plain(out.trim()),
     trustNote: "Every launch still builds the private config, exact two-tool agent file and task-bound MCP; the native tool allowlist behaviour of an untested version is not re-proven.",
-    receipt: "docs/verification/2026-10-31-kimi-241-reviewer-compat.md" },
+    receipt: "docs/verification/2026-11-06-kimi-251-reviewer-compat.md" },
   jcode: { label: "Jcode", verified: ["0.98.1", "0.99.0", "0.99.1"], line: { min: "0.98.0", below: "1.0.0" }, gate: "contract", probe: ["jcode", "--quiet", "version", "--json"], config: "jcode_cmd",
     parse: out => { try { const v = JSON.parse(out).semver; return typeof v === "string" ? plain(v) : undefined; } catch { return undefined; } },
     trustNote: "The ACP, serve and MCP contract was verified on 0.98.1 and 0.99.1 and steering on 0.99.0 and 0.99.1; an untested version may change them.",
@@ -57,10 +57,10 @@ export const COMPAT = {
     parse: out => plain(out.trim()),
     trustNote: "Only 1.4.2, 1.4.7 and 1.4.12 are T0-verified; the plugin MCP and hook contract of another version is unverified.",
     receipt: "docs/verification/2026-11-03-agy-1.4.12-launcher-nonce.md" },
-  qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0", "0.26.1", "0.26.4", "0.26.5"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
+  qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0", "0.26.1", "0.26.4", "0.26.5", "0.26.8"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
     parse: out => plain(out.trim()),
-    trustNote: "Native ACP identity, mode ids and permission callbacks were re-checked without inference on 0.26.4 and 0.26.5; real model turns remain unverified. Another version may change those contracts.",
-    receipt: "docs/verification/2026-11-03-qwen-0265-acp.md" },
+    trustNote: "Native ACP identity, mode ids and permission callbacks were re-checked without inference on 0.26.4, 0.26.5 and 0.26.8 (macOS arm64 and Linux x86_64); real model turns remain unverified. Another version may change those contracts.",
+    receipt: "docs/verification/2026-11-06-qwen-0268-acp.md" },
   // Receipt: docs/verification/2026-10-25-qwen-dual-output-t0.md. The dual-output contract (input file, event file, can_use_tool control requests) is its own entry:
   // the ACP receipts of the headless `qwen` entry say nothing about it, so that entry is not widened and this one carries no `line`.
   "qwen-dual": { label: "Qwen Code dual-output TUI", verified: ["0.26.1"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",

package/src/adapters/definitions/native-cli-claude-setup.ts

@@ -1,5 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
+import { stablePackageRoot } from "../../cli/install-paths.ts";
 import { realPath } from "../../hub/project.ts";
 import { VERSION } from "../../version.ts";
 
@@ -53,11 +55,11 @@ export type PluginState =
   | { state: "stale"; version: string; why: string; notices?: string[] };
 
 const safeDisplayValue = (value: unknown): string | undefined =>
-  typeof value === "string" && value.length <= 4096 && !/[\x00-\x1f\x7f]/.test(value) ? value : undefined;
+  typeof value === "string" && value.length <= 4096 && value.isWellFormed() && !/[\p{Cc}\p{Cf}]/u.test(value) ? value : undefined;
 
 function nonUserPluginNotices(plugins: InstalledPlugin[]): string[] {
   return plugins.filter(plugin => plugin.id === PLUGIN && plugin.scope !== "user").map(plugin => {
-    const scope = plugin.scope === "project" || plugin.scope === "local" ? plugin.scope : "unknown-scope";
+    const scope = safeDisplayValue(plugin.scope) ?? "unknown-scope";
     const path = safeDisplayValue(plugin.projectPath) ?? safeDisplayValue(plugin.installPath);
     const version = safeDisplayValue(plugin.version) ?? "unknown";
     return `${scope} plugin row preserved${path ? ` at ${path}` : ""} (version ${version}); setup never removes non-user scopes`;
@@ -90,14 +92,21 @@ export interface SetupStep {
  * The next thing `ahub setup` has to do, or nothing. One step at a time: the state is read again after every step,
  * because what a step leaves behind is Claude Code's business (removing a marketplace may uninstall its plugins).
  */
-export function nextStep(plugins: InstalledPlugin[], marketplaces: Marketplace[], packageRoot: string): SetupStep | undefined {
+export function nextStep(plugins: InstalledPlugin[], marketplaces: Marketplace[], packageRoot: string, personHome = homedir()): SetupStep | undefined {
   const root = real(packageRoot);
   const market = marketplaces.find((m) => m.name === MARKETPLACE);
   if (market && real(market.path ?? "") !== root) {
-    if (plugins.some(plugin => plugin.id === PLUGIN && plugin.scope !== "user")) return { why: `the ${MARKETPLACE} marketplace points at another source; removing it may remove non-user plugin rows`, argv: [], blocked: true };
+    const blockers = plugins.filter(plugin => plugin.id === PLUGIN && plugin.scope !== "user");
+    if (blockers.length) {
+      const display = (value: unknown) => JSON.stringify(safeDisplayValue(value) ?? "unknown");
+      const rows = blockers.map(plugin => `scope=${display(plugin.scope)}, projectPath=${display(plugin.projectPath)}, version=${display(plugin.version)}, installPath=${display(plugin.installPath)}`).join("; ");
+      const homeProject = blockers.some(plugin => safeDisplayValue(plugin.projectPath) !== undefined && real(plugin.projectPath!) === real(personHome));
+      const danger = homeProject ? ` Do not run 'claude plugin uninstall --scope project' from $HOME (${display(personHome)}): its project settings file ~/.claude/settings.json (${display(join(personHome, ".claude/settings.json"))}) is also the default home's user settings.` : "";
+      return { why: `the ${MARKETPLACE} marketplace points at another source; removing it may remove non-user plugin rows. Blocking rows: ${rows}. Hub-launched Claude sessions load their plugin from ~/.agenthub/releases (${display(join(personHome, ".agenthub/releases"))}), not from these plugin-cache rows. Standalone Claude sessions may still use them.${danger} Next: back up the selected Claude home's plugins/installed_plugins.json, review every listed row, and manually remove only rows confirmed stale and unused, preserving every other row; then rerun ahub setup. Setup never removes these rows automatically`, argv: [], blocked: true };
+    }
     return { why: `the ${MARKETPLACE} marketplace points at ${market.path ?? "another source"}, not at this package`, argv: ["claude", "plugin", "marketplace", "remove", MARKETPLACE] };
   }
-  if (!market) return { why: "register this package as a Claude Code plugin marketplace", argv: ["claude", "plugin", "marketplace", "add", root] };
+  if (!market) return { why: "register this package as a Claude Code plugin marketplace", argv: ["claude", "plugin", "marketplace", "add", stablePackageRoot(root)] };
   const state = pluginState(plugins, root);
   if (state.state === "missing") return { why: "install the user-scope channel plugin", argv: ["claude", "plugin", "install", PLUGIN, "--scope", "user"] };
   // Uninstall rather than update: with an unchanged version number an update has nothing to do.

package/src/broker/protocol.ts

@@ -8,6 +8,8 @@ import {
   type OwnerPin, type VerifiedPublicRoster,
 } from "../rooms/wire.ts";
 
+/** Optional codec header token; the existing ephemeral opt-in remains byte-for-byte unchanged. */
+export const BROKER_CODEC_FEATURES_OPT_IN = "1";
 export const BROKER_CONTROL_LIMITS = Object.freeze({ control: 1_048_576, challenge: 8192, nonceBytes: 32 });
 export type BrokerProtocolCode = "invalid_wire" | "limit" | "untrusted" | "expired" | "authentication_failed";
 export class BrokerProtocolError extends Error {
@@ -35,6 +37,9 @@ export interface BrokerAuth {
   roster: string | null;
   signature: string;
 }
+/** Broker-to-client transport evidence; never accepted as client control or authority. */
+export interface BrokerCodecPeer { member: string; session: string | null; supported: boolean }
+export interface BrokerCodecPeers { v: 1; type: "codec_peers"; digest: string; peers: BrokerCodecPeer[] }
 export interface BrokerRosterReady { v: 1; type: "roster_ready"; digest: string }
 export interface BrokerReceived { v: 1; type: "received"; digest: string }
 export type BrokerControl = BrokerAuth | BrokerRosterReady | BrokerReceived;

package/src/broker/server.ts

@@ -2,7 +2,7 @@
 import type { ServerWebSocket } from "bun";
 import { assertRoomCryptoReady, decodeBase64url, encodeBase64url, randomBytes } from "../rooms/crypto.ts";
 import { brokerUrl, canonicalBytes, decodeFrame, decodeRoster, publicRosterWire, verifyPublicFrame, verifyPublicRoster, type VerifiedPublicRoster } from "../rooms/wire.ts";
-import { BROKER_CONTROL_LIMITS, decodeBrokerControl, encodeBrokerChallenge, verifyBrokerAuth, type BrokerChallenge } from "./protocol.ts";
+import { BROKER_CODEC_FEATURES_OPT_IN, BROKER_CONTROL_LIMITS, decodeBrokerControl, encodeBrokerChallenge, verifyBrokerAuth, type BrokerChallenge } from "./protocol.ts";
 import { BrokerStore, BrokerStoreError, type BrokerLimits } from "./store.ts";
 
 export const BROKER_SOCKET_LIMITS = Object.freeze({ connections: 128, verifications: 16, authMs: 10_000, rosterAckMs: 30_000, backpressureBytes: 1_048_576, queuedMessages: 8, queuedBytes: 2_097_152, globalQueuedBytes: 33_554_432 });
@@ -26,6 +26,10 @@ interface Client {
   ws?: ServerWebSocket<Client>;
   room: string;
   ephemeral: boolean;
+  codecFeatures: boolean;
+  codecSession: string;
+  pendingCodecMembers: Set<string>;
+  codecFlushQueued: boolean;
   challenge: BrokerChallenge;
   phase: "challenge" | "authenticating" | "roster" | "ready" | "closed";
   busy: boolean;
@@ -108,11 +112,13 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
   function close(client: Client, code: string): void {
     if (client.phase === "closed") return;
     client.phase = "closed";
+    client.pendingCodecMembers.clear(); client.codecFlushQueued = false;
     client.inFlight = undefined; client.inFlightEphemeral = undefined; client.inFlightExpiresAt = undefined; client.inFlightEpoch = undefined;
     queuedBytes -= client.inboxBytes; client.inboxBytes = 0; client.inbox.length = 0;
     if (client.member && members.get(memberKey(client)) === client) {
       members.delete(memberKey(client));
       try { store.disconnect(client.room, client.member); } catch { emit("refused", client, "state_unavailable"); }
+      notifyCodecPeers(client.room, client.member);
     }
     if (client.ws) { try { client.ws.close(4403, code); } catch { /* already closed */ } }
     else clients.delete(client);
@@ -137,15 +143,55 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     if (!roster || !member || identityKey(member) !== client.key) throw new BrokerServerError("untrusted");
     return roster;
   }
+  /** Connection evidence only: the sender must still echo its session in signed presence. */
+  function sendCodecPeers(recipient: Client, memberIds: readonly string[]): void {
+    if (!recipient.codecFeatures || recipient.phase !== "ready") return;
+    try {
+      const roster = active(recipient);
+      const peers = memberIds.filter(member => member !== recipient.member && roster.members.some(row => row.fingerprint === member)).map(member => {
+        const source = members.get(`${recipient.room}|${member}`);
+        const current = source?.phase === "ready" && active(source).digest === roster.digest ? source : undefined;
+        return { member, session: current?.codecSession ?? null, supported: current?.codecFeatures === true };
+      });
+      if (peers.length) control(recipient, { v: 1, type: "codec_peers", digest: roster.digest, peers });
+    } catch { close(recipient, "state_changed"); }
+  }
+  function flushCodecPeers(client: Client): void {
+    const pending = [...client.pendingCodecMembers]; client.pendingCodecMembers.clear();
+    if (pending.length) sendCodecPeers(client, pending);
+  }
+  function notifyCodecPeers(room: string, member: string): void {
+    for (const recipient of clients) if (recipient.room === room && recipient.codecFeatures && recipient.phase === "ready") {
+      try {
+        const current = new Set(active(recipient).members.map(row => row.fingerprint));
+        // At most the signed roster's members can wait; churn replaces evidence
+        // rather than growing a control queue beyond the existing packet ceiling.
+        for (const pending of recipient.pendingCodecMembers) if (!current.has(pending)) recipient.pendingCodecMembers.delete(pending);
+        if (member === recipient.member || !current.has(member)) continue;
+        recipient.pendingCodecMembers.add(member);
+        if (!recipient.codecFlushQueued) {
+          recipient.codecFlushQueued = true;
+          queueMicrotask(() => { recipient.codecFlushQueued = false; flushCodecPeers(recipient); });
+        }
+      } catch { close(recipient, "state_changed"); }
+    }
+  }
+  function codecInventory(client: Client): void {
+    if (!client.codecFeatures || client.phase !== "ready") return;
+    client.pendingCodecMembers.clear();
+    sendCodecPeers(client, active(client).members.map(member => member.fingerprint));
+  }
   function sendRoster(client: Client): void {
     const roster = active(client);
     client.phase = "roster"; client.rosterDigest = roster.digest;
     client.rosterDeadline = now() + BROKER_SOCKET_LIMITS.rosterAckMs;
     // Legacy hubs have a closed ready grammar; advertise only after HTTP opt-in.
-    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest, ...(client.ephemeral ? { ephemeral: true } : {}) });
+    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest, ...(client.ephemeral ? { ephemeral: true } : {}), ...(client.codecFeatures ? { codecFeatures: true, codecSession: client.codecSession } : {}) });
   }
   function pump(client: Client): void {
     if (stopping || client.phase === "closed" || !client.member) return;
+    flushCodecPeers(client); // Source-session invalidation always precedes ciphertext handoff.
+    if (members.get(memberKey(client)) !== client) return;
     const roster = active(client);
     const next = store.next(client.room, client.member);
     if (client.inFlightEphemeral && client.inFlightEpoch !== roster.epoch) {
@@ -192,6 +238,7 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     if (previous && previous !== client) close(previous, "replaced");
     members.set(memberKey(client), client);
     client.phase = "roster";
+    notifyCodecPeers(client.room, client.member);
     sendRoster(client);
     emit("connected", client);
   }
@@ -218,7 +265,7 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
       const proof = await (ports.verifyFrame ?? verifyPublicFrame)({ wire: bytes, roster: selected });
       const onlineRecipients = proof.recipients.filter(recipient => {
         const target = members.get(`${client.room}|${recipient}`);
-        return target?.phase === "ready" && (!proof.ephemeral || target.ephemeral);
+        return target?.phase === "ready" && (!proof.ephemeral || target.ephemeral) && (!proof.codecFeatures || target.codecFeatures);
       });
       try {
         active(client);
@@ -241,6 +288,8 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
       const latest = active(client);
       if (packet.digest !== client.rosterDigest || packet.digest !== latest.digest) { sendRoster(client); return; }
       client.phase = "ready"; client.rosterDeadline = undefined;
+      codecInventory(client);
+      if (client.member) notifyCodecPeers(client.room, client.member);
       safePump(client); return;
     }
     if (packet.digest !== client.inFlight) { refused(client, "unexpected_ack", false); return; }
@@ -290,7 +339,8 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
           const room = roomId(url.pathname.slice("/v1/rooms/".length));
           if (clients.size >= BROKER_SOCKET_LIMITS.connections) return new Response("busy", { status: 503 });
           const current = store.current(room)?.current;
-          const client: Client = { room, ephemeral: req.headers.get("x-agent-hub-ephemeral") === "1", challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
+          const transportOptIn = req.headers.get("x-agent-hub-ephemeral");
+          const client: Client = { room, ephemeral: transportOptIn === "1", codecFeatures: transportOptIn === "1" && req.headers.get("x-agent-hub-codecs") === BROKER_CODEC_FEATURES_OPT_IN, codecSession: encodeBase64url(randomBytes(32)), pendingCodecMembers: new Set(), codecFlushQueued: false, challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
           clients.add(client);
           if (host.upgrade(req, { data: client })) return;
           clients.delete(client); return new Response("websocket required", { status: 400 });

package/src/broker/store.ts

@@ -408,7 +408,9 @@ export class BrokerStore {
         // ponytail: while A awaits C, A's broadcast reply to B may replace C's request;
         // C waits for A's next state change/reconnect. Task #736 idle refresh or
         // per-(sender,recipient) coalescing closes this latest-per-sender ceiling.
-        this.removeEphemeral(proof.room, proof.sender);
+        // Codec advertisements must not evict a legacy snapshot that a mixed
+        // member has not received yet. Both groups share the existing queue caps.
+        this.removeEphemeral(proof.room, proof.sender, undefined, proof.codecFeatures === true);
         const connected = new Set(onlineRecipients);
         recipients = recipients.filter(recipient => connected.has(recipient));
       }
@@ -438,12 +440,13 @@ export class BrokerStore {
     this.transaction(() => { this.removeEphemeral(room, undefined, recipient); });
   }
 
-  private removeEphemeral(room?: string, sender?: string, recipient?: string): void {
+  private removeEphemeral(room?: string, sender?: string, recipient?: string, codecFeatures?: boolean): void {
     const rows = this.db.query<{ rowid: number; wire: Uint8Array; recipients: string }, [string | null, string | null, string | null, string | null]>(
       "SELECT rowid,wire,recipients FROM queued_frames WHERE (? IS NULL OR room=?) AND (? IS NULL OR sender=?)",
     ).all(room ?? null, room ?? null, sender ?? null, sender ?? null);
     for (const row of rows) {
-      if (!decodeFrame(row.wire).ephemeral) continue;
+      const frame = decodeFrame(row.wire);
+      if (!frame.ephemeral || codecFeatures !== undefined && (frame.codecFeatures === true) !== codecFeatures) continue;
       const remaining = recipient === undefined ? [] : parseRecipients(row.recipients).filter(id => id !== recipient);
       if (remaining.length) this.db.query("UPDATE queued_frames SET recipients=? WHERE rowid=?").run(JSON.stringify(remaining), row.rowid);
       else this.db.query("DELETE FROM queued_frames WHERE rowid=?").run(row.rowid);

package/src/cli/autonomy-homes.ts

@@ -22,12 +22,21 @@ export async function usedClaudeHomes(registry: Registry, home: string, env: Nod
   return { ...found, complete: found.complete && !notices.length, notices: [...notices, ...found.notices] };
 }
 export async function autonomyHomeStatus(registry: Registry, home: string, env: NodeJS.ProcessEnv, packageRoot: string, probe: ClaudeHomeProbe) {
-  const found = await usedClaudeHomes(registry, home, env), deadline = performance.now() + 6000;
+  const found = await usedClaudeHomes(registry, home, env);
+  // Doctor also inspects the existing default home; setup's selected write inventory stays unchanged.
+  const defaults = await discoverClaudeHomes({ home, env: { ...env, CLAUDE_CONFIG_DIR: undefined } });
+  // Discovery canonicalizes existing homes through realPath, so lexical aliases share one inspection.
+  const inspected = new Map(found.homes.map(selected => [selected.path, selected]));
+  for (const selected of defaults.homes.filter(selected => selected.exists)) {
+    const previous = inspected.get(selected.path);
+    inspected.set(selected.path, previous ? { ...previous, sources: [...new Set([...previous.sources, ...selected.sources])] } : selected);
+  }
+  const notices = [...new Set([...found.notices, ...defaults.notices])], deadline = performance.now() + 6000;
   const homes = [];
-  for (const selected of found.homes) {
+  for (const selected of inspected.values()) {
     const remaining = Math.floor(deadline - performance.now());
     if (remaining < 1) homes.push({ home: selected, plugin: { state: "unknown", reason: "The machine profile inventory time bound was reached." }, hook: checkClaudeProfileHook(selected) });
     else homes.push(await checkClaudeHome(selected, packageRoot, env, probe, Math.min(remaining, 6000)));
   }
-  return { homes, notices: found.notices, complete: found.complete && performance.now() <= deadline };
+  return { homes, notices, complete: found.complete && defaults.complete && performance.now() <= deadline };
 }

package/src/cli/claude-homes.ts

@@ -3,7 +3,7 @@ import { isAbsolute, join } from "node:path";
 import { realPath } from "../hub/project.ts";
 import { launcherOf, recordPath, MAX_COMMAND_MS, type ProcessIdentity } from "./terminal-recovery.ts";
 import { CLAUDE_PLUGIN_INVENTORY, PLUGIN, nextStep, pluginState, type InstalledPlugin, type Marketplace, type PluginState, type SetupStep } from "./setup.ts";
-import { checkClaudeProfileHook, type ClaudeProfileHookCheck } from "./claude-profile-hook.ts";
+import { checkClaudeProfileHook, type ClaudeProfileHookCheck, type ClaudeProfileHookOptions } from "./claude-profile-hook.ts";
 
 export type ClaudeHomeSource = "environment" | "default" | "recorded-launch";
 export interface ClaudeHome { path: string; exists: boolean; sources: ClaudeHomeSource[] }
@@ -93,12 +93,12 @@ export interface ClaudeHomeCheck {
 }
 
 /** Read-only per-home plugin inspection. Installation never proves that a live permission hook is present. */
-export async function checkClaudeHome(home: ClaudeHome, packageRoot: string, env: NodeJS.ProcessEnv, probe: ClaudeHomeProbe, timeoutMs = MAX_COMMAND_MS, probeMissingDefault = false): Promise<ClaudeHomeCheck> {
+export async function checkClaudeHome(home: ClaudeHome, packageRoot: string, env: NodeJS.ProcessEnv, probe: ClaudeHomeProbe, timeoutMs = MAX_COMMAND_MS, probeMissingDefault = false, hookOptions?: ClaudeProfileHookOptions): Promise<ClaudeHomeCheck> {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_COMMAND_MS) throw new Error("invalid Claude plugin probe time bound");
-  const hook = checkClaudeProfileHook(home);
+  const hook = checkClaudeProfileHook(home, hookOptions);
   const unknown = (): ClaudeHomeCheck => ({ home, plugin: { state: "unknown", reason: "Claude plugin inventory is unavailable or invalid for this home." }, hook });
   if (hook.state === "refused") return unknown();
-  if (!home.exists && !(probeMissingDefault && home.sources.includes("default"))) return { home, plugin: { state: "missing" }, next: nextStep([], [], packageRoot), hook };
+  if (!home.exists && !(probeMissingDefault && home.sources.includes("default"))) return { home, plugin: { state: "missing" }, next: nextStep([], [], packageRoot, validPath(env.HOME) ? env.HOME : undefined), hook };
   const scoped = claudeHomeEnvironment(home, env), deadline = performance.now() + timeoutMs;
   const read = async (argv: readonly string[]): Promise<unknown[] | undefined> => {
     const remaining = Math.floor(deadline - performance.now());
@@ -118,6 +118,6 @@ export async function checkClaudeHome(home: ClaudeHome, packageRoot: string, env
       (row.version === undefined || typeof row.version === "string" && row.version.length <= 64 && (row.id !== PLUGIN ? !/[\u0000-\u001f\u007f-\u009f]/.test(row.version) : /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(row.version))) &&
       (row.installPath === undefined || validPath(row.installPath))) ||
       !marketplaces.every(row => object(row) && typeof row.name === "string" && row.name.length <= 256 && (row.path === undefined || validPath(row.path)))) return unknown();
-    return { home, plugin: pluginState(plugins as InstalledPlugin[], packageRoot), next: nextStep(plugins as InstalledPlugin[], marketplaces as Marketplace[], packageRoot), hook };
+    return { home, plugin: pluginState(plugins as InstalledPlugin[], packageRoot), next: nextStep(plugins as InstalledPlugin[], marketplaces as Marketplace[], packageRoot, validPath(env.HOME) ? env.HOME : undefined), hook };
   } catch { return unknown(); }
 }

package/src/cli/claude-profile-hook.ts

@@ -1,9 +1,9 @@
-import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, writeFileSync, type Stats } from "node:fs";
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, statSync, writeFileSync, type Stats } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { dirname, isAbsolute, join } from "node:path";
-import { canonicalJson } from "../hub/packs.ts";
 import { factsHook } from "./facts-hook.ts";
 import { shellQuote } from "./shell-quote.ts";
+import { stableBunRuntime, stablePackageRoot } from "./install-paths.ts";
 import type { ClaudeHome } from "./claude-homes.ts";
 
 export interface ClaudeProfileHookOptions { script?: string; runtime?: string }
@@ -25,11 +25,29 @@ interface HookPlan {
 }
 
 function hookEntry(options: ClaudeProfileHookOptions): Record<string, unknown> {
-  const script = options.script ?? join(import.meta.dir, "claude-profile-hook.ts"), runtime = options.runtime ?? process.execPath;
+  const script = options.script ?? join(stablePackageRoot(join(import.meta.dir, "../..")), "src/cli/claude-profile-hook.ts"), runtime = options.runtime ?? stableBunRuntime();
   if (!validPath(script) || !validPath(runtime)) throw new Error("invalid profile hook command");
   return { matcher: "*", hooks: [{ type: "command", command: `${shellQuote(runtime)} ${shellQuote(script)} --run`, timeout: 5 }] };
 }
 
+interface ManagedProfileHook { entry: Record<string, unknown>; hook: Record<string, unknown>; runtime: string; script: string }
+/** Own only the generated command grammar; matcher, timeout and caller metadata remain theirs. */
+function managedProfileHook(candidate: unknown): ManagedProfileHook | undefined {
+  if (!object(candidate) || !Array.isArray(candidate.hooks) || candidate.hooks.length !== 1) return;
+  const hook = candidate.hooks[0];
+  if (!object(hook) || hook.type !== "command" || typeof hook.command !== "string") return;
+  const match = /^'((?:[^']|'\\'')*)' '((?:[^']|'\\'')*)' --run$/.exec(hook.command);
+  if (!match) return;
+  const runtime = match[1]!.replace(/'\\''/g, "'"), script = match[2]!.replace(/'\\''/g, "'");
+  if (!validPath(runtime) || !validPath(script) || !script.endsWith("/src/cli/claude-profile-hook.ts")
+    || hook.command !== `${shellQuote(runtime)} ${shellQuote(script)} --run`) return;
+  return { entry: candidate, hook, runtime, script };
+}
+
+function hookPathPresent(file: string): boolean {
+  try { return statSync(file).isFile(); } catch { return false; }
+}
+
 function settingsSource(file: string): { value: Record<string, unknown>; source?: HookPlan["source"] } {
   let fd: number | undefined;
   try {
@@ -67,13 +85,24 @@ function planClaudeProfileHook(home: ClaudeHome, options: ClaudeProfileHookOptio
     if (value.hooks !== undefined && !object(value.hooks)) return refuse("Claude's hook configuration is malformed.");
     const hooks = value.hooks ?? {}, existing = hooks.PreToolUse ?? [];
     if (!Array.isArray(existing)) return refuse("Claude's PreToolUse hook list is malformed.");
-    const entry = hookEntry(options), expected = canonicalJson(entry);
-    const matches = existing.filter(candidate => canonicalJson(candidate) === expected).length;
-    const next = matches === 1 ? undefined : `${JSON.stringify({ ...value, hooks: { ...hooks, PreToolUse: [...existing.filter(candidate => canonicalJson(candidate) !== expected), entry] } }, null, 2)}\n`;
+    const entry = hookEntry(options), expectedCommand = (entry.hooks as { command: string }[])[0]!.command;
+    const managed = existing.map(managedProfileHook), first = managed.find(candidate => candidate !== undefined);
+    const count = managed.filter(candidate => candidate !== undefined).length;
+    const stale = managed.some(candidate => candidate && (!hookPathPresent(candidate.runtime) || !hookPathPresent(candidate.script)));
+    const configured = count === 1 && first?.hook.command === expectedCommand && !stale;
+    const normalized = existing.flatMap((candidate, index) => {
+      const owned = managed[index];
+      if (!owned) return [candidate];
+      return owned === first ? [{ ...owned.entry, hooks: [{ ...owned.hook, command: expectedCommand }] }] : [];
+    });
+    if (!first) normalized.push(entry);
+    const next = configured ? undefined : `${JSON.stringify({ ...value, hooks: { ...hooks, PreToolUse: normalized } }, null, 2)}\n`;
     if (next !== undefined && Buffer.byteLength(next, "utf8") > MAX_SETTINGS_BYTES) return refuse("Claude's settings would exceed the bounded profile settings size.");
-    return { file, home: directory, parent, source, next, check: matches === 1
-      ? { state: "installed", reason: "The project-neutral profile hook is configured; this does not prove live permission enforcement." }
-      : { state: "missing", reason: matches ? "Duplicate managed profile hooks need normalization." : "The project-neutral profile hook is not configured." } };
+    let reason = "The project-neutral profile hook is not configured for this install; run ahub setup.";
+    if (count > 1) reason = "Duplicate managed profile hooks need normalization; run ahub setup.";
+    if (stale) reason = "A managed profile hook script or runtime is missing; run ahub setup to refresh the selected home's hook.";
+    if (configured) reason = "The project-neutral profile hook is configured; this does not prove live permission enforcement.";
+    return { file, home: directory, parent, source, next, check: { state: configured ? "installed" : "missing", reason } };
   } catch { return refuse("Claude profile settings could not be safely inspected; no settings were changed."); }
 }
 

package/src/cli/install-paths.ts

@@ -0,0 +1,71 @@
+import { lstatSync, readlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { realPath } from "../hub/project.ts";
+
+export interface InstallPathOptions {
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  globalFlag?: "-g" | "--global";
+}
+// Contract: #1245 limits lexical symlink inspection to eight hops; unknown paths use the resolved fallback.
+const MAX_LINK_HOPS = 8;
+const samePath = (left: string, right: string): boolean => {
+  try { return realPath(left) === realPath(right); } catch { return false; }
+};
+
+/** Follow only the leaf links, preserving lexical parent aliases such as current/. */
+function lexicalTarget(entry: string): string | undefined {
+  let link = resolve(entry);
+  const seen = new Set<string>();
+  try {
+    for (let hops = 0; hops <= MAX_LINK_HOPS; hops++) {
+      if (seen.has(link)) return;
+      seen.add(link);
+      if (!lstatSync(link).isSymbolicLink()) return link;
+      if (hops === MAX_LINK_HOPS) return;
+      link = resolve(dirname(link), readlinkSync(link));
+    }
+  } catch { /* Missing, unreadable and cyclic aliases are not evidence of this install. */ }
+}
+
+/** The PATH entry's canonical target must also be a CLI entry, not just a lookalike parent. */
+function pathPackageRoot(invocation: string): string | undefined {
+  const target = lexicalTarget(invocation);
+  if (!target?.endsWith(`${sep}src${sep}cli${sep}main.js`)) return;
+  try {
+    const canonical = realPath(invocation);
+    if (!canonical.endsWith(`${sep}src${sep}cli${sep}main.js`)) return;
+    const candidate = dirname(dirname(dirname(target)));
+    return samePath(candidate, dirname(dirname(dirname(canonical)))) ? candidate : undefined;
+  } catch { return; }
+}
+
+/** Bun resolves argv[1], Bun.main and import.meta.dir, through both bun <link> and a shebang (native probe, #1245). */
+export function stablePackageRoot(root: string, options: { invocation?: string } = {}): string {
+  const invocation = options.invocation ?? Bun.which("ahub", { PATH: process.env.PATH });
+  const candidate = invocation ? pathPackageRoot(invocation) : undefined;
+  return candidate && samePath(candidate, root) ? candidate : root;
+}
+
+export function stableBunRuntime(options: { runtime?: string; pathRuntime?: string } = {}): string {
+  const runtime = options.runtime ?? process.execPath, candidate = options.pathRuntime ?? Bun.which("bun", { PATH: process.env.PATH });
+  return candidate && lexicalTarget(candidate) && samePath(candidate, runtime) ? candidate : runtime;
+}
+
+/** Advice only; a staged daemon upgrade does not update the person's global CLI installation. */
+export function globalCliUpdateStep(version?: string, options: InstallPathOptions = {}): string {
+  const env = options.env ?? process.env;
+  const invocation = Bun.which("ahub", { PATH: env.PATH ?? "" });
+  const root = invocation ? pathPackageRoot(invocation) : undefined;
+  const generic = `update the global CLI${version ? ` to ${version}` : ""} the way it was installed`;
+  if (!root) return generic;
+  const global = join(env.BUN_INSTALL || join(options.home ?? homedir(), ".bun"), "install/global/node_modules");
+  let bunGlobal = false;
+  try {
+    const within = relative(realPath(global), realPath(root));
+    bunGlobal = within !== "" && within !== ".." && !within.startsWith(`..${sep}`) && !isAbsolute(within);
+  } catch { /* An unproven Bun prefix must not suggest updating a different CLI. */ }
+  if (bunGlobal) return `run \`bun add ${options.globalFlag ?? "-g"} @staix/agent-hub${version ? `@${version}` : ""}\``;
+  return `${generic} (running from ${root})`;
+}

package/src/cli/main.ts

@@ -43,6 +43,7 @@ import { readAutonomyDefaults, writeAutonomyDefaults } from "../hub/autonomy-def
 import { inheritMachineAutonomy, prepareAutonomyProject, runAllProjectAutonomy, type PreparedAutonomyProject } from "./autonomy-projects.ts";
 import { offlineAutonomyStatus } from "./autonomy-offline.ts";
 import { autonomyHomeStatus, usedClaudeHomes } from "./autonomy-homes.ts";
+import { shellQuote } from "./shell-quote.ts";
 import { discoverClaudeHomes } from "./claude-homes.ts";
 import { setupClaudeHomes } from "./setup-homes.ts";
 import { registerAconPlugin } from "./acon-register.ts";
@@ -89,7 +90,7 @@ import { createInterface as lineReader } from "node:readline";
 import { activeOperation, assertLifecycleAvailable, operationIdPattern, readOperation, writeOperation, recoveryLock, recoveryRunner, signedRunner, stopSignedRunner, supportsAction } from "../hub/recovery-store.ts";
 import { childEnv, personEnv } from "../hub/child-process.ts";
 import { abortRecovery, createOperation, disposeRecovery, recordRecoveryDelegation, repairedFreshSession, reattachRecovery, liveProjects, nextChoices, nextActionsText, publicOperation, recoveryCommand, registeredProjects, runRecovery, type RecoveryOperation, type Inspection } from "./upgrade.ts";
-import { endPlannedPeer, makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.ts";
+import { endPlannedPeer, makeRecoveryDriver, makeUpgradePlan, preserveSource, reattachPlannedTerminals } from "./upgrade-runtime.ts";
 import { exactVersion, latestRelease, newerVersion } from "./recovery-package.ts";
 import { globalUpdateAdvice, runtimeVersionWarnings } from "./runtime-version-warning.ts";
 import { operationScreen, planScreen, type ScreenIO, type UpgradeHost } from "./upgrade-interactive.ts";
@@ -722,6 +723,7 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
     endInspection: recoveryEndInspection,
     afterCompleted: (op) => globalUpdateLines(op.plan.version),
     endPeer: (planned, peer) => endPlannedPeer(planned, peer),
+    reattachTerminals: (planned, terminals) => reattachPlannedTerminals(planned, terminals),
     runnerStoppable: (id) => signedRunner(id) !== undefined,
     stopRunner: (id) => stopSignedRunner(id),
     entry: join(import.meta.dir, "main.js"),
@@ -2931,6 +2933,23 @@ const commands: Record<string, () => Promise<void> | void> = {
       }
       const plugin = pluginState(parseList<InstalledPlugin>(spawnSync(DOCTOR_PLUGIN_PROBE.command, [...DOCTOR_PLUGIN_PROBE.argv], { encoding: "utf8" }).stdout ?? ""), join(import.meta.dir, "..", ".."));
       row(plugin.state === "current", DOCTOR_PLUGIN_PROBE.name, plugin.state === "missing" ? "missing: run ahub setup" : plugin.state === "current" ? `agent-hub@agent-hub ${plugin.version}` : `agent-hub@agent-hub is stale (${plugin.why}): run ahub setup`);
+      let profileRegistry: Registry | undefined;
+      try {
+        profileRegistry = new Registry();
+        const profiles = await autonomyHomeStatus(profileRegistry, homedir(), process.env, join(import.meta.dir, "..", ".."), (argv, options) => {
+          const result = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", env: options.env, timeout: options.timeoutMs, maxBuffer: 1024 * 1024 });
+          return { status: result.status ?? -1, stdout: result.stdout ?? "" };
+        });
+        for (const profile of profiles.homes) {
+          const installed = profile.hook.state === "installed";
+          checks.push({ name: `Claude profile hook: ${profile.home.path}`, section: "Hub", level: installed ? "ok" : "warn",
+            detail: installed ? profile.hook.reason : `${profile.hook.reason} Run CLAUDE_CONFIG_DIR=${shellQuote(profile.home.path)} ahub setup.` });
+        }
+        if (!profiles.complete) checks.push({ name: "Claude profile discovery", section: "Hub", level: "unknown",
+          detail: profiles.notices.join("; ") || "Claude profile discovery is incomplete; inspect the registered projects and selected homes before setup." });
+      } catch {
+        checks.push({ name: "Claude profile discovery", section: "Hub", level: "unknown", detail: "Claude profile inventory is unavailable; inspect the machine registry and selected homes before setup." });
+      } finally { profileRegistry?.close(); }
       if (up) checks.push(...runtimeVersionWarnings(daemonVersion, VERSION, plugin.state === "missing" ? undefined : plugin.version));
 
       const config = loadConfig(cwd);

package/src/cli/output.ts

@@ -5,7 +5,7 @@ import { boardColumns, type BoardPeerInput } from "../ui/task-board.ts";
 import { peerStyle } from "../ui/peer-palette.ts";
 import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, terminalText, initialConsoleState, stateTone, type Span, type Tone } from "./console-state.ts";
 import { taskProgress } from "../ui/task-progress.ts";
-import { backendLabel, memorySyncLine, reviewInputHealthLine } from "./status-lines.ts";
+import { backendLabel, memorySyncLine, reviewInputHealthLine, roomsUnavailableLine } from "./status-lines.ts";
 import { ownerIsolationText } from "./role-holders.ts";
 import { schedulePeriodText, scheduleWhen } from "../hub/schedules.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
@@ -14,6 +14,8 @@ import type { SpecsStatus } from "../hub/specs-task.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  roomsUnavailable?: unknown;
+  roomsOpening?: boolean;
   controlWriteTiming?: { active: number; slowRequests: number; blockedLoopSamples: number; droppedActive: number; droppedRecent: number; droppedLogs: number; droppedSpans?: number; droppedMetadata?: number; expiredRequests?: number };
   specs?: SpecsStatus & { missingBlockHint?: boolean };
   queueBackpressure?: QueueBackpressureStatus;
@@ -263,6 +265,8 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     const text = ownerIsolationText(isolated, data.ownerIsolationNotes?.[id]);
     if (text) out.push(...detail(`${id} owner isolation`, text, columns, isolated ? undefined : "attention"));
   }
+  if (data.roomsOpening === true) out.push(...lines("rooms: opening; wait for local room storage initialization", columns, "muted"));
+  if (data.roomsUnavailable !== undefined) out.push(...lines(roomsUnavailableLine(data.roomsUnavailable), columns, "failure"));
   if (data.deliveryError) out.push(...detail("delivery storage", `${data.deliveryError}; dispatch is stopped`, columns, "failure"));
   for (const [peer, count] of Object.entries(data.deliveryFailures ?? {})) {
     if (Number.isSafeInteger(count) && count > 0) out.push(...detail(`${peer} failed deliveries`, `${count}; next: ahub queue discard --peer ${peer} --state failed`, columns, "attention"));