@staix/agent-hub 0.27.0 → 0.28.0

package/src/adapters/claude-channel.ts

@@ -13,6 +13,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { ControlClient, INVOCATION_CONTROL_TIMEOUT_MS } from "../hub/control-client.ts";
+import { toolWriteOperation } from "../hub/tool-request.ts";
 import { channelProject } from "../hub/channel-project.ts";
 import { VERSION } from "../version.ts";
 import { IMPLEMENTER_HUB_TOOL_NAMES, IMPLEMENTER_PERMISSION_TOOL, ACTIONABLE_MESSAGE_INSTRUCTION, projectConductorTools, projectToolList, CONDUCTOR_TOOL_NAMES, DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.ts";
@@ -394,7 +395,7 @@ function toolListFor(lifecycle: Awaited<ReturnType<typeof activeLifecycle>>) {
             ? [
                 {
                   name: "hub_delivery_done",
-                  description: "Explicitly complete one handled channel delivery using its delivery_id and delivery_generation metadata. Does not change task state. Never use for an unhandled or uncertain delivery.",
+                  description: "Explicitly complete one handled channel delivery using its delivery_id and delivery_generation metadata. Does not change task state. If a prior result was outcome unknown, read the queue first and retry only if the delivery is still unresolved, with the same delivery_id and delivery_generation. Never complete an unhandled delivery.",
                   inputSchema: { type: "object", properties: { delivery_id: { type: "string" }, delivery_generation: { type: "string" } }, required: ["delivery_id", "delivery_generation"], additionalProperties: false },
                 },
               ]
@@ -443,6 +444,7 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
     if (!hub) return text(offline());
     const a = args ?? {};
     const result = await hub.request({ t: "delivery_complete", deliveryId: a.delivery_id, generation: a.delivery_generation });
+    if (result.outcome === "unknown") return text(typeof result.error === "string" ? result.error : "Write outcome unknown. Inspect the delivery before another write; call again only if it is absent, with the same delivery id and generation.");
     return text(result.ok ? "delivery completed" : `not completed: ${result.error}`);
   }
   if (name === "hub_inbox" && (!toolsMode || permissionTool)) {
@@ -483,7 +485,15 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
     if (!hub) return text(offline());
     // #445 C2: a daemon that predates invocations would answer with a generic unknown-operation error; say what is missing instead.
     if (name === "hub_invoke" && !hub.features.includes("invocation")) return { ...text("error: this hub does not support invocations; restart it with the current agent-hub release (ahub restart)"), isError: true };
-    const res = await hub.request({ t: "task", op: name, args: args ?? {} }, name === "hub_invoke" ? INVOCATION_CONTROL_TIMEOUT_MS : undefined, name === "hub_invoke" ? signal : undefined);
+    const rawArgs = args ?? {}, operation = toolWriteOperation({ t: "task", op: name });
+    let taskArgs = rawArgs, requestId: unknown;
+    if (operation && Object.hasOwn(rawArgs, "request_id")) {
+      requestId = rawArgs.request_id;
+      const { request_id: _requestId, ...withoutRequestId } = rawArgs;
+      taskArgs = withoutRequestId;
+    }
+    const res = await hub.request({ t: "task", op: name, args: taskArgs, ...(requestId !== undefined ? { requestId } : {}) }, name === "hub_invoke" ? INVOCATION_CONTROL_TIMEOUT_MS : undefined, name === "hub_invoke" ? signal : undefined);
+    if (res.outcome === "unknown") return text(typeof res.error === "string" ? res.error : "Write outcome unknown. Inspect the task before another write; call again only if it is absent, with the same request_id and arguments.");
     return { ...text(res.ok ? res.text : `error: ${res.error}`), ...(res.ok ? {} : { isError: true }) };
   }
   return text(`unknown tool ${name}`);

package/src/adapters/compat.ts

@@ -40,7 +40,7 @@ export const COMPAT = {
     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-10-31-claude-implementer-2.1.316.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
-  "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0", "0.164.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
+  "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" },

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

@@ -14,6 +14,8 @@ export interface InstalledPlugin {
   id: string;
   version?: string;
   installPath?: string;
+  scope?: string;
+  projectPath?: string;
 }
 export interface Marketplace {
   name: string;
@@ -45,26 +47,43 @@ const read = (p: string) => {
   }
 };
 
-export type PluginState = { state: "missing" } | { state: "current"; version: string } | { state: "stale"; version: string; why: string };
+export type PluginState =
+  | { state: "missing"; notices?: string[] }
+  | { state: "current"; version: string; notices?: string[] }
+  | { 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;
+
+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 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`;
+  });
+}
 
 /**
  * Is the installed Claude plugin the one this hub ships? The version is compared, and so is the bundle itself: Claude
  * Code runs a cached copy, and a copy taken from an earlier build of the same version speaks an older wire protocol.
  */
 export function pluginState(plugins: InstalledPlugin[], packageRoot: string): PluginState {
-  const mine = plugins.find((p) => p.id === PLUGIN);
-  if (!mine) return { state: "missing" };
+  const notices = nonUserPluginNotices(plugins);
+  const mine = plugins.find((p) => p.id === PLUGIN && p.scope === "user");
+  if (!mine) return { state: "missing", ...(notices.length ? { notices } : {}) };
   const version = mine.version ?? "unknown";
-  if (version !== VERSION) return { state: "stale", version, why: `version ${version}, this hub is ${VERSION}` };
+  if (version !== VERSION) return { state: "stale", version, why: `version ${version}, this hub is ${VERSION}`, ...(notices.length ? { notices } : {}) };
   const shipped = read(join(packageRoot, "plugins", "agent-hub", "server.js"));
   const cached = mine.installPath ? read(join(mine.installPath, "server.js")) : undefined;
-  if (shipped !== undefined && cached !== undefined && shipped !== cached) return { state: "stale", version, why: "same version, but the cached bundle differs from the one this hub ships" };
-  return { state: "current", version };
+  if (shipped !== undefined && cached !== undefined && shipped !== cached) return { state: "stale", version, why: "same version, but the cached bundle differs from the one this hub ships", ...(notices.length ? { notices } : {}) };
+  return { state: "current", version, ...(notices.length ? { notices } : {}) };
 }
 
 export interface SetupStep {
   why: string;
   argv: string[];
+  blocked?: true;
 }
 
 /**
@@ -74,11 +93,14 @@ export interface SetupStep {
 export function nextStep(plugins: InstalledPlugin[], marketplaces: Marketplace[], packageRoot: string): SetupStep | undefined {
   const root = real(packageRoot);
   const market = marketplaces.find((m) => m.name === MARKETPLACE);
-  if (market && real(market.path ?? "") !== root) return { why: `the ${MARKETPLACE} marketplace points at ${market.path ?? "another source"}, not at this package`, argv: ["claude", "plugin", "marketplace", "remove", 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 };
+    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] };
   const state = pluginState(plugins, root);
-  if (state.state === "missing") return { why: "install the channel plugin", argv: ["claude", "plugin", "install", PLUGIN] };
+  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.
-  if (state.state === "stale") return { why: `replace the installed plugin (${state.why})`, argv: ["claude", "plugin", "uninstall", PLUGIN] };
+  if (state.state === "stale") return { why: `replace the installed user-scope plugin (${state.why})`, argv: ["claude", "plugin", "uninstall", PLUGIN, "--scope", "user"] };
   return undefined;
 }

package/src/adapters/definitions/native-cli-entry-jcode.ts

@@ -3,10 +3,40 @@ import { resolve } from "node:path";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 import type { ControlClient } from "../../hub/control-client.ts";
 import type { JcodeTuiBinding, JcodeTuiState } from "../jcode.ts";
+import { JCODE_HEADLESS_AFTER_RECOVERY } from "../jcode.ts";
 import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
 
 const WAITING = "jcode's TUI opens after its first hub turn; send it work, or Ctrl-C";
 
+/**
+ * #1085: what to tell the person for each cause class the daemon returns as `code`. Fixed text: the daemon's reply carries a code, never a path or id, and nothing else is echoed.
+ * A session that was loaded from a record (`resumed`, crash or controlled recovery) is running headless: the way back to its TUI is stop, then start.
+ */
+export function jcodeTuiCauseMessage(code: unknown, resumed = false): string | undefined {
+  // The cause sentence is per class (AC1). The next step is per class too, except that a session loaded from a record is
+  // running headless from recovery, whatever refused the TUI: its way back is always stop, then start (AC2).
+  const recoveredStep = `${JCODE_HEADLESS_AFTER_RECOVERY}`;
+  const step = (own: string) => resumed ? recoveredStep : own;
+  switch (code) {
+    case "launch_changed": return `Jcode was restarted while ahub jcode was starting its TUI; ${step("run ahub jcode again")}`;
+    case "server_not_running": return `Jcode's owned server is not running; ${step("run ahub stop jcode, then ahub jcode")}`;
+    case "socket_changed": return `Jcode's private socket was replaced by another process; ${step("run ahub stop jcode, then ahub jcode")}`;
+    case "session_unknown": return `Jcode has not reported a session yet; ${step("wait for it to attach, then run ahub jcode again")}`;
+    case "session_proof_refused": return `Jcode's saved session failed the hub's safety check (not a plain file, too large, or another session); ${step("run ahub stop jcode, then ahub jcode for a new session")}`;
+    case "hub_busy": return "the hub is stopping, recovering or changing its roster; wait for ahub status to settle, then run ahub jcode again";
+    case "not_running": return "Jcode is not running under this hub; run ahub jcode again";
+    case "mcp_stale": return "the project's Jcode MCP entry is missing or stale; run ahub jcode again to rewrite it";
+    default: return undefined;
+  }
+}
+
+/** Names the cause class the daemon returned (#1085). An older daemon sends no code: the caller's generic message stands. */
+function refuseTuiCause(reply: { ok?: unknown; code?: unknown; resumed?: unknown }, fail: NativeCliEntryContext["fail"]): void {
+  if (reply.ok) return;
+  const message = jcodeTuiCauseMessage(reply.code, reply.resumed === true);
+  if (message) fail(message);
+}
+
 /** The daemon names the one session option that differs from the attached saved session (#559 N2, #574). */
 function refuseNamedOption(reply: { ok?: unknown; option?: unknown }, fail: NativeCliEntryContext["fail"]): void {
   if (!reply.ok && typeof reply.option === "string" && ["--session-id", "--model", "--provider-profile"].includes(reply.option)) fail(`Jcode is already running with a different ${reply.option}; run ahub jcode without it, or stop jcode first`);
@@ -20,6 +50,7 @@ export async function waitForJcodeTui(hub: ControlClient, fail: NativeCliEntryCo
       const reply = await hub.request({ t: "native_tui_launch", peer: "jcode", binding, args: options });
       if (signal.aborted) return;
       refuseNamedOption(reply, fail);
+      refuseTuiCause(reply, fail);
       if (!reply.ok || !reply.binding || !["waiting", "ready"].includes(reply.state)) fail("Jcode launch changed or its native saved session is unavailable; retry from a terminal");
       current = reply as JcodeTuiState;
     }
@@ -78,6 +109,7 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
       if (!hub.features.includes("native_tui_launch") || mode !== "tui") return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2));
       const reply = await hub.request({ t: "native_tui_launch", peer: "jcode", args: options });
       refuseNamedOption(reply, fail);
