@staix/agent-hub 0.12.39 → 0.12.40

package/src/adapters/jcode.ts

@@ -1,9 +1,10 @@
 import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { createConnection } from "node:net";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import type { Readable } from "node:stream";
-import type { PeerState } from "../hub/envelope.ts";
+import { renderDigest, type Envelope, type PeerState } from "../hub/envelope.ts";
 import { AcpPeer, type AcpOptions } from "./acp.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
@@ -11,6 +12,8 @@ export interface JcodeOptions extends Omit<AcpOptions, "cmd" | "qwen025" | "expe
   command: string[];
   home: string;
   providerProfile?: string;
+  /** How long a native steer may take to be acknowledged (#572); default 5 s. */
+  steerTimeoutMs?: number;
 }
 export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string): string[] {
   if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
@@ -57,6 +60,10 @@ function savedSession(home: string, id: string): boolean {
 }
 
 /** Set on every owned jcode process: no Claude MCP import, and no native telemetry (jcode-telemetry-core is_enabled, #529). */
+/** A TUI launch option that differs from the running owned session; carries the flag name only. */
+export class JcodeOptionMismatch extends Error {
+  constructor(readonly option: "--session-id" | "--model" | "--provider-profile") { super("Jcode launch options differ from its running session"); }
+}
 const JCODE_OWNED_ENV = { JCODE_DISABLE_CLAUDE_MCP: "1", JCODE_NO_TELEMETRY: "1" } as const;
 /** The oldest native release accepted; its ACP, serve and MCP contract was verified live on 0.98.1 (docs/verification). */
 export const JCODE_MIN_VERSION = "0.98.0";
@@ -70,6 +77,65 @@ export function jcodeVersionSupported(version: unknown): boolean {
   return !!v && compare(v, release(JCODE_MIN_VERSION)!) >= 0 && compare(v, release(JCODE_BREAKING_VERSION)!) < 0;
 }
 
+/** A native steer the server did not take, with nothing sent: the message may safely stay queued. */
+class SteerRefused extends Error {}
+/** A native steer that was sent but not acknowledged: it may have gone in, so it is never requeued as if it had not. */
+class SteerUncertain extends Error {}
+const STEER_TIMEOUT_MS = 5000;
+
+/**
+ * #572 AC1: a second client on the hub's own private server socket queues a soft interrupt into the running session
+ * (jcode injects it at the next tool boundary, or when a text-only turn ends). Established on 0.99.0 under an isolated
+ * home: ping lists `soft_interrupt_ids`, subscribe with `target_session_id` joins the same session without a new one,
+ * `state` says whether a turn runs, and the injection survives this client's disconnect. Nothing here cancels the turn.
+ * `canSend` runs immediately before the soft interrupt is written and names why the hub no longer wants it sent. What
+ * cannot be closed from here is the native side: the server's `state` reply is a snapshot, so a turn that ends and
+ * another that begins inside the server between its reply and the write still receives the message. Such a steer is
+ * acknowledged, adopted by nobody, and held for review; an upstream atomic "steer turn N" request would remove it.
+ */
+function nativeSteer(socket: string, cwd: string, sessionId: string, text: string, clientId: string, timeoutMs = STEER_TIMEOUT_MS, canSend: () => string | undefined = () => undefined): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const conn = createConnection(socket);
+    let phase: "ping" | "subscribe" | "state" | "sent" = "ping", buffer = "", finished = false;
+    const finish = (error?: Error) => {
+      if (finished) return;
+      finished = true; clearTimeout(timer); conn.destroy();
+      if (error) reject(error); else resolve();
+    };
+    const fail = (why: string) => finish(phase === "sent" ? new SteerUncertain(`Jcode steering outcome is uncertain: ${why}`) : new SteerRefused(`Jcode owned server cannot take a steer: ${why}`));
+    const timer = setTimeout(() => fail(`no answer in the ${phase} step`), timeoutMs);
+    const send = (value: Record<string, unknown>) => conn.write(`${JSON.stringify(value)}\n`);
+    conn.once("error", () => fail("connection failed"));
+    conn.once("close", () => fail("connection closed"));
+    conn.once("connect", () => send({ type: "ping", id: 1 }));
+    conn.on("data", chunk => {
+      buffer += chunk.toString();
+      if (buffer.length > 1024 * 1024) return fail("oversized reply");
+      const lines = buffer.split("\n"); buffer = lines.pop()!;
+      for (const line of lines) {
+        let msg: { type?: unknown; id?: unknown; capabilities?: unknown; session_id?: unknown; is_processing?: unknown };
+        try { msg = JSON.parse(line); } catch { continue; }
+        if (msg.type === "error" && typeof msg.id === "number" && msg.id >= 1) return fail("the server refused a request");
+        if (phase === "ping" && msg.type === "pong" && msg.id === 1) {
+          if (!Array.isArray(msg.capabilities) || !msg.capabilities.includes("soft_interrupt_ids")) return fail("no soft interrupt support");
+          phase = "subscribe"; send({ type: "subscribe", id: 2, working_dir: cwd, target_session_id: sessionId, continue_on_disconnect: true });
+        } else if (phase === "subscribe" && msg.type === "session") {
+          if (msg.session_id !== sessionId) return fail("the server answered for another session");
+          phase = "state"; send({ type: "state", id: 3 });
+        } else if (phase === "state" && msg.type === "state" && msg.id === 3) {
+          if (msg.session_id !== sessionId || msg.is_processing !== true) return fail("the session has no running turn");
+          // The last check before anything is sent (review round 2 I1): the hub's own turn, launch, session and stop state may
+          // have changed during the connect, ping, subscribe and state round trips. Past this write the server may have taken
+          // the message, so it is never refused as unsent again.
+          const changed = canSend();
+          if (changed) return fail(changed);
+          phase = "sent"; send({ type: "soft_interrupt", id: 4, content: text, urgent: false, client_id: clientId });
+        } else if (phase === "sent" && msg.type === "ack" && msg.id === 4) finish();
+      }
+    });
+  });
+}
+
 /** The wrapper contract preserves every configured prefix argument before the native probe. */
 export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
   const [bin, ...prefix] = command;
