@staix/agent-hub 0.12.30 → 0.12.31

package/src/cli/console-state.ts

@@ -2,6 +2,7 @@ import { consoleNeeds, characterAttentionLine, attentionCommand } from "./attent
 import { CHARACTERS, petFrame, petSize, petFooterRows, type CharacterId, type PetSize, type PetPose } from "../pet/frame.ts";
 import { PEER_PALETTE } from "../ui/peer-palette.ts";
 import { PERMISSION_MODES, permissionBoundary } from "../hub/permission-mode.ts";
+import { PLANNER_PEERS } from "../hub/peer-catalog.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import type { ProgressStage } from "../ui/task-progress.ts";
 import { sanitize } from "../hub/envelope.ts";
@@ -13,9 +14,10 @@ export interface Approval {
 export interface PermissionDefault { peer: string; mode: "never-ask"; source: string }
 export interface ConsoleEvent { text: string; peer?: string; kind?: string; tone?: Tone }
 export interface ConsoleState {
+  features?: readonly string[];
   /** Older embedding callers omit choices and retain the original STAI/off toggle. */
   petChoices?: readonly CharacterId[]; petCharacter?: CharacterId; petSize?: PetSize; petGlyphs?: "ascii" | "blocks";
-  attentionFacts?: { kind: "review" | "offline"; id: number; peer?: string }[];
+  attentionFacts?: { kind: "review" | "offline" | "stall" | "offer"; id: number; peer?: string }[];
   attentionFingerprint?: string;
   petEnabled?: boolean; petBlink?: boolean; attentionMessages?: { id?: string; peer?: string; important: boolean; since?: number }[]; storageBlocked?: boolean; recoveryNeed?: { id?: string; running: boolean; since?: number }; attentionSelection?: number;
   mode: "stream" | "panels"; panel: number; selection: number;
@@ -315,12 +317,15 @@ function approvalFields(a: Approval): [string, unknown][] {
 export function permissionText(a: Pick<Approval, "id" | "peer" | "title" | "options">): string {
   return `  ? ${a.peer} asks permission: ${String(a.title).replace(/\n/g, "\n      | ")}\n    answer with: ahub permit ${a.id} <${a.options.map(o => `${quoted(o.optionId)} (${quoted(o.name)})`).join(", ")}> | deny`;
 }
+/** #441: Home/End as terminals send them, plus `<` and `>` for keyboards without those keys. */
+export const FIRST_KEYS = ["<", "\x1b[H", "\x1bOH", "\x1b[1~", "\x1b[7~"];
+export const LAST_KEYS = [">", "\x1b[F", "\x1bOF", "\x1b[4~", "\x1b[8~"];
 const KEYS: [string, string[]][] = [
   ["Everywhere", ["Tab stream/panels", ": command", "? keys", "Esc back", "q quit"]],
   ["Command", ["Enter run", "Esc cancel", "Up/Down history", "Ctrl-U clear"]],
-  ["Panels", ["1-5 panel", "Left/Right panel", "j/k or Up/Down move", "Enter view", "j/k scroll a view"]],
+  ["Panels", ["1-5 panel", "Left/Right panel", "j/k or Up/Down move", "Home/< first, End/> last", "Enter view", "j/k scroll a view", "w web UI", "o pet window"]],
   ["Approvals", ["a allow (then y)", "d deny", "v view", "[ ] select"]],
-  ["Peers", ["p pause", "r resume", "m permission mode"]],
+  ["Peers", ["p pause", "r resume", "m permission mode", "l make planner (then y)"]],
   ["Tasks", ["a assign/reviewer (then y)", "u unassign (then y)", "r review (in review)"]],
   ["Queue", ["r resolve (reason, then y)", "queued=discard, needs_review=retry"]],
   ["Events", ["f peer filter", "g kind filter"]],
@@ -354,7 +359,7 @@ function bound(s: ConsoleState): ConsoleState {
   if (s.requestDetail && s.requestDetail !== s.approvalId) { s.requestDetail = s.approvalId; s.detailOffset = 0; }
   return s;
 }
-const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "permission", "ask", "remember", "route", "sdlc", "turns", "undo", "check-path", "report"]);
+const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "permission", "ask", "remember", "route", "sdlc", "turns", "undo", "check-path", "report", "ui", "pet"]);
 /** A tiny argv parser, never a shell. Quotes group arguments; backslash escapes one character. */
 export function parseConsoleCommand(input: string): string[] {
   const words: string[] = []; let word = ""; let quote = ""; let escaped = false; let started = false;
@@ -374,7 +379,7 @@ export function parseConsoleCommand(input: string): string[] {
 }
 export function commandNeedsConfirmation(args: string[]): boolean {
   const positional = args.filter(arg => arg !== "--yes");
-  return (positional[0] === "permission" && positional[2] === "never-ask") || (args[0] === "task" && ["assign", "unassign"].includes(args[1] ?? "")) || (args[0] === "queue" && args[1] === "resolve") || (args[0] === "permit" && args[2] !== "deny");
+  return (positional[0] === "permission" && positional[2] === "never-ask") || (args[0] === "task" && ["assign", "unassign", "cancel"].includes(args[1] ?? "")) || (args[0] === "queue" && args[1] === "resolve") || (args[0] === "permit" && args[2] !== "deny");
 }
 export function panelRows(s: ConsoleState): any[] {
   if (s.panel === 1) return Object.entries(s.peers).map(([id, peer]) => ({ id, ...peer, budget: s.budget[id] }));
@@ -386,6 +391,15 @@ export function panelRows(s: ConsoleState): any[] {
   if (s.panel === 4) return s.queue.filter(q => q.state === "needs_review" || q.state === "queued");
   return s.events.filter(e => (!s.peerFilter || e.peer === s.peerFilter) && (!s.kindFilter || e.kind === s.kindFilter));
 }
+/** #441: Events follow the newest row while the selection is on the last one; a row the person moved to stays put. */
+export function appendEvent(s: ConsoleState, event: ConsoleEvent, cap = 1000): void {
+  if (s.panel !== 5) { s.events = [...s.events, event].slice(-cap); return; }
+  const before = panelRows(s), held = before[s.selection], following = !held || s.selection >= before.length - 1;
+  s.events = [...s.events, event].slice(-cap);
+  const rows = panelRows(s);
+  s.selection = following ? Math.max(0, rows.length - 1) : Math.max(0, rows.indexOf(held));
+}
+const newestEvent = (s: ConsoleState) => Math.max(0, panelRows(s).length - 1);
 export const selectedApproval = (s: ConsoleState) => s.approvals.find(a => a.id === s.approvalId);
 /** The selected row: approvals and refreshed Tasks/Queue rows are bound by id, never by a replacement row. */
 const selection = (s: ConsoleState) => {
@@ -412,6 +426,7 @@ function lockedCommandPrompt(lock: NonNullable<ConsoleState["actionLock"]>, args
     const action = commandFlag(args, "--action") ?? "resolve";
     return `${action} delivery ${lock.id} at revision ${lock.revision}${action === "completed" ? "; this asserts external effects" : action === "discard" ? "; no task or native turn is cancelled" : ""}`;
   }
+  if (lock.prefix[1] === "cancel") return `cancel task #${lock.id} at revision ${lock.revision}; native turns and worktrees are retained`;
   const role = commandFlag(args, "--role") ?? "owner";
   if (lock.prefix[1] === "assign") return `assign ${role} on task #${lock.id} at revision ${lock.revision}${lock.waiting && role === "owner" ? " as a reservation until dependencies approve" : ""}`;
   const affected = role === "owner" ? [lock.owner, lock.reserved].filter(Boolean).join(" and ") : lock.reviewer ?? "none";
@@ -530,7 +545,7 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
   }
   if (key === "\t") { s.mode = s.mode === "panels" ? "stream" : "panels"; s.detail = undefined; s.requestDetail = undefined; return done(); }
   if (key === ":") { s.editing = true; return done(); }
-  const switchPanel = (panel: number) => { s.panel = panel; s.selection = 0; s.taskSelection = undefined; s.queueSelection = undefined; s.detail = undefined; s.requestDetail = undefined; return done(); };
+  const switchPanel = (panel: number) => { s.panel = panel; s.selection = panel === 5 ? newestEvent(s) : 0; s.taskSelection = undefined; s.queueSelection = undefined; s.detail = undefined; s.requestDetail = undefined; return done(); };
   if (s.mode === "panels" && /^[1-5]$/.test(key) && !s.optionChoice) return switchPanel(Number(key));
   // Right and Left are the digit of the next or previous tab, wrapping at both ends (#309); the same guards as the
   // digits apply (the confirm, mode-choice, key-table and editing branches above returned already).
@@ -541,6 +556,19 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     return done();
   }
   if (key === "\x1b") { s.detail = undefined; s.requestDetail = undefined; s.help = false; s.optionChoice = undefined; return done(); }
+  // #452: open the project dashboard or the pet window as a person's console command; both return at once.
+  if (s.mode === "panels" && (key === "w" || key === "o") && !s.optionChoice) {
+    effects.push({ type: "command", args: key === "w" ? ["ui"] : ["pet", "--window"] });
+    return done();
+  }
+  if (s.mode === "panels" && (FIRST_KEYS.includes(key) || LAST_KEYS.includes(key))) {
+    const first = FIRST_KEYS.includes(key);
+    if (s.detail !== undefined || s.requestDetail) { if (first) s.detailOffset = 0; return done(); }
+    s.selection = first ? 0 : Math.max(0, panelRows(s).length - 1);
+    if (s.panel === 2) s.approvalId = s.approvals[s.selection]?.id;
+    captureConsoleSelection(s, true);
+    return done();
+  }
   if (s.mode === "panels" && ["j", "k", "\x1b[A", "\x1b[B"].includes(key)) {
     if (s.detail !== undefined || s.requestDetail) { s.detailOffset = Math.max(0, s.detailOffset + (["j", "\x1b[B"].includes(key) ? 1 : -1)); return done(); }
     s.selection = Math.max(0, Math.min(panelRows(s).length - 1, selection(s) + (["j", "\x1b[B"].includes(key) ? 1 : -1)));
@@ -595,9 +623,25 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
       else s.modeChoice = peer;
       return done();
     }
+    // #455: the planner is a setting; the command runs only after y, as a person's terminal command.
+    if (s.panel === 1 && key === "l") {
+      const peer = String(item);
+      if (!(PLANNER_PEERS as readonly string[]).includes(peer)) notify(s, `${peer} cannot plan: the planner is one of ${PLANNER_PEERS.join(", ")}`, now);
+      else if (s.peers[peer]?.planner === "setting") notify(s, `${peer} is already the pinned planner`, now, "attention");
+      else s.confirm = { type: "command", args: ["settings", "set", "planner", peer], prompt: `make ${peer} the planner` };
+      return done();
+    }
     const prefill = s.panel === 1 && key === "p" ? `pause ${item}` : s.panel === 1 && key === "r" ? `resume ${item}` :
       s.panel === 3 && key === "r" && selected.state === "in_review" ? `review ${item} ` : undefined;
     if (prefill) { s.input = prefill; s.editing = true; return done(); }
+    if (s.panel === 3 && key === "c") {
+      if (!s.features?.includes("task_cancel")) { notify(s, "task cancellation requires a newer hub", now); return done(); }
+      const revision = selected.flowRevision;
+      if (!["proposed", "in_progress", "in_review", "changes_requested", "backlog"].includes(selected.state)) return done();
+      if (!Number.isSafeInteger(revision) || revision < 0) { notify(s, "task row actions need flowRevision; upgrade the hub", now); return done(); }
+      s.actionLock = { prefix: ["task", "cancel"], id: String(item), revision, state: String(selected.state) };
+      s.input = `task cancel ${item} --revision ${revision} --reason `; s.editing = true; return done();
+    }
     if (s.panel === 3 && (key === "a" || key === "u")) {
       if (!["proposed", "in_progress", "in_review", "changes_requested"].includes(selected.state)) return done();
       const revision = selected.flowRevision, role = selected.state === "in_review" || key === "u" && !selected.owner && !selected.reserved && selected.reviewer ? "reviewer" : "owner";
@@ -624,7 +668,7 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     const values = [...new Set(s.events.map(e => e[field]).filter((x): x is string => !!x))];
     const next = values[values.indexOf(current ?? "") + 1];
     if (key === "f") s.peerFilter = next; else s.kindFilter = next;
-    s.selection = 0; return done();
+    s.selection = newestEvent(s); return done();
   }
   if (s.mode === "stream" && !key.startsWith("\x1b")) { s.editing = true; s.input = terminalText(key).replace(/\n/g, ""); }
   return done();
@@ -652,7 +696,7 @@ export function cells(s: ConsoleState, row: any, selected: boolean, now: number,
     const paused = b?.paused ? `budget ${relative(b.paused.resetsAt, now)}` : row.paused && typeof row.paused === "object"
       ? `${row.paused.by ?? "paused"}${typeof row.paused.at === "number" ? ` ${duration(now - row.paused.at)}` : ""}`
       : row.paused === "manual" ? "user" : row.paused ? String(row.paused).split(":")[0] : "-";
-    return [id(row.id, row.state === "offline" ? undefined : "info"), span(row.rostered === false ? `${row.state} off roster` : row.state, stateTone(row.state)),
+    return [id(row.planner ? `${row.id} (planner)` : row.id, row.state === "offline" ? undefined : "info"), span(row.rostered === false ? `${row.state} off roster` : row.state, stateTone(row.state)),
       ...(showPermissionModes(s) ? [span(row.permissionMode && row.permissionMode !== "ask" ? row.permissionMode : "-", row.permissionMode === "never-ask" ? "attention" : undefined)] : []),
       span(row.pullOnly && row.id === "kimi" ? "pull-only" : row.toolsOnly ? "tools-only" : row.attached === false ? "detached" : "attached", row.toolsOnly ? "attention" : undefined),
       span(count(row.queued)), span(count(row.queuedImportant), row.queuedImportant ? "attention" : undefined),
@@ -666,9 +710,9 @@ export function cells(s: ConsoleState, row: any, selected: boolean, now: number,
     const at = last?.at ?? row.updated ?? row.created;
     const failed = last?.event === "check failed" || last?.event === "failed";
     const stage = stages?.get(row.id);
-    const meter = stage ? "[" + "#".repeat(stage.stage - (stage.changes ? 1 : 0)) + (stage.changes ? "!" : "") + "-".repeat(4 - stage.stage) + "]" : "[----]";
-    return [id(`#${row.id}`, "info"), span(`${row.state}${failed && row.state !== last.event ? ` ${last.event}` : ""}${row.ready ? " ready" : ""}${stage?.waiting ? " waiting" : ""}`, failed ? "failure" : row.ready || stage?.waiting ? "attention" : stateTone(row.state)),
-      span(row.owner ?? "-"), span(row.reviewer ?? "-"), span(row.profileClass ? `${row.profileClass} (base ${row.class})` : row.class ?? "-"), span(typeof at === "number" ? duration(now - at) : "-", "muted"), span(row.title), span(row.lifecycle ? `${meter} ${row.lifecycle.workflow ? row.lifecycle.workflow + " " : ""}SDLC ${row.lifecycle.stage}${row.lifecycle.definition ? ` (base ${row.lifecycle.definition.base}) / next: ${row.lifecycle.actor} / entry: ${row.lifecycle.entry?.length ? "blocked" : "ready"} / exit: ${row.lifecycle.exit?.length ? "blocked" : "ready"}` : ""}: ${row.lifecycle.next}` : meter, stage?.changes ? "failure" : stateTone(row.state))];
+    const meter = stage?.cancelled ? "[----] cancelled" : stage ? "[" + "#".repeat(stage.stage - (stage.changes ? 1 : 0)) + (stage.changes ? "!" : "") + "-".repeat(4 - stage.stage) + "]" : "[----]";
+    return [id(`#${row.id}`, "info"), span(`${row.state}${s.attentionFacts?.some(fact => fact.kind === "stall" && fact.id === row.id) ? " stalled" : ""}${failed && row.state !== last.event ? ` ${last.event}` : ""}${row.ready ? " ready" : ""}${stage?.waiting ? " waiting" : ""}`, failed ? "failure" : row.ready || stage?.waiting ? "attention" : stateTone(row.state)),
+      span(row.owner ?? "-"), span(row.reviewer ?? "-"), span(row.profileClass ? `${row.profileClass} (base ${row.class})` : row.class ?? "-"), span(typeof at === "number" ? duration(now - at) : "-", "muted"), span(row.title), span(row.lifecycle ? `${meter} ${row.lifecycle.workflow ? row.lifecycle.workflow + " " : ""}SDLC ${row.lifecycle.stage}${row.lifecycle.definition ? ` (base ${row.lifecycle.definition.base}) / next: ${row.lifecycle.actor} / entry: ${row.lifecycle.entry?.length ? "blocked" : "ready"} / exit: ${row.lifecycle.exit?.length ? "blocked" : "ready"}` : ""}: ${row.lifecycle.next}` : meter, stage?.cancelled ? "muted" : stage?.changes ? "failure" : stateTone(row.state))];
   }
   if (s.panel === 4) return [id(row.id, "info"), span(row.peer), span(row.rostered === false ? `${row.state} off roster` : row.state, stateTone(row.state)), span(row.revision ?? "-"), span(typeof row.createdAt === "number" ? duration(now - row.createdAt) : "-", "muted")];
   const [header, ...body] = String(row.text).split("\n");
@@ -715,7 +759,7 @@ function taskHints(row: any): string[] {
 function panelContext(s: ConsoleState, row: any): string[] {
   if (!row) return [];
   if (s.panel === 1) return ["p pause", "r resume", "m permission mode"];
-  if (s.panel === 3) return taskHints(row);
+  if (s.panel === 3) return [...taskHints(row), ...(s.features?.includes("task_cancel") ? ["c cancel"] : [])];
   if (s.panel === 4) return [row.state === "queued" ? "r discard" : "r resolve"];
   return [];
 }

package/src/cli/console.ts

@@ -4,7 +4,7 @@ import { StringDecoder } from "node:string_decoder";
 import type { ControlClient } from "../hub/control-client.ts";
 import { contextLine } from "./status-lines.ts";
 import { renderTailEvent } from "./tail-render.ts";
-import { syncPermissionDefaults, permissionDefaultText, approvalFrom, initialConsoleState, keyTable, notify, paint, permissionText, plural, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, streamTokens, wrapStreamTokens, terminalText, wrap, captureConsoleSelection, selectedPanelRow } from "./console-state.ts";
+import { syncPermissionDefaults, permissionDefaultText, approvalFrom, initialConsoleState, keyTable, notify, paint, permissionText, plural, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, streamTokens, wrapStreamTokens, terminalText, wrap, captureConsoleSelection, selectedPanelRow, appendEvent, FIRST_KEYS, LAST_KEYS } from "./console-state.ts";
 import type { ConsoleEffect, ConsoleEvent, Detail, Tone } from "./console-state.ts";
 import type { BusEvent } from "../hub/bus.ts";
 import { consoleNeeds, attentionFacts } from "./attention.ts";
@@ -34,6 +34,17 @@ export interface ConsoleOptions {
   runCommand?: (args: string[], output: (text: string) => void, done: () => void, columns?: number) => (() => void);
   pollMs?: number;
 }
+/** Exact navigation sequences only (#309, #441); anything else in a multi-character read is a paste. */
+const NAVIGATION = ["\x1b[A", "\x1b[B", "\x1b[C", "\x1b[D", ...FIRST_KEYS, ...LAST_KEYS].filter(key => key.startsWith("\x1b"));
+export function navigationPresses(text: string): string[] | undefined {
+  const keys: string[] = [];
+  for (let at = 0; at < text.length;) {
+    const key = NAVIGATION.find(k => text.startsWith(k, at));
+    if (!key) return undefined;
+    keys.push(key); at += key.length;
+  }
+  return keys.length ? keys : undefined;
+}
 export const RESTORE_CONSOLE = "\x1b[?1049l\x1b[r\x1b[0m\x1b[?25h";
 /** Console-only styling uses event structure; tail text and message bodies are never parsed for meaning. */
 export function eventTone(e: BusEvent): Tone | undefined {
@@ -103,7 +114,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   /** `record: false` is for the console's own prints (the key table, a request viewed again): not events, so not in Events. */
   const stream = (event: ConsoleEvent, record = true) => {
     if (event.kind === "command") event = { ...event, text: terminalText(event.text).replace(/\t/g, " ") };
-    if (record) state.events = [...state.events, { ...event, text: terminalText(event.text) }].slice(-1000);
+    if (record) appendEvent(state, { ...event, text: terminalText(event.text) });
     if (plain) {
       const [header, ...body] = terminalText(event.text).split("\n");
       terminal.write(paint([...(color ? streamTokens(header ?? "", event.tone, event.kind) : [{ text: header ?? "" }]), ...body.map(text => ({ text: "\n" + text }))], color) + "\n");
@@ -183,6 +194,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       const [status, budget, tasks, queue, ready] = replies;
       captureConsoleSelection(state);
       if (status.status?.tasks && status.ok !== false) state.taskCounts = status.status.tasks;
+      if (status.status) state.features = Array.isArray(status.status.features) ? status.status.features : [];
       if (status.status?.peers) state.peers = Object.fromEntries(Object.entries(status.status.peers).map(([peer, value]) => [peer, { ...(value as object), ...status.status.roleInfo?.[peer] }]));
       if (status.status && status.ok !== false) {
         state.attentionFacts = attentionFacts(status.status.attentionItems);
@@ -299,10 +311,11 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       terminal.raw(true);
       removers.push(terminal.onData(text => {
         // A pasted chunk can only edit text, never approve, confirm or run commands. Bracketed-paste delimiters are stripped.
-        // Under the modal key table it does nothing at all. A read holding nothing but arrow sequences is that many
-        // key presses (key repeat, a slow link), not a paste (#309): each arrow reaches the reducer on its own.
-        if (Array.from(text).length > 1 && !["\x1b[A", "\x1b[B", "\x1b[C", "\x1b[D"].includes(text)) {
-          if (/^(?:\x1b\[[ABCD])+$/.test(text)) { for (const key of text.match(/\x1b\[[ABCD]/g)!) handle(key); }
+        // Under the modal key table it does nothing at all. A read holding nothing but arrow or Home/End sequences is
+        // that many key presses (key repeat, a slow link), not a paste (#309, #441): each reaches the reducer on its own.
+        const presses = navigationPresses(text);
+        if (Array.from(text).length > 1 && presses?.length !== 1) {
+          if (presses) { for (const key of presses) handle(key); }
           else {
             state.attentionMessages = []; state.attentionSelection = undefined;
             if (state.help && state.mode === "panels") { draw(); return; }

package/src/cli/identity.ts

@@ -82,6 +82,7 @@ export function cliCommandLabel(command: string, args: readonly string[]): strin
   return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
 }
 
-export function peerCommandRefusal(peer: string, command: string): string {
-  return `${peer} cannot run ahub ${command}; the person runs it in ahub console or a terminal`;
+export function peerCommandRefusal(peer: string, command: string, env: Readonly<Record<string, string | undefined>> = process.env): string {
+  const markers = ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "AGENTHUB_PEER_ID", "CODEX_THREAD_ID"].filter(name => env[name] !== undefined);
+  return `${peer} cannot run ahub ${command}; the person runs it in ahub console or a terminal. Refused because inherited agent markers${markers.length ? ` (${markers.join(", ")})` : ""} identify this shell as an agent. A ! command in an agent session runs as that agent; use a separate terminal outside the agent session`;
 }

package/src/cli/jcode-mcp.ts

@@ -21,7 +21,7 @@ const map = (doc: Document): Document => (doc.mcpServers ?? doc.servers ?? {}) a
 const owned = (entry: unknown, cwd: string): entry is Document => object(entry) && object(entry.env) && entry.env.AGENTHUB_MODE === "tools" && entry.env.AGENTHUB_PEER_ID === "jcode" && entry.env.AGENTHUB_PROJECT_DIR === cwd;
 
 export function jcodeMcpEntry(cwd: string, stateDir: string, bundle: string) {
-  return { command: "bun", args: ["run", bundle], shared: false, env: { AGENTHUB_MODE: "tools", AGENTHUB_PEER_ID: "jcode", AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } };
+  return { command: "bun", args: ["run", bundle], shared: false, env: { AGENTHUB_MODE: "tools", AGENTHUB_DELIVERY_ONLY: "true", AGENTHUB_PEER_ID: "jcode", AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } };
 }
 /** The native loader reads later project files last. Never shadow a foreign definition. */
 function inspect(cwd: string): Document {

package/src/cli/main.ts

@@ -353,6 +353,7 @@ function fail(message: string): never {
 async function taskOp(op: string, a: Record<string, unknown>, throwOnError = false, connection?: ControlClient): Promise<string> {
   const hub = connection ?? await connect();
   try {
+    if (op === "hub_task_cancel" && !hub.features.includes("task_cancel")) fail("this daemon does not support task cancellation; upgrade it first");
     const res = await hub.request({ t: "task", op, args: a }, op === "github_import" ? 60_000 : 30_000);
     if (!res.ok) { if (throwOnError) throw new Error(res.error); audit("refused"); fail(res.error); }
     return res.text;
@@ -1189,6 +1190,12 @@ const commands: Record<string, () => Promise<void> | void> = {
       finally { hub.close(); }
       return;
     }
+    if (sub === "cancel") {
+      const { one, rest: positional } = takeFlags(rest, ["--reason", "--superseded-by", "--revision"], []);
+      const revision = one["--revision"] === undefined ? undefined : Number(one["--revision"]);
+      if (positional.length !== 1 || !/^[1-9]\d*$/.test(positional[0]!) || !one["--reason"]?.trim() || (revision !== undefined && (!/^\d+$/.test(one["--revision"]!) || !Number.isSafeInteger(revision)))) fail("usage: ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]");
+      return console.log(await taskOp("hub_task_cancel", { id: Number(positional[0]), reason: one["--reason"], ...(one["--superseded-by"] === undefined ? {} : { superseded_by: one["--superseded-by"] }), ...(revision === undefined ? {} : { revision }) }));
+    }
     if (sub === "show") return console.log(await taskOp("task_show", { id: rest[0] }));
     if (sub === "escalate") return console.log(await taskOp("task_escalate", { id: rest[0] }));
     if (sub === "assign") {
@@ -1214,7 +1221,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       appendRecords(project.id, [{ schema: RESEARCH_SCHEMA, kind: "label", project: projectKey(project.id), task: id, createdAt: record!.createdAt!, label, at: new Date().toISOString() }]);
       return console.log(`task #${id} (approved ${record!.approvedAt}) labelled ${label} in the research records`);
     }
-    if (sub !== "propose" || rest.length < 1) fail("usage: ahub task propose [<class>] <title...> | show <id> | assign <id> <peer> | unassign <id> | escalate <id>");
+    if (sub !== "propose" || rest.length < 1) fail("usage: ahub task propose [<class>] <title...> | show <id> | assign <id> <peer> | unassign <id> | cancel <id> --reason <text> | escalate <id>");
     // `--class` is the explicit form. A first word that is a class name is still taken as the class (the documented
     // short form), but said out loud: "review the auth module" would otherwise be filed as class review, silently.
     const urgent = rest.includes("--urgent"), backlog = rest.includes("--backlog");

package/src/cli/output.ts

@@ -7,9 +7,12 @@ import { formatReport, formatTaskReport, type Report, type TaskReport } from "..
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  taskStalls?: readonly { task: number; cause: { kind: string; peer?: string; dependency?: number; code: string } }[];
+  pendingTaskOffers?: readonly { task: number; peer: string }[];
+  isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
   memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string };
   taskWip?: Record<string, { wip: number; wipLimit: number }>;
-  pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; budget?: Record<string, any>;
+  pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
   tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[]; switchyard?: string;
 }
 export interface BudgetOutput { budget: Record<string, any>; gate?: number }
@@ -185,14 +188,20 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.roleInfo) data = { ...data, peers: Object.fromEntries(Object.entries(data.peers).map(([peer, value]) => [peer, { ...value, ...data.roleInfo?.[peer] }])) };
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
+  for (const stall of data.taskStalls ?? []) out.push(...detail(`task #${stall.task} stalled`, `${stall.cause.kind}${stall.cause.peer ? ` ${stall.cause.peer}` : ""}${stall.cause.dependency ? ` #${stall.cause.dependency}` : ""}: ${stall.cause.code}; configure the peer, ahub task assign ${stall.task} <peer>, or ahub task cancel ${stall.task} --reason <text>`, columns, "attention"));
+  for (const offer of data.pendingTaskOffers ?? []) out.push(...detail("task offer", `open ${offer.peer}: task #${offer.task} is waiting for it`, columns, "attention"));
   if (data.memoryProfile) {
     const memory = data.memoryProfile;
     const profile = memory.profile === "generation" ? `generation ${memory.generation?.slice(0, 8) ?? "unknown"}` : memory.profile ?? "unbound";
     out.push(...detail("memory", `${profile}; ${memory.state ?? "unknown"}; agent-mem ${memory.agentMemVersion ?? "unknown"}${memory.skippedRows ? `; malformed legacy rows skipped: ${memory.skippedRows}` : ""}${memory.error ? `; ${memory.error}` : ""}`, columns, memory.state === "unavailable" ? "attention" : undefined));
   }
+  if (data.planner) out.push(...detail("planner", `${data.planner.peers?.join(", ") || "nobody"} (${data.planner.source ?? "unknown"})${data.planner.source === "automatic" || data.planner.source === "none" ? "; pin it with ahub settings set planner <peer>" : ""}`, columns, data.planner.source === "none" ? "attention" : undefined));
   if (data.deliveryError) out.push(...detail("delivery storage", `${data.deliveryError}; dispatch is stopped`, columns, "failure"));
   for (const pending of data.permissionDefaults ?? []) out.push(...detail("permission default", `${pending.peer}: never-ask from ${pending.source}, stays ask until a person confirms in ahub console`, columns, "attention"));
   for (const crash of data.crash ?? []) out.push(...detail("crash recovery", crash, columns, "attention"));
+  for (const warning of data.isolatedChecks?.orphans ?? []) out.push(...detail("isolated check warning", warning, columns, "attention"));
+  for (const id of data.isolatedChecks?.unknownReceipts ?? []) out.push(...detail("check receipt", `${id}: unknown; receipt storage unavailable`, columns, "attention"));
+  if (data.isolatedChecks?.maintenanceUnavailable) out.push(...detail("check maintenance", "unavailable; saved run outcomes are unchanged", columns, "attention"));
   const s = initialConsoleState(); s.panel = 1; s.peers = data.peers; s.budget = data.budget ?? {};
   const head = Object.values(data.peers).some(p => p.permissionMode && p.permissionMode !== "ask") ? ["PEER", "STATE", "MODE", ...TABLES[1]!.slice(2)] : [...TABLES[1]!];
   head.push("CONTEXT");
@@ -206,7 +215,9 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     if (p.flowRoles) out.push(...detail(`${id} flow roles`, p.flowRoles.join(", ") || "none", columns));
     if (p.catalogRoles) { out.push(...detail(`${id} catalog roles`, Array.isArray(p.catalogRoles.value) ? p.catalogRoles.value.join(", ") || "none" : "unconfirmed", columns)); if (p.catalogRoles.pending !== undefined) out.push(...detail(`${id} pending roles`, p.catalogRoles.pending.join(", ") || "none", columns, "attention")); }
     if (p.liveAccepted?.length) { settling = true; out.push(...detail("settling", p.liveAccepted.map((v: string) => shortId(v, columns, full)).join(", "), columns, "attention")); }
-    if (p.heldBy) {
+    if (p.heldRows?.length) {
+      for (const row of p.heldRows) out.push(...detail("held", `${id}: needs_review ${shortId(row.id, columns, full)}; from ${row.senders.join(",")}; kind ${row.kinds.join(",")}; age ${duration(Math.max(0, now - row.createdAt))}${row.context ? `; ${row.context}` : ""}; ahub queue show ${row.id}`, columns, "failure"));
+    } else if (p.heldBy) {
       const note = flat(p.holdNote ?? "");
       const command = `ahub queue resolve ${p.heldBy} --action completed|retry|discard --reason <text>`;
       const normalized = note.startsWith(`held by needs_review ${p.heldBy}`)

package/src/cli/upgrade-interactive.ts

@@ -1,3 +1,4 @@
+import { restoreReceiptStatus } from "./upgrade-restore-state.ts";
 import { recoveryArgv } from "../hub/recovery-store.ts";
 import { cancellableWait, nextChoices, publicOperation, type Inspection, type PlannedProject, type RecoveryOperation, type RecoveryPeer, type UpgradePlan } from "./upgrade.ts";
 
@@ -108,7 +109,7 @@ export function operationLines(op: RecoveryOperation, runner: number | "unknown"
   const held = runner === "unknown" ? "; whether a runner holds it cannot be read" : runner ? `; runner ${runner} is working` : op.phase === "running" ? "; no runner holds it (the last one stopped mid-step)" : "";
   const lines = [`${op.plan.kind} to ${op.plan.version}: operation ${op.id}`, `  ${op.phase} at "${stepLabel(op.step)}", updated ${ago(now - op.updatedAt)} ago${held}`];
   for (const p of op.projects) {
-    const effects = Object.entries(p.terminals).map(([key, value]) => value === "pending" || value === "failed" ? `${key} ${value}` : key);
+    const effects = Object.entries(p.terminals).map(([key, value]) => key.startsWith("restored:") ? `${key} ${restoreReceiptStatus(value)}` : value === "pending" || value === "failed" ? `${key} ${value}` : key);
     lines.push(`  ${p.id}  ${p.phase}${effects.length ? `  (${effects.join(", ")})` : ""}${p.restarts?.length ? `  restarts ${p.restarts.length}` : ""}`);
   }
   // The error ends with the commands status would print; the menu below offers them instead.

package/src/cli/upgrade-restore-state.ts

@@ -0,0 +1,133 @@
+import type { TerminalBinding } from "./terminal-recovery.ts";
+
+export type RestoreReceipt =
+  | { state: "pending" }
+  | { state: "waiting"; origin: "pending" | "failed"; binding: TerminalBinding }
+  | { state: "done"; binding: TerminalBinding }
+  | { state: "failed" };
+export interface RestoreEvidence {
+  target: "running" | "stopped" | "changed";
+  launcher: "live" | "gone" | "unknown" | "no-record-yet" | "replaced" | "older-instance";
+  session: "planned" | "other" | "none";
+  allowOther: boolean;
+  /** The original or verified selected terminal when a bare receipt first acquires a binding. */
+  binding?: TerminalBinding;
+}
+export type RestoreAction = "poll" | "settle" | "revalidate" | "block" | "fail" | "create";
+export interface RestoreTransition { next: RestoreReceipt; action: RestoreAction }
+export type RestoreReceiptStatus = "unstarted" | "pending" | "waiting:pending" | "waiting:failed" | "done" | "failed";
+
+function malformed(): never { throw new Error("invalid restore receipt"); }
+const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+function terminalBinding(value: unknown): TerminalBinding {
+  if (!object(value) || typeof value.peer !== "string" || !["codex", "claude", "pi"].includes(value.peer)) malformed();
+  for (const key of ["handle", "incarnationId", "worktreeId", "projectRoot", "sessionId"]) if (!text(value[key])) malformed();
+  for (const key of ["sessionFile", "backend", "model"]) if (value[key] !== undefined && typeof value[key] !== "string") malformed();
+  const launch = value.launch;
+  const validLaunch = (v: unknown) => object(v) && text(v.packageEntrypoint) && text(v.command)
+    && Array.isArray(v.argv) && v.argv.every(arg => typeof arg === "string")
+    && object(v.env) && Object.values(v.env).every(entry => typeof entry === "string");
+  if (!validLaunch(launch) || value.launchMetadata !== undefined && !validLaunch(value.launchMetadata)) malformed();
+  return { ...value, launchMetadata: value.launchMetadata ?? launch } as unknown as TerminalBinding;
+}
+
+/** Decode legacy representations only here. Absence is unstarted, never pending or failed. */
+export function decodeRestoreReceipt(value: unknown): RestoreReceipt | undefined {
+  if (value === undefined) return undefined;
+  if (value === "pending" || value === "failed") return { state: value };
+  if (!object(value)) malformed();
+  if (Object.hasOwn(value, "state")) {
+    const allowed = value.state === "waiting" ? ["state", "origin", "binding"] : value.state === "done" ? ["state", "binding"] : ["state"];
+    if (Object.keys(value).some(key => !allowed.includes(key))) malformed();
+    switch (value.state) {
+      case "pending": case "failed": return { state: value.state };
+      case "waiting": {
+        if (value.origin !== "pending" && value.origin !== "failed") malformed();
+        return { state: "waiting", origin: value.origin, binding: terminalBinding(value.binding) };
+      }
+      case "done": return { state: "done", binding: terminalBinding(value.binding) };
+      default: return malformed();
+    }
+  }
+  if (Object.hasOwn(value, "attachmentReceipt")) malformed();
+  return { state: "done", binding: terminalBinding(value) };
+}
+
+export function restoreReceiptStatus(value: unknown): RestoreReceiptStatus {
+  const receipt = decodeRestoreReceipt(value);
+  return !receipt ? "unstarted" : receipt.state === "waiting" ? `waiting:${receipt.origin}` : receipt.state;
+}
+export function canChooseFresh(value: unknown): boolean {
+  const receipt = decodeRestoreReceipt(value);
+  return receipt?.state === "failed" || receipt?.state === "waiting" && receipt.origin === "failed";
+}
+
+/** Pure decision only: settlement/revalidation must succeed before the runtime persists its proposed next receipt. */
+export function restoreTransition(receipt: RestoreReceipt, evidence: RestoreEvidence): RestoreTransition {
+  const keep = (action: RestoreAction): RestoreTransition => ({ next: receipt, action });
+  if (evidence.target !== "running") return keep("block");
+  // A chosen waiting terminal cannot be replaced by another identity, even if a session has attached meanwhile.
+  if (receipt.state === "waiting" && ["unknown", "replaced", "older-instance"].includes(evidence.launcher)) return keep("block");
+  if (evidence.session === "other" && (!evidence.allowOther || receipt.state === "done")) return keep("block");
+  if (evidence.session === "planned" || evidence.session === "other" && evidence.allowOther) {
+    if (receipt.state === "done") return keep("revalidate");
+    const binding = receipt.state === "waiting" ? receipt.binding : evidence.binding;
+    return binding ? { next: { state: "done", binding }, action: "settle" } : keep("block");
+  }
+  if (receipt.state === "done") return keep("block");
+  if (evidence.launcher === "unknown" || evidence.launcher === "replaced" || evidence.launcher === "older-instance") return keep("block");
+  if (receipt.state === "waiting" && (evidence.launcher === "live" || evidence.launcher === "no-record-yet")) return keep("poll");
+  const origin = receipt.state === "waiting" ? receipt.origin : receipt.state;
+  if (evidence.launcher === "live") return evidence.binding
+    ? { next: { state: "waiting", origin, binding: evidence.binding }, action: "poll" }
+    : keep("block");
+  // Bare pending/failed have no chosen saved terminal: never infer that an absent record is an outstanding bound wait.
+  return { next: { state: "failed" }, action: origin === "pending" ? "fail" : "create" };
+}
+
+/** Checkable compact documentation, enumerated through the same pure decision function. */
+export function renderRestoreTransitionTable(): string {
+  const launch = { packageEntrypoint: "table", command: "table", argv: [], env: {} };
+  const binding: TerminalBinding = { peer: "codex", handle: "selected", incarnationId: "selected", worktreeId: "selected", projectRoot: "table", sessionId: "planned", launch, launchMetadata: launch };
+  const receipts: RestoreReceipt[] = [{ state: "pending" }, { state: "waiting", origin: "pending", binding }, { state: "waiting", origin: "failed", binding }, { state: "done", binding }, { state: "failed" }];
+  const launchers: RestoreEvidence["launcher"][] = ["live", "gone", "unknown", "no-record-yet", "replaced", "older-instance"];
+  const result = (receipt: RestoreReceipt, evidence: RestoreEvidence, unchanged = false) => {
+    const next = restoreTransition(receipt, evidence);
+    const status = restoreReceiptStatus(next.next);
+    return `${next.action} -> ${unchanged && status === restoreReceiptStatus(receipt) ? "unchanged" : status}${canChooseFresh(next.next) && !(unchanged && status === restoreReceiptStatus(receipt)) ? "; fresh" : ""}`;
+  };
+  const table = (title: string, sessions: readonly { session: RestoreEvidence["session"]; allowOther: boolean }[]) => [
+    title,
+    "",
+    `| Receipt | ${launchers.join(" | ")} |`,
+    `|---|${launchers.map(() => "---").join("|")}|`,
+    ...receipts.map(receipt => `| ${restoreReceiptStatus(receipt)} | ${launchers.map(launcher => {
+      const variants = sessions.map(session => ({ session: session.session, result: result(receipt, { target: "running", launcher, ...session, binding }) }));
+      const outcomes = [...new Set(variants.map(value => value.result))];
+      return outcomes.length === 1 ? outcomes[0]! : [...new Set(variants.map(value => `${value.session}: ${value.result}`))].join("; ");
+    }).join(" | ")} |`),
+  ].join("\n");
+  const priority = (targets: readonly RestoreEvidence["target"][], sessions: readonly { session: RestoreEvidence["session"]; allowOther: boolean }[]) => {
+    const outcomes = new Set<string>();
+    for (const receipt of receipts) for (const target of targets) for (const launcher of launchers) for (const session of sessions) {
+      outcomes.add(result(receipt, { target, launcher, ...session, binding }, true));
+    }
+    return [...outcomes].join(" / ");
+  };
+  const allSessions = (["planned", "other", "none"] as const).flatMap(session => [false, true].map(allowOther => ({ session, allowOther })));
+  return [
+    "Cells show action -> next receipt status. Fresh-session eligibility is marked fresh; peer/operation-specific restrictions still apply. Exact terminal revalidation and settlement must succeed before persisting a proposed done receipt.",
+    "",
+    "| Priority condition | Decision |",
+    "|---|---|",
+    `| Target stopped or changed | ${priority(["stopped", "changed"], allSessions)} |`,
+    `| Running target, other session not allowed | ${priority(["running"], [{ session: "other", allowOther: false }])} |`,
+    "| Absent receipt | unstarted; initial launch is handled by the runtime outside this receipt table |",
+    "",
+    table("Running target, no attached session (either allowOther value):", [{ session: "none", allowOther: false }, { session: "none", allowOther: true }]),
+    "",
+    table("Running target, planned session or explicitly allowed other session (different decisions are labeled):", [{ session: "planned", allowOther: false }, { session: "planned", allowOther: true }, { session: "other", allowOther: true }]),
+  ].join("\n");
+}
+export const RESTORE_TRANSITION_TABLE = renderRestoreTransitionTable();