+      refuseTuiCause(reply, fail);
       if (!reply.ok || reply.state !== "ready") fail("Jcode's selected native session is not saved and ready; run ahub jcode to wait for its first hub turn");
       return console.log(JSON.stringify(reply.launch, null, 2));
     }
@@ -102,6 +134,7 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
     // no terminal recovery adapter (#564).
     const confirmed = await hub.request({ t: "native_tui_launch", peer: "jcode", binding: ready.binding, args: options });
     if (interruptedWait()) return;
+    refuseTuiCause(confirmed, fail);
     if (!confirmed.ok || confirmed.state !== "ready") fail("Jcode launch changed before its terminal opened");
     // ponytail: jcode 0.98.1's top-level TUI spawns a shared server (no --temporary-server or --owner-pid) when nothing
     // answers on the dialed socket at startup, and on its reload-handoff reconnect. A hub stop or an owned-server crash

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

@@ -43,9 +43,9 @@ export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
   // The daemon's launch env carries only the peer marker: Qwen runs in the person's own terminal and needs their PATH, HOME (its settings and sessions) and the key its provider
   // names, none of which the daemon may copy. So the person's environment is the base and the daemon's marker goes over it. (Measured: without this the exec found no `qwen`.)
   // That terminal may itself be inside another agent (a Claude or Codex shell): its vendor markers and every hub marker but AGENTHUB_HOME are dropped, so Qwen and its hub MCP