@@ -162,6 +228,44 @@ export class JcodePeer extends AcpPeer {
     }
     if (failure) throw failure;
   }
+  /**
+   * #572 AC1: an `important` message to a busy Jcode goes into its running turn through its own server (a soft
+   * interrupt), with the receipt contract of Codex's steer: `failed_safe` when nothing was sent, `needs_review` when it
+   * may have gone in, `accepted` once the server acknowledged it, and `completed` when the turn ends normally.
+   * The hub never cancels the turn to deliver.
+   */
+  async steer(envs: Envelope[], deliveryId?: string): Promise<void> {
+    const refuse = (reason: string): never => {
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason });
+      throw new Error(reason);
+    };
+    const sessionId = super.recoveryMetadata().sessionId;
+    const socket = lstatSync(this.socket, { throwIfNoEntry: false });
+    if (this.state !== "busy") refuse(`jcode is ${this.state}`);
+    if (this.ending || !this.server || this.server.exitCode !== null || this.server.signalCode !== null ||
+      !socket?.isSocket() || socket.dev !== this.socketIdentity?.dev || socket.ino !== this.socketIdentity.ino || typeof sessionId !== "string") refuse("owned Jcode server is unavailable");
+    // The turn this steer is for. The native acknowledgement is asynchronous: only this exact turn may take the message.
+    const turn = this.currentTurn(), launch = this.server!, identity = this.socketIdentity; // both proven present above
+    const stillCurrent = (): string | undefined => {
+      if (this.currentTurn() !== turn || this.state !== "busy") return `jcode's turn changed before the steer was sent (${this.state})`;
+      if (this.ending || this.server !== launch || launch.exitCode !== null || launch.signalCode !== null || this.socketIdentity !== identity) return "owned Jcode server changed before the steer was sent";
+      if (super.recoveryMetadata().sessionId !== sessionId) return "jcode's session changed before the steer was sent";
+      const now = lstatSync(this.socket, { throwIfNoEntry: false });
+      if (!now?.isSocket() || now.dev !== identity?.dev || now.ino !== identity.ino) return "owned Jcode socket changed before the steer was sent";
+      return undefined;
+    };
+    try { await nativeSteer(this.socket, this.jcode.cwd, sessionId as string, renderDigest(envs, true), deliveryId ?? crypto.randomUUID(), this.jcode.steerTimeoutMs, stillCurrent); }
+    catch (error) {
+      if (error instanceof SteerUncertain) {
+        if (deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: "steering outcome is uncertain" });
+        throw error;
+      }
+      return refuse(error instanceof Error ? error.message : "Jcode steer failed");
+    }
+    // The turn may have ended, or another begun, while the server answered: it did take the message, so it is held for review, never refused as unsent and never adopted into a different turn.
+    try { this.adoptIntoTurn(turn, envs, deliveryId); }
+    catch { if (deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: "steered turn ended before its receipt" }); throw new SteerUncertain("Jcode steering outcome is uncertain: its turn ended first"); }
+  }
   tuiLaunch(expected?: JcodeTuiBinding, options: { model?: string; providerProfile?: string; sessionId?: string } = {}): JcodeTuiState {
     const sessionId = super.recoveryMetadata().sessionId;
     const socket = lstatSync(this.socket, { throwIfNoEntry: false });
@@ -169,9 +273,11 @@ export class JcodePeer extends AcpPeer {
       !socket?.isSocket() || socket.dev !== this.socketIdentity?.dev || socket.ino !== this.socketIdentity.ino || typeof sessionId !== "string") throw new Error("owned Jcode launch is unavailable");
     const binding = { launchId: this.launchId, sessionId };
     if (expected && (expected.launchId !== binding.launchId || expected.sessionId !== binding.sessionId)) throw new Error("Jcode launch changed");
-    if ((options.sessionId !== undefined && options.sessionId !== sessionId) ||
-      (options.model !== undefined && options.model !== this.jcode.launchModel) ||
-      (options.providerProfile !== undefined && options.providerProfile !== this.jcode.providerProfile)) throw new Error("Jcode launch options differ from its running session");
+    // Names the option, never its value: the flag is the person's own and carries nothing private (#559).
+    const differs = options.sessionId !== undefined && options.sessionId !== sessionId ? "--session-id"
+      : options.model !== undefined && options.model !== this.jcode.launchModel ? "--model"
+      : options.providerProfile !== undefined && options.providerProfile !== this.jcode.providerProfile ? "--provider-profile" : undefined;
+    if (differs) throw new JcodeOptionMismatch(differs);
     if (!savedSession(this.jcode.home, sessionId)) return { state: "waiting", binding };
     const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile);
     return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, ...JCODE_OWNED_ENV } } };