-  // server never carry another peer's identity, launch id or mode.
+  // server never carry another peer's identity, launch id or mode. Its ORCA_* values belong to this person-owned pane and are retained.
   const person = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("AGENTHUB_") || name === "AGENTHUB_HOME"));
-  const env = { ...peerChildEnv(peer, person), ...verified.env };
+  const env = { ...peerChildEnv(peer, person, { preserveOrca: true }), ...verified.env };
   delete env.AGENTHUB_RECOVERY_OPERATION; delete env.AGENTHUB_UNATTENDED;
   console.error("Qwen runs in this terminal, driven by the hub through its dual-output files. Limits: a hub deny ends the turn without an answer, and a stalled turn is stopped only by pressing Esc here.");
   return execWithEnv(verified.cmd, verified.args, env);

package/src/adapters/jcode.ts

@@ -19,6 +19,8 @@ export interface JcodeOptions extends Omit<AcpOptions, "cmd" | "qwen025" | "expe
   provider?: string;
   /** How long a native steer may take to be acknowledged (#572); default 5 s. */
   steerTimeoutMs?: number;
+  /** #1085: what the hub knows that the adapter does not, asked when status is built: is this peer's start mode tui, and did this hub run start after a crash report. */
+  tuiHintContext?: () => { tui: boolean; afterCrash: boolean };
 }
 export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string, provider?: string, peer = "jcode"): string[] {
   if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
@@ -73,6 +75,16 @@ function savedSession(home: string, id: string): boolean {
 export class JcodeOptionMismatch extends Error {
   constructor(readonly option: "--session-id" | "--model" | "--provider-profile") { super("Jcode launch options differ from its running session"); }
 }
+/**
+ * #1085: why an owned Jcode refused a TUI launch. A closed set of causes, never a path, session id or launch id:
+ * the daemon logs the code and returns it, and the launcher turns it into a message with a next step.
+ */
+export type JcodeTuiRefusalCode = "launch_changed" | "server_not_running" | "socket_changed" | "session_unknown" | "session_proof_refused";
+export class JcodeTuiRefusal extends Error {
+  constructor(readonly code: JcodeTuiRefusalCode) { super(`owned Jcode TUI launch refused: ${code}`); }
+}
+/** #1085: said by `ahub status` while a recovered headless Jcode has not yet opened its TUI, and by the launcher when `ahub jcode` finds it running headless. */
+export const JCODE_HEADLESS_AFTER_RECOVERY = "jcode is running headless after recovery; run ahub stop jcode, then ahub jcode to get its TUI back";
 const JCODE_OWNED_ENV = { JCODE_DISABLE_CLAUDE_MCP: "1", JCODE_NO_TELEMETRY: "1" } as const;
 /** #691: the verdict lives in `src/adapters/compat.ts` (line, verified versions, the person's trust); never pin here. */
 export const jcodeVersionSupported = (version: unknown): boolean => assessVersion("jcode", version).ok;
@@ -194,6 +206,8 @@ export class JcodePeer extends AcpPeer {
   private ending = false;
   private preserveRoot = false;
   private stopPromise: Promise<void> | undefined;
+  /** #1085: a ready TUI launch was served for this owned launch, so the person is on the way to its TUI. */
+  private tuiServed = false;
 
   constructor(private readonly jcode: JcodeOptions) {
     if (!isAbsolute(jcode.home)) throw new Error("jcode_home must be an absolute native data path");
@@ -215,6 +229,20 @@ export class JcodePeer extends AcpPeer {
 
   ownsLaunch(launchId: unknown): boolean { return !this.ending && typeof launchId === "string" && launchId === this.launchId; }
 
+  /**
+   * #1085: after recovery this Jcode can be live and headless while its start mode is tui and no `ahub jcode` has reached its TUI yet: say how to get the TUI back.
+   * Only while it is live, only after a crash report or a resumed session, and never once a ready TUI launch was served. Fixed text: no id, path or socket.
+   */
+  get statusNotice(): { code: "jcode-headless-after-recovery"; message: string } | undefined {
+    if (this.state === "offline" || this.tuiServed) return undefined;
+    const context = this.jcode.tuiHintContext?.();
+    if (!context?.tui || !(context.afterCrash || this.resumedSession)) return undefined;
+    return { code: "jcode-headless-after-recovery", message: JCODE_HEADLESS_AFTER_RECOVERY };
+  }
+
+  /** #1085: this owned launch loaded a recorded session id (crash or controlled recovery, or the person's --session-id) instead of making a new one. A boolean only, never the id. */
+  get resumedSession(): boolean { return typeof this.jcode.resumeSessionId === "string" && this.jcode.resumeSessionId.length > 0; }
+
   override async start(): Promise<void> {
     // The native loader otherwise imports Codex MCP into the user's store on first use.
     if (!existsSync(join(this.jcode.home, "mcp.json"))) throw new Error("initialize Jcode's global MCP store with its native client before enabling this peer; the hub never initializes or copies it");
@@ -315,16 +343,21 @@ export class JcodePeer extends AcpPeer {
   tuiLaunch(expected?: JcodeTuiBinding, options: { model?: string; providerProfile?: string; sessionId?: string } = {}): JcodeTuiState {
     const sessionId = super.recoveryMetadata().sessionId;
     const socket = lstatSync(this.socket, { throwIfNoEntry: false });
-    if (this.ending || !this.server || this.server.exitCode !== null || this.server.signalCode !== null || this.state === "offline" ||
-      !socket?.isSocket() || socket.dev !== this.socketIdentity?.dev || socket.ino !== this.socketIdentity.ino || typeof sessionId !== "string") throw new Error("owned Jcode launch is unavailable");
+    // One cause per check, in the order the checks ran before #1085, so the same states are refused as before.
+    if (this.ending || !this.server || this.server.exitCode !== null || this.server.signalCode !== null || this.state === "offline") throw new JcodeTuiRefusal("server_not_running");
+    if (!socket?.isSocket() || socket.dev !== this.socketIdentity?.dev || socket.ino !== this.socketIdentity.ino) throw new JcodeTuiRefusal("socket_changed");
+    if (typeof sessionId !== "string") throw new JcodeTuiRefusal("session_unknown");
     const binding = { launchId: this.launchId, sessionId };
-    if (expected && (expected.launchId !== binding.launchId || expected.sessionId !== binding.sessionId)) throw new Error("Jcode launch changed");
+    if (expected && (expected.launchId !== binding.launchId || expected.sessionId !== binding.sessionId)) throw new JcodeTuiRefusal("launch_changed");
     // 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 };
+    let saved: boolean;
+    try { saved = savedSession(this.jcode.home, sessionId); } catch { throw new JcodeTuiRefusal("session_proof_refused"); }
+    if (!saved) return { state: "waiting", binding };
+    this.tuiServed = true;
     const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile, this.jcode.provider);
     // The TUI is the person's own client of this peer's server. The shared project MCP entry names no peer (#685), so every launch
     // path supplies its own id: the base Jcode's too, or its MCP child would fall back to the channel default.

package/src/adapters/qwen-dual.ts

@@ -2,7 +2,8 @@ import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSy
 import { join } from "node:path";
 import { renderDigest, replyAudience, replyParent, sanitize, type Envelope, type PeerId } from "../hub/envelope.ts";
 import { BasePeer, type DeliveryReceipt } from "../hub/peers.ts";
-import { peerChildEnv, processTable, type ProcRow } from "../hub/child-process.ts";
+import { childEnv, peerChildEnv, processTable, type ProcRow } from "../hub/child-process.ts";
+import { withoutOrcaEnv } from "../hub/orca-env.ts";
 import { processSignature } from "../pi/process-signature.ts";
 import { assessVersion } from "./compat.ts";
 import { qwenSessionId } from "./definitions/qwen-native.ts";
@@ -97,7 +98,7 @@ export function isQwenTaskNotification(text: string): boolean { return text.leng
 export async function qwenDualVersionAsync(cmd: readonly string[], cwd: string): Promise<{ ok: true; version: string; note?: string } | { ok: false; reason: string }> {
   const [bin, ...prefix] = cmd.filter(word => word !== "--acp");
   try {
-    const child = Bun.spawn([bin ?? "qwen", ...prefix, "--version"], { cwd, stdout: "pipe", stderr: "ignore", stdin: "ignore", env: { ...process.env } });
+    const child = Bun.spawn([bin ?? "qwen", ...prefix, "--version"], { cwd, stdout: "pipe", stderr: "ignore", stdin: "ignore", env: withoutOrcaEnv(childEnv(process.env)) });
     const timer = setTimeout(() => child.kill("SIGKILL"), 10_000);
     const out = await new Response(child.stdout).text(); await child.exited; clearTimeout(timer);
     const verdict = assessVersion("qwen-dual", out.trim());

package/src/cli/agents.ts

@@ -1,5 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { assessVersion, COMPAT, describe, isCompatId, readTrust, trustFile, writeTrust, type CompatId, type CompatVerdict } from "../adapters/compat.ts";
+import { childEnv } from "../hub/child-process.ts";
+import { withoutOrcaEnv } from "../hub/orca-env.ts";
 
 /** #691: what `ahub agents` and `ahub doctor` show for each gated native CLI. */
 export interface AgentVersionRow { id: CompatId; executable?: string; verdict: CompatVerdict; policy: string }
@@ -25,7 +27,7 @@ export function agentVersions(commands: Partial<Record<CompatId, readonly string
   return (Object.keys(COMPAT) as CompatId[]).map(id => {
     const target = probeTarget(id, commands);
     if (!target) return probeRow(id, undefined, undefined, trusted);
-    const result = spawnSync(target.executable, target.args, { encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024, env: { ...process.env, ...PROBE_ENV } });
+    const result = spawnSync(target.executable, target.args, { encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024, env: withoutOrcaEnv(childEnv({ ...process.env, ...PROBE_ENV })) });
     return probeRow(id, target.executable, result.status === 0 ? result.stdout ?? "" : undefined, trusted);
   });
 }
@@ -42,7 +44,7 @@ const PROBE_EXIT_GRACE_MS = 250;
  * The upgrade is a process group via child_process (as `jcodeVersionAsync` does).
  */
 async function runProbe(executable: string, args: readonly string[], timeoutMs: number, graceMs = PROBE_EXIT_GRACE_MS): Promise<string | undefined> {
-  const child = Bun.spawn([executable, ...args], { stdout: "pipe", stderr: "ignore", stdin: "ignore", env: { ...process.env, ...PROBE_ENV }, timeout: timeoutMs, killSignal: "SIGKILL" });
+  const child = Bun.spawn([executable, ...args], { stdout: "pipe", stderr: "ignore", stdin: "ignore", env: withoutOrcaEnv(childEnv({ ...process.env, ...PROBE_ENV })), timeout: timeoutMs, killSignal: "SIGKILL" });
   const reader = child.stdout.getReader();
   const chunks: Uint8Array[] = [];
   let total = 0, overflow = false, cancelled = false;

package/src/cli/bench.ts

@@ -284,9 +284,11 @@ async function runAttempt(task: SuiteTask, commit: string, repeat: number, run:
   for (;;) {
     let state: string | undefined;
     try {
-      const list = await hub.request({ t: "task", op: "hub_task_list", args: {} }, 15_000);
+      const list = await hub.request({ t: "task", op: "hub_task_list", args: { ids: [id] } }, 15_000);
       if (!list.ok) return done("error", { error: "hub stopped", hubTask: id, open: true });
-      state = (JSON.parse(String(list.text)) as { id: number; state: string }[]).find((t) => t.id === id)?.state;
+      // #1083: a current hub answers {tasks, total}; one from before the change ignores `ids` and answers the whole board as an array.
+      const parsed = JSON.parse(String(list.text)) as { id: number; state: string }[] | { tasks: { id: number; state: string }[] };
+      state = (Array.isArray(parsed) ? parsed : parsed.tasks).find((t) => t.id === id)?.state;
     } catch { return done("error", { error: "hub stopped", hubTask: id, open: true }); }
     if (state === "approved") break;
     if (opts.stopped?.()) return done("error", { error: "interrupted", hubTask: id, open: true });

package/src/cli/board-read.ts

@@ -10,3 +10,28 @@ export function supportsBoardColumnMetadata(status: unknown): boolean {
   const capability = (status as Record<string,unknown>).boardReadCapabilities;
   return !!capability && typeof capability === "object" && (capability as Record<string,unknown>).columnMetadata === true;
 }
+
+/** The most pages `ahub board` follows (200 rows each): a board larger than this is refused with a cause instead of read forever. */
+export const BOARD_MAX_PAGES = 100;
+
+/**
+ * #1083: `hub_task_list` answers an agent with `{tasks, total, next?}` and the person's console, or a hub from before the change, with the bare array.
+ * Read the whole board either way: ask for full rows in the largest page, follow `next` until it is absent, and return one flat array of rows.
+ * A person's console answers the bare array to a request that names no paging argument, but this reader names them, so it reads both shapes.
+ */
+export async function readAllTasks(call: (args: Record<string, unknown>) => Promise<string>, args: Record<string, unknown>, paged = true): Promise<any[]> {
+  const rows: any[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < BOARD_MAX_PAGES; page++) {
+    // A person's console is answered the bare array to a request with no paging argument, so it sends none and its request is unchanged; an agent shell is always paged.
+    const parsed: unknown = JSON.parse(await call(paged ? { ...args, detail: true, limit: 200, ...(cursor ? { cursor } : {}) } : args));
+    if (Array.isArray(parsed)) return parsed; // an older hub ignores the paging arguments and answers the whole board
+    const body = parsed as { tasks?: unknown; next?: unknown };
+    if (!body || !Array.isArray(body.tasks)) throw new Error("the hub's task list reply has neither rows nor a task array; upgrade or restart the hub (ahub status)");
+    rows.push(...body.tasks);
+    if (typeof body.next !== "string" || !body.next) return rows.sort((a, b) => a.id - b.id); // the bare array was in id order and the renderers print rows as given
+    if (body.next === cursor) throw new Error("the hub's task list cursor did not advance; run ahub status and retry");
+    cursor = body.next;
+  }
+  throw new Error(`the board is larger than ${BOARD_MAX_PAGES * 200} tasks, more than ahub board reads; filter it with a state or --release`);
+}

package/src/cli/claude-homes.ts

@@ -2,7 +2,7 @@ import { lstatSync, statSync } from "node:fs";
 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, nextStep, pluginState, type InstalledPlugin, type Marketplace, type PluginState, type SetupStep } from "./setup.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";
 
 export type ClaudeHomeSource = "environment" | "default" | "recorded-launch";
@@ -115,7 +115,7 @@ export async function checkClaudeHome(home: ClaudeHome, packageRoot: string, env
     if (!marketplaces) return unknown();
     const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
     if (!plugins.every(row => object(row) && typeof row.id === "string" && row.id.length <= 256 &&
-      (row.version === undefined || typeof row.version === "string" && row.version.length <= 64 && /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(row.version)) &&
+      (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 };

package/src/cli/console-state.ts

@@ -637,10 +637,15 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
           for (let i = reasonAt + 1; reasonAt >= 0 && i < parsed.length && !parsed[i]!.startsWith("--"); i++) words.push(parsed[i]!);
           const reason = words.join(" ").trim();
           if (!peer || !reason) throw new Error("queue discard needs --peer and --reason (it is recorded on every discarded delivery)");
-          const count = s.queue.filter(row => row.peer === peer && row.state === state).length;
-          const args = ["queue", "discard", "--peer", peer, ...(parsed.includes("--state") ? ["--state", state] : []), "--reason", reason, "--yes"];
+          // #1096: with no --state the CLI clears the peer's queued rows and its unsettled failed rows (the list this panel shows already hides settled ones), so the count names both. A hub without `queue_discard_states` cannot take that form: the command then names the one kind it can clear, queued, and the count follows it.
+          const bulk = !parsed.includes("--state") && s.features?.includes("queue_discard_states") === true;
+          const kinds = bulk ? ["queued", "failed"] : [state];
+          const counts = kinds.map(kind => [kind, s.queue.filter(row => row.peer === peer && row.state === kind).length] as const);
+          const count = counts.reduce((sum, [, n]) => sum + n, 0);
+          const what = bulk && counts.every(([, n]) => n > 0) ? counts.map(([kind, n]) => `${n} ${kind}`).join(" and ") : bulk ? `${count} ${counts.find(([, n]) => n > 0)?.[0] ?? "queued"}` : `${count} ${state}`;
+          const args = ["queue", "discard", "--peer", peer, ...(parsed.includes("--state") ? ["--state", state] : s.features !== undefined && !bulk ? ["--state", "queued"] : []), "--reason", reason, "--yes"];
           s.history = [...s.history, input].slice(-(s.historyLimit ?? CONSOLE_HISTORY_LIMIT)); s.historyIndex = s.history.length;
-          s.confirm = { type: "command", args, prompt: `discard all ${count} ${state} deliver${count === 1 ? "y" : "ies"} of ${peer}; no task or native turn is cancelled, other peers are untouched` };
+          s.confirm = { type: "command", args, prompt: `discard all ${what} deliver${count === 1 ? "y" : "ies"} of ${peer}; no task or native turn is cancelled, other peers are untouched` };
           return done();
         }
         const reviewProblem = reviewRefusal(parsed);                                           // an empty changes note never reaches the hub (#711)

package/src/cli/help.ts

@@ -7,11 +7,12 @@ export interface HelpEntry { section: string; usage: string; description: string
 
 const SECTIONS: [string, [usage: string, description: string][]][] = [
   ["Projects", [
+    ["ahub specs list [--json] | check [--require-fresh] [--base <ref>] [--json] | covers <file...> | stamp <id-or-document...> [--yes]", "read design specs, validate their graph and source freshness, or find covering specs; runs without a daemon; check exits 1 on errors and, with --require-fresh, stale documents; stamp is person only (a terminal, never an agent): it shows old -> new, asks (--yes skips the question but still needs a terminal), and then changes only the verified-against line (or the stamps-file entry) to the full HEAD SHA, refused while the covered paths have uncommitted changes"],
     ["ahub --project <path|id> <command>", "select a repository or worktree explicitly"],
     ["ahub projects [--json] [--full] [--color=auto|always|never]", "list registered projects and live status"],
     ["ahub projects remove <id>", "forget a stopped registration (keeps project files)"],
     ["ahub setup [--yes] [--agents <a,b>]", "install or update the channel plugin and project-neutral hook in Claude configuration homes in use, preserving unrelated profile settings, ask once which agents ahub up starts (--agents answers it, --yes keeps the current choice or claude,codex, no terminal keeps the default), register the acon console plugin (console/plugins/ahub.json in the hub home, read at acon's next start), then run doctor"],
-    ["ahub init [--profile dev|research|writing|general|<pack>] [--shadow] [--release-guard] [--dry-run --json]", "preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block); a pack is a shipped one (writing-pack, analysis, ops) or a project file .agenthub/roles/<name>.pack.json; a new project inherits a trusted machine autonomy default and the agent set chosen at ahub setup (start.agents) into config.local.json"],
+    ["ahub init [--profile dev|research|writing|general|<pack>] [--agents <a,b,...|none>] [--sdlc off|advise|enforce] [--coordination advisory|turn-free] [--memory|--no-memory] [--snapshots|--no-snapshots] [--pi|--no-pi] [--specs|--no-specs] [--spec-review off|report|require] [--autonomy inherit|off] [--shadow] [--release-guard] [--yes] [--dry-run --json]", "preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block); a pack is a shipped one (writing-pack, analysis, ops) or a project file .agenthub/roles/<name>.pack.json; a new project inherits a trusted machine autonomy default and the agent set chosen at ahub setup (start.agents) into config.local.json. Settings flags (#1065): --agents sets start.agents (none starts no agent) and --autonomy off skips the autonomy inheritance, both in config.local.json; --sdlc sets sdlc.toml mode (off writes no file on a new project); --coordination, --memory, --snapshots and --pi set their keys in config.json. On an existing project only a flag you give changes anything, and --dry-run shows each change as old -> new (--dry-run --json adds a settings array); a value equal to the current one is a no-op, an invalid value is refused with the allowed ones and nothing is written. --specs/--no-specs and --spec-review set the design-specs keys (and the AGENTS.md specs block). A person at a terminal who runs ahub init on a new project with no flag that sets anything and no --yes is asked each setting in turn with its default in brackets (Enter keeps it, a wrong answer asks again, and a third wrong answer ends init with nothing written), sees the plan and answers y/N; N, Ctrl-C and Ctrl-D write nothing. A peer, a live test, a pipe and --dry-run are never asked, and --yes takes the defaults. Executables, secrets, models and permissions stay file edits"],
     ["ahub --live-test [--project <path|id>] <command> [args...]", "user-authorized operational console delegation; ordinary calls retain peer identity; person-authored content refuses"],
     ["ahub help [command]", "this help, or one command's entries; also --help and -h"],
     ["ahub version | --version", "print the installed version"],
@@ -38,7 +39,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub sdlc costs [owner/repo] [--json] [--color=auto|always|never]", "read bounded planner cost metrics for linked merged PRs"],
     ["ahub sdlc metrics [--since <YYYY-MM-DD|ISO time>] [--json] [--color=auto|always|never]", "read SDLC metrics and control band tiers from board history (planner or person; read-only)"],
     ["ahub backlog groom | return <task> <revision> <reason...> [--json] [--color=auto|always|never]", "read grooming findings or return accepted untouched work to backlog (planner/person)"],
-    ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
+    ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts, plus a specs line (errors and stale documents) when the project has design specs"],
     ["ahub status --all [--json] [--color=auto|always|never]", "show every registered project"],
     ["ahub logs [-f]", "person: last 100 hub.log lines (-f starts at 10); conductor: bounded public lines and follow while authority remains"],
     ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models, memory library and memory capture setup (read from `amem setup <tool> --json`, a preview) this project uses, and the runtime capture pruning ledger; warn when the CLI or plugin is older than its running daemon"],
@@ -79,15 +80,15 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "validated settings: conductor set is limited to exact live operational keys; undo/reload and other keys are person only; --preview saves nothing; conductor writes keep the person undo record"],
     ["ahub settings edit <config.local.json|sdlc.toml> (set <path> <json> | remove <path>)... [--reason <text>] [--preview] [--yes] | backups [--json]", "human only: structural config (instances, review, snapshots, approvals, context.gate, research.runners, sdlc.toml mode and required_checks) validated by the hub's own loaders, previewed as a diff and written with a backup; a key that runs code or locates secrets needs its name typed, never --yes"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
-    ["ahub queue list [--peer <id>] [--json] [--full] [--color=auto|always|never]", "inspect durable deliveries; open to any agent as public queue metadata, held bodies stay with the person or conductor"],
+    ["ahub queue list [--peer <id>] [--all] [--json] [--full] [--color=auto|always|never]", "inspect durable deliveries; open to any agent as public queue metadata, held bodies stay with the person or conductor; rows a resolution already settled (a retried parent, a discarded or completed row) are hidden and counted on stderr, --all shows them"],
     ["ahub queue show <delivery-id> [--json] [--color=auto|always|never]", "person or configured conductor: inspect one delivery and revision; agent output uses the public view"],
     ["ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text> [--revision N] [--json] [--color=auto|always|never]", "person or configured conductor: resolve a queued or needs_review delivery; --revision binds the displayed row instead of a fresh show; a queued delivery can be discarded while its peer is busy, and a refusal names its cause"],
-    ["ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes] [--json]", "person or configured conductor: without --yes count one peer's queued (default) deliveries; with --yes discard them all with the reason, one recorded discard each; other peers' queues are untouched"],
+    ["ahub queue discard --peer <id> --reason <text> [--state queued|needs_review|failed] [--yes] [--json]", "person or configured conductor: without --yes count one peer's deliveries; with --yes discard them all with the reason, one recorded discard each. With no --state it takes the peer's queued and unsettled failed deliveries (a failed row a resolution already settled is left alone); --state names exactly one kind, needs_review only that way; other peers' queues are untouched"],
   ]],
   ["Tasks and review", [
     ["ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]", "person or configured conductor: read bounded open issues into deduplicated Backlog; never writes GitHub"],
     ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--handoffs] [--json] [--full] [--color=auto|always|never]", "the task board, one line per task at a terminal width; --full: whole titles and SDLC advice; --ready: proposed tasks with nothing left to wait for; --handoffs: what this project handed to other projects and the last state each reported"],
-    ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--backlog] [--detail <text>]", "put a task on the board; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
+    ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--needs-network] [--needs-worktree] [--backlog] [--detail <text>]", "put a task on the board; --needs-network keeps it away from a peer whose shell has none; --needs-worktree keeps it away from a sandboxed peer, which cannot create the task worktree; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
     ["ahub task handoff --project <root|id> [<class>] <title...> [--path <p>]... [--issue <n>] [--task <n>] [--detail <text>] [--json] [--color=auto|always|never]", "person only: register work that belongs to ANOTHER project that runs agent-hub on that project's board (an ownerless proposal its own roles take from there); the target must be registered and running, nothing is queued; a feature or behavior change first needs a spec issue there (--issue); its state changes show in ahub board --handoffs (an agent that hands off gets them as task messages)"],
     ["ahub backlog list [--json] [--full] [--color=auto|always|never] | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision> [--json] [--color=auto|always|never]", "person only: plan work with a reason; {} records a note-only revision, fields.sdlc sets backlog repo/issue identity and clears old spec acceptance; preserve pins/frozen scope and refuse stale edits; list is by rank (--json: raw listing)"],
     ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision> [--json] [--color=auto|always|never]", "person only, except show (any agent, public metadata): planned UTC millisecond dates and phased scope; ship records a time after approval, never tags or publishes"],

package/src/cli/identity.ts

@@ -29,6 +29,8 @@ export function liveTestRefusal(command: string, args: readonly string[], contex
     || (command === "bench" && args.find(arg => arg !== "--json") === "run") || command === "pet"
     // #691: trusting an untested agent CLI version is the person's consent, never a delegated live-test operation.
     || command === "autonomy"
+    // #1064 T3: a stamp is a person's record that they reviewed a document; no delegation, live-test or otherwise, may write one.
+    || (command === "specs" && args[0] === "stamp")
     || (command === "agents" && !args.every(arg => arg === "--json"));
 }
 
@@ -77,8 +79,9 @@ interface PeerReadForm {
 const publicReadDisplayFlags = ["--json", "--full", "--color=auto", "--color=always", "--color=never"] as const;
 const sdlcReadDisplayFlags = ["--json", "--color=auto", "--color=always", "--color=never"] as const;
 const peerReadForms: Readonly<Record<string, Readonly<Record<string, PeerReadForm>>>> = {
+  specs: { list: { displayFlags: ["--json"] }, check: { valueFlags: ["--base"], displayFlags: ["--json", "--require-fresh"] }, covers: { positional: 2000, minimum: 1, displayFlags: [] } },
   room: { list: { displayFlags: ["--json"] }, status: { positional: 1, displayFlags: ["--json"] } },
-  queue: { list: { valueFlags: ["--peer"], displayFlags: publicReadDisplayFlags } },
+  queue: { list: { valueFlags: ["--peer"], displayFlags: [...publicReadDisplayFlags, "--all"] } },
   roster: { "": { displayFlags: publicReadDisplayFlags } },
   settings: { "": { displayFlags: ["--json"] }, list: { displayFlags: ["--json"] }, get: { positional: 1, minimum: 1, displayFlags: ["--json"] } },
   // #814 renders these reads for people and keeps JSON as an explicit data format.
@@ -198,6 +201,11 @@ export function cliCommandLabel(command: string, args: readonly string[], catalo
   // #601: a campaign id and a contract path are text the person chose, so the audit names the subcommand only.
   if (command === "study") return ["draft", "revise", "approve", "close", "show", "experiments"].includes(args[0] ?? "") ? `study ${args[0]}` : "study";
   if (command === "release") return ["new", "list", "show", "plan", "activate", "freeze", "ship", "drop"].includes(args[0] ?? "") ? `release ${args[0]}` : "release";
+  // #1084: `autonomy`, `deliverables` and `usage` were missing from the table below, so a refusal and its audit line named them "unknown". Operands (a flag value, a task id) never reach the label.
+  if (command === "autonomy") { const sub = args.find(arg => !arg.startsWith("--")); return sub !== undefined && ["on", "off", "status"].includes(sub) ? `autonomy ${sub}` : "autonomy"; }
+  if (command === "usage") return args[0] === "limits" || args[0] === "total" ? `usage ${args[0]}` : "usage";
+  if (command === "deliverables") return "deliverables";
+  if (command === "specs") return ["list", "check", "covers", "stamp"].includes(args[0] ?? "") ? `specs ${args[0]}` : "specs";
   if (!(catalog?.definitionOf(command) ?? definitionOf(command)) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "down", "reset", "doctor", "agents", "source", "broker", "schedule", "intake", "learn", "study"].includes(command)) return "unknown";
   if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench", "agents", "roster", "settings"].includes(command)) {
     const sub = command === "bench" || command === "memory" || command === "goal" ? args.find((arg) => arg !== "--json") : args[0];