package/src/adapters/local-worker.ts

@@ -4,15 +4,16 @@ import type { RouteLabelEvent, RouteTurnOutcome } from "../models/route/labels.t
 import type { StaySwitchPolicy } from "../models/route/stage.ts";
 import type { ToolObservation } from "../models/route/signals.ts";
 import { randomUUID } from "node:crypto";
-import { renderDigest, replyAudience, replyParent, STANDING_INSTRUCTION, USER, type Envelope, type EnvelopeOpts, type PeerId } from "../hub/envelope.ts";
+import { MAX_HOP, renderDigest, replyAudience, replyParent, STANDING_INSTRUCTION, USER, type Envelope, type EnvelopeOpts, type PeerId } from "../hub/envelope.ts";
 import { CONDUCTOR_TOOL_NAMES, CONDUCTOR_TOOLS, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.ts";
 import { BasePeer } from "../hub/peers.ts";
+import type { PublishResult } from "../hub/bus.ts";
 import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
 import { runTool, toolResultFailed, TOOL_SCHEMAS, touchedPaths, ApprovalWaitStop, type ToolApproval, type ApprovalProvenance, type ToolContext } from "../local/tools.ts";
 import type { Capture } from "../memory/capture.ts";
 import type { ChatMessage, ChatResult, OmniRoute, ToolCall } from "../omniroute/client.ts";
 import { safeModelLabel } from "../omniroute/usage.ts";
-import type { Sidecar } from "../switchyard/sidecar.ts";
+import { effectiveLocalRoute } from "../hub/routing.ts";
 import type { ExecutionBudgetDecision } from "../hub/execution-budget.ts";
 
 export interface LocalOptions {
@@ -21,11 +22,9 @@ export interface LocalOptions {
   sdlcCriteria?: boolean;
   cwd: string;
   omni: OmniRoute;
-  /** Absent = always the fixed model on OmniRoute. */
-  sidecar?: Sidecar;
-  /** Switchyard route id asked of the sidecar. */
+  /** In-process hub route id; legacy routes use the fixed model. */
   route?: string;
-  /** Model id sent straight to OmniRoute when the sidecar is absent, unhealthy or fails a call. */
+  /** Model alias sent straight to OmniRoute when no hub route is active or its call fails. */
   fixedModel: string;
   hubRoutes?: () => Record<string, HubRoute>;
   /** routing.toml `stay_switch` for hub stage routes (#197). */
@@ -81,6 +80,7 @@ export class LocalPeer extends BasePeer {
   private readonly history: ChatMessage[] = [];
   private readonly sessionId = `agent-hub-local-${randomUUID()}`;
   private readonly routes: HubRouteRuntime;
+  private readonly warnedLegacyRoutes = new Set<string>();
   private routeEnvs: Envelope[] = [];
   private routePii = false;
   private routeTask?: number;
@@ -237,10 +237,8 @@ export class LocalPeer extends BasePeer {
     const turnSignal = this.abort!.signal;
     // claude-mem's observer is a cloud model: nothing of a PII turn is captured.
     const capture = policy?.pii ? undefined : this.opts.capture;
-    // Positive confirmation, and for the path this turn will really take: a sidecar generated against the off-campus URL
-    // keeps sending there even after the client has found the campus gateway again.
-    const viaOffCampus = !(policy?.route ?? this.opts.route)?.startsWith("hub/") && !!this.opts.sidecar?.upstream && this.opts.omni.isAccessHost(this.opts.sidecar.upstream);
-    if (policy?.pii && (viaOffCampus || !(await this.opts.omni.onCampus()))) {
+    // Unknown gateway state is never permission to send PII.
+    if (policy?.pii && !(await this.opts.omni.onCampus())) {
       return "Refused: this is a PII task and the only reachable gateway is off campus (Cloudflare Access). Connect the VPN and assign it again.";
     }
     this.routeEnvs = envs;
@@ -328,8 +326,9 @@ export class LocalPeer extends BasePeer {
       sandboxEnv: { ...proxyEnv(this.opts.tools.bashNetwork ?? false), AGENTHUB_PEER_ID: this.id },
       signal: turnSignal,
       send: (text, to) => {
-        const refused = this.onMessage?.(text, pii ? reply : { inReplyTo: replyParent(envs), to: to?.length ? to : replyAudience(envs) });
-        if (typeof refused === "string") return `not sent: ${refused}`;
+        const result = this.onMessage?.(text, pii ? reply : { inReplyTo: replyParent(envs), to: to?.length ? to : replyAudience(envs) }) as PublishResult | string | undefined;
+        if (typeof result === "string") return `not sent: ${result}`;
+        if (result?.dropped === "hop") return `not delivered: reply chain reached the hop cap (${MAX_HOP}); send a new message without reply_to`;
         return pii ? "sent to the console user only (PII task)" : "sent";
       },
     };
@@ -372,11 +371,14 @@ export class LocalPeer extends BasePeer {
     for (const tool_call_id of missing) msgs.push({ role: "tool", tool_call_id, content: result });
   }
 
-  /** L2 when the sidecar is up, otherwise (or when a call through it fails) the fixed model on L3. */
+  /** Hub-owned in-process policy, with a fixed OmniRoute alias as fallback. */
   private async call(turnMsgs: ChatMessage[], policy: { route?: string; fixedModel?: string; pii?: boolean; task?: string } | undefined, envs: Envelope[]): Promise<ChatResult> {
-    const { omni, sidecar } = this.opts;
-    // A task turn asks for its class's route; a route needs the sidecar, which exists only when the worker was started with one.
-    const route = policy?.route ?? this.opts.route;
+    const { omni } = this.opts;
+    const route = effectiveLocalRoute(this.opts.route, policy?.route, policy?.fixedModel);
+    if (route && !route.startsWith("hub/") && !this.warnedLegacyRoutes.has(route)) {
+      this.warnedLegacyRoutes.add(route);
+      this.opts.log?.(`legacy route ${route} is deprecated and ignored; using fixed model`);
+    }
     const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
     const task = policy?.task === undefined ? undefined : Number(policy.task);
     const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
@@ -384,19 +386,6 @@ export class LocalPeer extends BasePeer {
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
     const routed = await this.hubCall(route, messages, policy, signal);
     if (routed) return routed;
-    const via = await this.sidecarEndpoint(route, !!policy?.pii);
-    if (via) {
-      await this.requireBudget(envs, "model_calls");
-      try {
-        const res = await omni.chat({ model: route!, messages, tools }, { via, sessionId: this.sessionId, signal });
-        this.lastServedBy = `switchyard ${route} -> ${res.selectedModel ?? "?"}`;
-        this.recordUsage(res, route!, task);
-        return res;
-      } catch (e) {
-        if (signal.aborted) throw e;
-        sidecar!.disable((e as Error).message);
-      }
-    }
     await this.requireBudget(envs, "model_calls");
     const res = await omni.chat({ model: fixedModel, messages, tools }, { signal, ...(policy?.pii ? { onCampusOnly: true } : {}) });
     this.lastServedBy = `omniroute ${fixedModel} (provider ${res.provider ?? "?"})`;
@@ -441,13 +430,8 @@ export class LocalPeer extends BasePeer {
     }
   }
 
-  private async sidecarEndpoint(route: string | undefined, pii: boolean): Promise<string | undefined> {
-    if (!route || route.startsWith("hub/") || pii) return undefined;
-    return this.opts.sidecar?.endpoint();
-  }
-
-  private async conclude(msgs: ChatMessage[], policy: { route?: string; pii: boolean } | undefined, turn: number, step: number, maxSteps: number, answer: string, signal: AbortSignal, decisionId?: string): Promise<string | undefined> {
-    const route = policy?.route ?? this.opts.route, config = this.hubConfig(route);
+  private async conclude(msgs: ChatMessage[], policy: { route?: string; fixedModel?: string; pii: boolean } | undefined, turn: number, step: number, maxSteps: number, answer: string, signal: AbortSignal, decisionId?: string): Promise<string | undefined> {
+    const route = effectiveLocalRoute(this.opts.route, policy?.route, policy?.fixedModel), config = this.hubConfig(route);
     if (!route || !config) return answer;
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...msgs];
     const feedback = await this.routes.review(route, config, messages, this.routeScope(!!policy?.pii, turn), !!policy?.pii, signal, decisionId);
@@ -472,7 +456,7 @@ export class LocalPeer extends BasePeer {
         ...(res.usage ? { usage: res.usage } : {}),
         requestedModel: safeModelLabel(requestedModel) ?? "unknown",
         ...(Number.isSafeInteger(task) && task! > 0 ? { task } : {}),
-        ...(safeModelLabel(res.servedModel ?? res.selectedModel) ? { servedModel: safeModelLabel(res.servedModel ?? res.selectedModel)! } : {}),
+        ...(safeModelLabel(res.servedModel) ? { servedModel: safeModelLabel(res.servedModel)! } : {}),
         ...(safeModelLabel(res.provider) ? { provider: safeModelLabel(res.provider)! } : {}),
       });
     } catch {

package/src/adapters/pi.ts

@@ -429,6 +429,13 @@ export class PiPeer extends BasePeer {
   private verifiedOwner(): boolean {
     return this.ownerClaimed && !!this.ownerPid && !!this.ownerSignature && processSignature(this.ownerPid) === this.ownerSignature;
   }
+
+  terminalOwner(_launchId: string): { generation: string; nativePid: number } | undefined {
+    if (this.opts.mode !== "tui" || !this.started || this.stopping || this.rosterDetached || !this.verifiedOwner() || !this.sessionId || !this.sessionFile ||
+        this.opts.sessionId && this.opts.sessionId !== this.sessionId || this.opts.sessionFile && this.opts.sessionFile !== this.sessionFile) return undefined;
+    const generation = this.sessionGeneration;
+    return generation && this.ownerPid ? { generation, nativePid: this.ownerPid } : undefined;
+  }
   private abortTools(): Promise<void>[] {
     this.executionAbort?.abort();
     this.idleBashReservations.clear();

package/src/cli/console-state.ts

@@ -891,6 +891,7 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     if (p.permissionMode && p.permissionMode !== "ask") summary.push(span(` ${p.permissionMode}`, "attention"));
     if (p.needsReview) summary.push(span(` review${p.needsReview}`, "failure"));
     if (p.paused) summary.push(span(" paused", "attention"));
+    if (typeof p.importantWaitingSince === "number") summary.push(span(` important waiting ${duration(now - p.importantWaitingSince)}`, "attention")); // #572 AC1: a busy ACP peer that cannot be steered
     if (p.toolsOnly) summary.push(span(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") ? ` pull-only, read ${typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never"}` : " tools-only: ahub claude", "attention"));
   }
   if (s.pendingRestart?.length) summary.push(span(`${summary.length ? " | " : ""}restart pending: ${s.pendingRestart.map(row => row.key).join(", ")}`, "attention"));

package/src/cli/console.ts

@@ -86,7 +86,8 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   const { client } = options; const terminal = options.terminal ?? nativeTerminal();
   const color = options.color ?? resolveColor(undefined, { isTTY: terminal.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR }) === true;
   let state = initialConsoleState(!!options.panels); state.project = basename(options.cwd);
-  const pet = loadPetConfig(options.cwd);
+  let pet = loadPetConfig(options.cwd);
+  let petSignature = JSON.stringify([pet.enabled, pet.character, pet.size, pet.glyphs, pet.blink, pet.bell]);
   state.petEnabled = pet.enabled && !options.noPet; state.petBlink = pet.blink;
   state.petChoices = CHARACTER_IDS; state.petCharacter = pet.character ?? "stai";
   state.petSize = pet.size; state.petGlyphs = petGlyphs(pet.glyphs);
@@ -194,6 +195,15 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       if (!active) return;
       const [status, budget, tasks, queue, ready, settings] = replies;
       captureConsoleSelection(state);
+      try {
+        const latestPet = loadPetConfig(options.cwd);
+        const nextSignature = JSON.stringify([latestPet.enabled, latestPet.character, latestPet.size, latestPet.glyphs, latestPet.blink, latestPet.bell]);
+        if (nextSignature !== petSignature) {
+          pet = latestPet; petSignature = nextSignature;
+          state.petEnabled = pet.enabled && !options.noPet; state.petBlink = pet.blink;
+          state.petCharacter = pet.character ?? "stai"; state.petSize = pet.size; state.petGlyphs = petGlyphs(pet.glyphs);
+        }
+      } catch { /* retain running console presentation while a config file is unreadable */ }
       if (status.status?.tasks && status.ok !== false) state.taskCounts = status.status.tasks;
       if (status.status && status.ok !== false) state.pendingRestart = Array.isArray(status.status.pendingRestart) ? status.status.pendingRestart : [];
       if (status.status && status.ok !== false) state.retainedConfig = Array.isArray(status.status.retainedConfig) ? status.status.retainedConfig : [];

package/src/cli/help.ts

@@ -21,6 +21,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub console --no-pet", "turn off attention for this session; combines with --panels and --color"],
     ["ahub pet --window [--close]", "start or close the macOS floating window, from a person's terminal"],
     ["ahub pet [--short]", "read attention without connecting; --short prints ahub!N only when action is needed"],
+    ["ahub pet --palette <blue|teal|violet|ochre>", "save the floating window's base color to pet.palette in .agenthub/config.local.json"],
     ["ahub sdlc status [task] | explain <task> | export <task> | record <task> <receipt-json>", "read head-bound lifecycle gates and the next actor/action (person only)"],
     ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...]", "read-only merge and release evidence (person only)"],
     ["ahub sdlc accept <task> --issue <n> [--repo owner/repo]", "accept the task's spec issue at its current body; build entry needs it in enforce (person only)"],
@@ -36,8 +37,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub doctor --orphans [--kill] [--json] [--color=auto|always|never]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
     ["ahub kill", "stop this project's hub"],
     ["ahub reset [--all] [--yes]", "list, then with --yes stop the hub and discard every queued and needs_review delivery, clear holds and pauses and drop session pointers; --all moves the state directory to .agenthub/archive instead"],
-    ["ahub restart [--dry-run] [--yes]", "recover this project's runtime; on a terminal without a flag it reviews the plan with you, follows the progress and offers the next steps"],
-    ["ahub upgrade [--to <version>] [--dry-run] [--yes]", "review and upgrade running projects; --to defaults to the latest release (--yes needs it), and a newer release's own coordinator takes over; on a terminal without --dry-run or --yes: review, end agents first if you choose, apply, follow, and resume, cancel, end or reset on the spot"],
+    ["ahub restart [--dry-run] [--yes] [--json] [--verbose] [--color=auto|always|never]", "recover this project's runtime; on a terminal without a flag it reviews the plan with you, follows the progress and offers the next steps"],
+    ["ahub upgrade [--to <version>] [--dry-run] [--yes] [--json] [--verbose] [--color=auto|always|never]", "review and upgrade running projects; --to defaults to the latest release (--yes needs it), and a newer release's own coordinator takes over; on a terminal without --dry-run or --yes: review, end agents first if you choose, apply, follow, and resume, cancel, end or reset on the spot"],
     ["ahub recovery [status|resume|abort] [<operation-id>]", "inspect, resume or cancel a preflight; status names the next actions; without an id, the operation that holds the lock, and with nothing else on a terminal its screen"],
     ["ahub recovery reattach <operation-id> codex|claude|pi", "person only: repair that blocked peer with its recorded session; leaves the rest for recovery resume"],
     ["ahub recovery dispose [<operation-id>] --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
@@ -49,10 +50,12 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"],
     ["ahub codex [--print-command] [--unattended] [args...]", "start the Codex adapter and attach the TUI"],
     ["ahub kimi [--print-command] [--mode tui|headless] [--model <alias>]", "default: Kimi's own TUI, pull-only via hub_inbox; no push, steer, watchdog, console approvals or automatic quota handoff. Select headless for ACP"],
-    ["ahub jcode [--mode headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional owned Jcode daemon/ACP; native policy unmanaged, no hub sandbox"],
+    ["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"],
+    ["ahub agy [--print-command | --dry-run] [args...]", "optional Antigravity CLI 1.4.2 TUI in this terminal (roster.agy, default off): pull-only via hub_inbox, implementer/verifier only; native permissions unmanaged, no hub sandbox"],
     ["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", "start optional Qwen Code 0.25.0 ACP (roster.qwen, default off)"],
-    ["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"],
+    ["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"],
     ["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
+    ["ahub claude|codex|kimi|qwen|pi|local --as <instance> [options...]", "start an extra instance of that kind declared under instances in .agenthub/config.local.json"],
     ["ahub role list [--group <group>] | show <id>", "read bounded catalog guidance with layer and content hash"],
     ["ahub role assign <peer> <id> | clear <peer> [<id>]", "person only: add or clear catalog guidance, applied at the next peer start"],
     ["ahub stop <peer>", "human only: stop a hub-owned headless peer; end TUI agents in their terminals"],
@@ -67,7 +70,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub permit <id> <option>", "answer a permission request shown by tail (\"deny\" cancels)"],
     ["ahub roster [--json] [--color=auto|always|never]", "human only: every known peer, participation, start mode and retained work"],
     ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff"],
-    ["ahub settings [list] [--json] | get <key>", "human only: the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
+    ["ahub settings [list] [--json] | get <key> [--json]", "human only: the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
     ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "human only: change or reload validated settings, written to .agenthub/config.local.json or routing.local.toml (never a tracked file); --preview shows the effect and saves nothing; undo puts back the last write"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
     ["ahub queue list [--peer <id>] [--json] [--color=auto|always|never]", "inspect durable deliveries"],
@@ -88,8 +91,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]", "name the owner (default) or reviewer; a task that still waits reserves its owner; --revision refuses stale console actions"],
     ["ahub task unassign <id> [--role owner|reviewer] [--revision N]", "person only: remove the owner/reservation or reviewer without routing a replacement or stopping native work"],
     ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]", "person only: close obsolete work with a reason; retain its history without stopping native work or releasing dependents"],
-    ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned", "your later verdict on an approved task, kept in the research records (research must be on)"],
-    ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]...", "give a review verdict on a task"],
+    ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned [--created <time>]", "your later verdict on an approved task, kept in the research records (research must be on)"],
+    ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>]", "give a review verdict on a task"],
     ["ahub review brief <id>", "print the review brief of a task's commit: reviewable and excluded files, rules, coverage to account for"],
     ["ahub route explain <id>", "why a task went where it went, its reserved owner included"],
     ["ahub route explain --class <c> <title...>", "what would happen to such a task now"],
@@ -113,7 +116,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub research export [--format jsonl|csv] [--since 30d] [--all]", "the research records for outside analysis: ids, counts and tokens, never text"],
     ["ahub research backfill", "build this project's research records once from events.jsonl"],
     ["ahub bench run <suite.json> --arm <label> [--repeat N] [--tasks a,b] [--addon <name>=on|off]... [--memory off|claude-mem|native|both]", "run a benchmark suite against the peers attached here, in a project kept for benchmarks (it resets the work tree); --addon and --memory declare the arm's add-on and memory state and refuse a setup that differs"],
-    ["ahub bench list|status", "benchmark runs on this machine / the one running now"],
+    ["ahub bench list|status [--json]", "benchmark runs on this machine / the one running now"],
     ["ahub bench report <run> [--json]", "pass rate, first pass, rework, tokens and wall time per task and overall"],
     ["ahub bench compare <run|arm>... [--suite <name>] [--mixed] [--json]", "compare arms of one suite with 95% bootstrap intervals; inconclusive below 5 counted attempts per arm"],
     ["ahub bench export [--format jsonl|csv]", "benchmark records for outside analysis: ids, outcomes and counts, never suite text"],
@@ -123,6 +126,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub memory promote|demote|forget <id> | supersede <old> <new> | rebuild", "a person's changes to memory: move an entry between tiers, forget it, mark it superseded, or rebuild the index from the logs"],
     ["ahub memory sync [--remote <private git url>] | machine [--label <name>]", "sync hub memory with your other machines through a private git remote (a person's), or show or name this machine"],
     ["ahub memory import claude-mem [--db <path>] [--limit N] [--restart] | dedupe [--apply] | suggestions | confirm|reject <id>", "copy the hub's notes from claude-mem into hub memory (a person's); review the model's suggested edges"],
+    ["ahub memory decay [--days N] [--json]", "person only: list long-term entries older than N days (default 90) that no open goal links; review only, nothing is changed"],
+    ["ahub memory profile-check [--json]", "read-only check of the running hubs' memory bindings against their memory profiles; exits 1 when one is not ready"],
     ["ahub goal [list] [--all] | show <id> [--json]", "long-term tasks: state, which machine holds each and until when, linked board tasks"],
     ["ahub goal new <title> [--milestone <text>]... [--depends <id>]... [--shared] | link <id> <task> | state <id> <state> | done <id> | take <id> [--force]", "a person's changes to long-term tasks; take --force voids other machines' claims"],
   ]],

package/src/cli/identity-audit.ts

@@ -22,7 +22,7 @@ const splitLabel = (label: string): [string, string[]] => { const [command = "un
  * the checked 256-file / 64 KiB ceiling by at most one bounded row per concurrent writer.
  * Unpublished temp files count against the ceiling, so a crashed writer cannot grow the spool forever.
  */
-export function recordCliAudit(stateDir: string, peer: string, command: string, outcome: CliAudit["outcome"]): void {
+function reserveCliAudit(stateDir: string, peer: string, command: string, outcome: CliAudit["outcome"]) {
   const row: CliAudit = { v: 1, id: crypto.randomUUID(), at: Date.now(), peer, command, outcome };
   if (!valid(row)) throw new Error("invalid CLI audit identifiers");
   const dir = join(stateDir, "cli-audit");
@@ -36,13 +36,39 @@ export function recordCliAudit(stateDir: string, peer: string, command: string,
   const text = JSON.stringify(row) + "\n";
   if (Buffer.byteLength(text) > MAX_ROW_BYTES || files.length >= MAX_FILES || bytes + Buffer.byteLength(text) > MAX_BYTES) throw new Error("CLI audit outbox is full");
   const pending = join(dir, `${row.id}.tmp`);
+  try { writeFileSync(pending, text, { mode: 0o600, flag: "wx" }); }
+  catch (error) { try { unlinkSync(pending); } catch { /* only this writer's unpublished file */ } throw error; }
+  return {
+    id: row.id,
+    commit(outcome: CliAudit["outcome"]) {
+      if (!valid({ ...row, outcome })) throw new Error("invalid CLI audit identifiers");
+      writeFileSync(pending, JSON.stringify({ ...row, outcome }) + "\n", { mode: 0o600 });
+      renameSync(pending, join(dir, `${row.id}.json`));
+    },
+    close() { try { unlinkSync(pending); } catch { /* only this writer's unpublished file */ } },
+  };
+}
+
+export function recordCliAudit(stateDir: string, peer: string, command: string, outcome: CliAudit["outcome"]): void {
+  const pending = reserveCliAudit(stateDir, peer, command, outcome);
+  try { pending.commit(outcome); }
+  finally { pending.close(); }
+}
+
+/** Reserve the bounded audit before connecting; old drains never see an unsupported ready row. */
+export async function recordDelegatedCliAudit(stateDir: string, peer: string, command: string, features: () => Promise<readonly string[]>): Promise<string> {
+  let pending: ReturnType<typeof reserveCliAudit>;
+  try { pending = reserveCliAudit(stateDir, peer, command, "delegated"); }
+  catch { throw new Error("live-test delegation audit unavailable; nothing was executed"); }
   try {
-    writeFileSync(pending, text, { mode: 0o600, flag: "wx" });
-    renameSync(pending, join(dir, `${row.id}.json`));
-  } catch (error) {
-    try { unlinkSync(pending); } catch { /* only this writer's unpublished file */ }
-    throw error;
-  }
+    let supported = false;
+    try { supported = (await features()).includes("cli_audit_delegated"); }
+    catch { /* unavailable authentication is not proof of an audit consumer */ }
+    try { pending.commit(supported ? "delegated" : "refused"); }
+    catch { throw new Error("live-test delegation audit unavailable; nothing was executed"); }
+    if (!supported) throw new Error("running hub cannot retain delegated CLI audits; upgrade it from a person's terminal, or use the audited upgrade/recovery path; nothing was executed");
+    return pending.id;
+  } finally { pending.close(); }
 }
 
 /** Consume ready files only; rebuild fixed fields so titles or other injected text cannot be rendered. */

package/src/cli/jcode-mcp.ts

@@ -1,2 +1,2 @@
 /** Compatibility exports; the project MCP layer is native adapter policy. */
-export { JCODE_MCP_FILE, JCODE_MCP_NAME, jcodeMcpEntry, jcodeMcpReady, configureJcodeMcp } from "../adapters/definitions/native-cli-jcode-mcp.ts";
+export { JCODE_MCP_FILE, JCODE_MCP_NAME, jcodeMcpEntry, jcodeMcpReady, configureJcodeMcp, jcodeExtraMcpServers } from "../adapters/definitions/native-cli-jcode-mcp.ts";