@staix/agent-hub 0.12.41 → 0.12.43

package/src/cli/console-state.ts

@@ -16,6 +16,8 @@ export interface PermissionDefault { peer: string; mode: "never-ask"; source: st
 export interface ConsoleEvent { text: string; peer?: string; kind?: string; tone?: Tone }
 export interface SettingsEdit {
   token: number; key?: string; undo: boolean; phase: "value" | "preview" | "reason" | "confirm";
+  /** The existing editor can also be opened by the Peers WIP shortcut. */
+  panel?: 1 | 6;
   text: string; value?: SettingValue; reason?: string; lines?: string[]; confirm?: string; undoDigest?: string;
 }
 export interface ConsoleState {
@@ -38,11 +40,13 @@ export interface ConsoleState {
   autoSelected?: boolean;
   input: string; editing: boolean; history: string[]; historyIndex: number;
   approvals: Approval[]; events: ConsoleEvent[]; peers: Record<string, any>; budget: Record<string, any>;
+  taskWip?: Record<string, { wip: number; wipLimit: number }>;
+  backlogView?: boolean;
   tasks: any[]; tasksKnown?: boolean; taskCounts?: Record<string, number>; queue: any[]; detail?: Detail; detailOffset: number; help: boolean; notice: string; noticeAt?: number; noticeTone?: Tone;
   peerFilter?: string; kindFilter?: string; project?: string;
   taskSelection?: number; queueSelection?: string;
-  actionLock?: { prefix: string[]; id: string; revision: number; state: string; owner?: string; reserved?: string; reviewer?: string; waiting?: boolean };
-  confirm?: { type: "permission"; id: string; option: string; peer: string } | { type: "command"; args: string[]; prompt?: string } | { type: "permission_default"; peer: string; source: string };
+  actionLock?: { prefix: string[]; id: string; revision: number; state: string; owner?: string; reserved?: string; reviewer?: string; waiting?: boolean; syntax?: "planning" | "ownerless-return"; revisionField?: "planningRevision" | "flowRevision" };
+  confirm?: { type: "permission"; id: string; option: string; peer: string } | { type: "command"; args: string[]; prompt?: string; lock?: ConsoleState["actionLock"] } | { type: "permission_default"; peer: string; source: string };
   optionChoice?: string;
   modeChoice?: string;
   permissionDefaults: PermissionDefault[];
@@ -334,10 +338,10 @@ 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", "Home/< first, End/> last", "Enter view", "j/k scroll a view", "w web UI", "o pet window"]],
+  ["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 (outside Peers)", "o pet window"]],
   ["Approvals", ["a allow (then y)", "d deny", "v view", "[ ] select"]],
-  ["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)"]],
+  ["Peers", ["p pause", "r resume", "m permission mode", "w WIP limit", "l make planner (then y)"]],
+  ["Tasks", ["b backlog/open", "n add backlog", "a assign/reserve (then y)", "u unassign (then y)", "r review (in review)", "p pull, e plan (backlog)", "R return to backlog", "c cancel (then y)"]],
   ["Queue", ["r resolve (reason, then y)", "queued=discard, needs_review=retry"]],
   ["Events", ["f peer filter", "g kind filter"]],
   ["Settings", ["6 Settings panel", "e edit", "u undo", "preview, reason, then y"]],
@@ -371,7 +375,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", "ui", "pet"]);
+const COMMANDS = new Set(["status", "board", "task", "backlog", "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;
@@ -391,12 +395,13 @@ 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", "cancel"].includes(args[1] ?? "")) || (args[0] === "queue" && args[1] === "resolve") || (args[0] === "permit" && args[2] !== "deny");
+  return (args[0] === "backlog" && args[1] !== "list") || (args[0] === "task" && args[1] === "propose" && args.includes("--backlog")) || (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] }));
   if (s.panel === 2) return s.approvals;
   if (s.panel === 3) {
+    if (s.backlogView) return s.tasks.filter(t => t.state === "backlog").sort((a, b) => (a.rank ?? Number.MAX_SAFE_INTEGER) - (b.rank ?? Number.MAX_SAFE_INTEGER) || a.id - b.id);
     const states = ["proposed", "in_progress", "in_review", "changes_requested"];
     return s.tasks.filter(t => states.includes(t.state)).sort((a, b) => states.indexOf(a.state) - states.indexOf(b.state));
   }
@@ -430,11 +435,20 @@ export function captureConsoleSelection(s: ConsoleState, byIndex = false): void
 const commandFlag = (args: string[], name: string) => { const at = args.indexOf(name); return at < 0 ? undefined : args[at + 1]; };
 function validateLockedCommand(lock: NonNullable<ConsoleState["actionLock"]>, args: string[]): void {
   const revisions = args.flatMap((arg, index) => arg === "--revision" ? [args[index + 1]] : []);
-  if (args[0] !== lock.prefix[0] || args[1] !== lock.prefix[1] || args[2] !== lock.id || revisions.length !== 1 || revisions[0] !== String(lock.revision)) {
+  const matches = lock.syntax === "planning" ? args[3] === String(lock.revision) : lock.syntax === "ownerless-return" ? args.length === 3 : revisions.length === 1 && revisions[0] === String(lock.revision);
+  if (args[0] !== lock.prefix[0] || args[1] !== lock.prefix[1] || args[2] !== lock.id || !matches) {
     throw new Error("the selected id and revision cannot be edited; start again from the row");
   }
 }
+function validateLockedRow(s: ConsoleState, lock: NonNullable<ConsoleState["actionLock"]>): void {
+  if (!lock.revisionField) return;
+  const row = s.tasks.find(row => String(row.id) === lock.id);
+  // Board rows omit a zero planning revision; flow revisions are always explicit in the console projection.
+  const revision = row && (lock.revisionField === "planningRevision" ? row.planningRevision ?? 0 : row.flowRevision);
+  if (!row || row.state !== lock.state || revision !== lock.revision) throw new Error("the selected task revision changed; reload and start again from the row");
+}
 function lockedCommandPrompt(lock: NonNullable<ConsoleState["actionLock"]>, args: string[]): string {
+  if (lock.prefix[0] === "backlog") return `${lock.prefix[1]} task #${lock.id} at ${lock.revisionField === "planningRevision" ? "planning " : ""}revision ${lock.revision}`;
   if (lock.prefix[0] === "queue") {
     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" : ""}`;
@@ -493,6 +507,9 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
       return done();
     }
     if (key === "y") {
+      if (confirm.type === "command" && confirm.lock) {
+        try { validateLockedRow(s, confirm.lock); } catch (error) { notify(s, (error as Error).message, now); return done(); }
+      }
       if (confirm.type === "command") effects.push({ type: "command", args: confirm.args[0] === "permission" && confirm.args[2] === "never-ask" ? [...confirm.args.filter(arg => arg !== "--yes"), "--yes"] : confirm.args });
       else if (s.approvals.some(a => a.id === confirm.id && allowOptions(a).some(o => o.optionId === confirm.option))) {
         effects.push({ type: "permit", id: confirm.id, option: confirm.option });
@@ -535,15 +552,23 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
         }
         if (lock) {
           validateLockedCommand(lock, args);
+          validateLockedRow(s, lock);
+          if (lock.syntax === "planning" && args.length < (lock.prefix[1] === "plan" ? 6 : 5)) throw new Error("backlog row actions require a reason");
           if (lock.prefix[0] === "task" && !["owner", "reviewer"].includes(commandFlag(args, "--role") ?? "owner")) throw new Error("role must be owner or reviewer");
         }
         s.history = [...s.history, input].slice(-100); s.historyIndex = s.history.length;
-        if (commandNeedsConfirmation(args)) s.confirm = { type: "command", args, ...(lock ? { prompt: lockedCommandPrompt(lock, args) } : {}) };
+        if (commandNeedsConfirmation(args)) s.confirm = { type: "command", args, ...(lock ? { prompt: lockedCommandPrompt(lock, args), ...(lock.revisionField ? { lock } : {}) } : {}) };
         else effects.push({ type: "command", args });
       } catch (error) { notify(s, String((error as Error).message), now); }
     } else if (!key.startsWith("\x1b")) s.input += terminalText(key).replace(/\n/g, "");
     return done();
   }
+  if (s.mode === "panels" && s.panel === 3 && key === "b") {
+    s.backlogView = !s.backlogView; s.selection = 0; s.taskSelection = undefined; s.detail = undefined; s.detailOffset = 0; return done();
+  }
+  if (s.mode === "panels" && s.panel === 3 && key === "n" && s.detail === undefined) {
+    s.input = "backlog add implement "; s.editing = true; return done();
+  }
   if ((key === "n" || key === "P") && attentionKeyBlocked) return done();
   if (key === "q") { effects.push({ type: "exit" }); return done(); }
   if (key === "P" && !s.optionChoice && !s.help) {
@@ -572,9 +597,9 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
       const selected = item.id === undefined ? -1 : rows.findIndex(row => row.id === item.id);
       if (selected >= 0) { s.panel = 4; s.selection = selected; navigated = true; }
     } else if (item.kind === "review" && s.mode === "panels") {
-      const rows = panelRows({ ...s, panel: 3 });
+      const rows = panelRows({ ...s, panel: 3, backlogView: false });
       const selected = rows.findIndex(row => row.id === item.id);
-      if (selected >= 0) { s.panel = 3; s.selection = selected; navigated = true; }
+      if (selected >= 0) { s.panel = 3; s.backlogView = false; s.selection = selected; navigated = true; }
     }
     if (navigated) { captureConsoleSelection(s, true); s.detail = undefined; s.requestDetail = undefined; }
     else {
@@ -592,6 +617,17 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
   // 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).
   if (s.mode === "panels" && (key === "\x1b[C" || key === "\x1b[D") && !s.optionChoice) return switchPanel(s.panel === 6 ? key === "\x1b[C" ? 1 : 5 : (s.panel + (key === "\x1b[C" ? 0 : 3)) % 5 + 1);
+  if (s.mode === "panels" && s.panel === 1 && key === "w") {
+    const peer = selectedPanelRow(s)?.id;
+    if (!peer || s.detail !== undefined) { notify(s, "select a peer row to edit its planner WIP limit", now); return done(); }
+    const wip = s.taskWip?.[peer];
+    if (!wip || s.peers[peer]?.rostered === false) { notify(s, `planner WIP is unavailable for ${peer}`, now); return done(); }
+    const row = s.settingsRows?.find(row => row.key === `tasks.wip_limits.${peer}`);
+    if (!row || s.settingsProblem) { notify(s, s.settingsProblem ?? "WIP setting is unavailable; refresh settings and try again", now); return done(); }
+    const token = (s.settingsSequence ?? 0) + 1; s.settingsSequence = token;
+    s.settingsEdit = { token, panel: 1, key: row.key, undo: false, phase: "value", text: String(wip.wipLimit) };
+    return done();
+  }
   if (s.mode === "panels" && s.panel === 6 && s.detail === undefined && (key === "e" || key === "u")) {
     const row = selectedPanelRow(s);
     if (key === "u" && !s.settingsUndo) { notify(s, "nothing to undo", now); return done(); }
@@ -666,6 +702,16 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     return done();
   }
   if (s.mode === "panels" && item !== undefined && item !== null) {
+    if (s.panel === 3 && (selected.state === "backlog" && ["p", "a", "e"].includes(key) || key === "R" && ["proposed", "in_progress"].includes(selected.state))) {
+      const ownerless = key === "R" && selected.state === "proposed" && !selected.owner;
+      const revision = ownerless ? selected.flowRevision : selected.planningRevision ?? 0;
+      if (!Number.isSafeInteger(revision) || revision < 0) { notify(s, "backlog row actions need a valid revision; refresh the board", now); return done(); }
+      const sub = key === "R" ? "return" : key === "p" ? "pull-ready" : "plan";
+      s.actionLock = { prefix: ["backlog", sub], id: String(item), revision, state: String(selected.state), syntax: ownerless ? "ownerless-return" : "planning", revisionField: ownerless ? "flowRevision" : "planningRevision" };
+      const fields = key === "a" ? { reserved: selected.reserved ?? "" } : { priority: selected.priority ?? null, rank: selected.rank ?? null, deps: selected.deps ?? [] };
+      s.input = ownerless ? `backlog return ${item}` : `backlog ${sub} ${item} ${revision} ${sub === "plan" ? `'${JSON.stringify(fields)}' ` : ""}`;
+      s.editing = true; return done();
+    }
     if (s.panel === 1 && key === "m") {
       const peer = String(item);
       const info = s.peers[peer];
@@ -690,7 +736,7 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
       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.actionLock = { prefix: ["task", "cancel"], id: String(item), revision, state: String(selected.state), ...(selected.state === "backlog" ? { revisionField: "flowRevision" as const } : {}) };
       s.input = `task cancel ${item} --revision ${revision} --reason `; s.editing = true; return done();
     }
     if (s.panel === 3 && (key === "a" || key === "u")) {
@@ -732,7 +778,7 @@ export function activeNotice(s: Pick<ConsoleState, "notice" | "noticeAt">, now =
   return !!s.notice && now - (s.noticeAt ?? now) < NOTICE_MS;
 }
 export const TABLES: Record<number, string[]> = {
-  1: ["PEER", "STATE", "LINK", "Q", "!", "REVIEW", "PAUSE", "QUOTA", "MODEL"],
+  1: ["PEER", "STATE", "LINK", "Q", "!", "WIP", "REVIEW", "PAUSE", "QUOTA", "MODEL"],
   2: ["ID", "PEER", "LEFT", "TITLE"],
   3: ["ID", "STATE", "OWNER", "REVIEWER", "CLASS", "AGE", "TITLE", "STAGE"],
   4: ["ID", "PEER", "STATE", "REV", "AGE"],
@@ -740,11 +786,14 @@ export const TABLES: Record<number, string[]> = {
 };
 const showPermissionModes = (s: ConsoleState) => Object.values(s.peers).some(peer => peer.permissionMode && peer.permissionMode !== "ask");
 const count = (n: unknown) => typeof n === "number" && n ? String(n) : "-";
+const BACKLOG_COLUMNS = ["ID", "PRI", "RESERVED", "DEPS", "CLASS", "AGE", "TITLE"];
+const waitingDeps = (s: ConsoleState, row: any): number[] => (row.deps ?? []).filter((id: number) => !s.tasks.some(task => task.id === id && task.state === "approved"));
 /** One span per column of a panel row; zero counters and unknown values read `-`. */
 export function cells(s: ConsoleState, row: any, selected: boolean, now: number, stages?: Map<number, ProgressStage>): Span[] {
   const id = (text: unknown, tone: Tone | undefined) => span(text, tone && (selected ? "strong" : tone));
   if (s.panel === 1) {
     const b = s.budget[row.id];
+    const wip = s.taskWip?.[row.id];
     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] : "-";
@@ -752,11 +801,16 @@ export function cells(s: ConsoleState, row: any, selected: boolean, now: number,
       ...(showPermissionModes(s) ? [span(row.permissionMode && row.permissionMode !== "ask" ? row.permissionMode : "-", row.permissionMode === "never-ask" ? "attention" : undefined)] : []),
       span(row.pullOnly && definitionOf(row.id)?.attach?.pullOnlyForms?.includes("tui") ? "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),
+      span(wip ? `${wip.wip}/${wip.wipLimit}` : "-", wip && wip.wip >= wip.wipLimit ? "attention" : undefined),
       span(count(row.needsReview), row.needsReview ? "failure" : undefined), span(paused, paused === "-" ? undefined : "attention"),
       span(b?.windows?.length ? b.windows.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%${typeof w.resetsAt === "number" ? ` ${relative(w.resetsAt, now)}` : ""}`).join(", ") : "-"),
       span(row.servedBy ?? row.requestedModel ?? "-")];
   }
   if (s.panel === 2) return [id(row.id, "attention"), span(row.peer, "attention"), span(duration(row.expiresAt - now), "muted"), span(row.title)];
+  if (s.panel === 3 && s.backlogView) {
+    const waits = waitingDeps(s, row);
+    return [id(`#${row.id}`, "info"), span(`${row.priority ?? "-"}/${row.rank ?? "-"}`), span(row.reserved ?? "-"), span(waits.length ? waits.map(id => `#${id}`).join(",") : "ready", waits.length ? "attention" : "success"), span(row.class ?? "-"), span(typeof row.created === "number" ? duration(now - row.created) : "-", "muted"), span(row.pii ? "[pii]" : row.title)];
+  }
   if (s.panel === 3) {
     const last = row.history?.at(-1);
     const at = last?.at ?? row.updated ?? row.created;
@@ -801,20 +855,41 @@ export function table(head: string[], rows: Span[][], columns: number, explicitW
     return { ...cell, text: text + " ".repeat(Math.max(0, widths[i]! - Bun.stringWidth(text)) + (i === head.length - 1 ? 0 : 2)) };
   }));
 }
+/** Keep the status/quota columns visible instead of clipping them behind optional peer metadata. */
+function optionalTable(head: string[], rows: Span[][], columns: number, drop = ["MODEL", "WIP", "PAUSE", "REVIEW", "LINK", "Q", "!", "MODE"]): Span[][] {
+  const cap = Math.max(24, Math.floor(columns / 3));
+  const widths = head.map((name, i) => Math.min(cap, rows.reduce((max, row) => Math.max(max, Bun.stringWidth(flat(row[i]?.text ?? ""))), name.length)));
+  const keep = head.map((_, i) => i);
+  const total = () => keep.reduce((sum, i) => sum + widths[i]!, 0) + 2 * (keep.length - 1);
+  for (const name of drop) {
+    if (total() <= columns - 2) break;
+    const at = keep.findIndex(i => head[i] === name);
+    if (at >= 0) keep.splice(at, 1);
+  }
+  // Very long peer/state/quota values still fit, with their headers intact.
+  while (total() > columns - 2) {
+    const largest = keep.reduce((best, i) => widths[i]! - head[i]!.length > widths[best]! - head[best]!.length ? i : best, keep[0]!);
+    if (widths[largest]! <= head[largest]!.length) break;
+    widths[largest] = widths[largest]! - 1;
+  }
+  return table(keep.map(i => head[i]!), rows.map(row => keep.map(i => row[i]!)), columns, keep.map(i => widths[i]!));
+}
 function taskHints(row: any): string[] {
+  if (row.state === "backlog") return ["p pull", "a reserve", "e plan"];
   if (!["proposed", "in_progress", "in_review", "changes_requested"].includes(row.state)) return [];
   const review = row.state === "in_review";
   const hints = [review ? "a reviewer" : "a assign"];
   if (review ? row.reviewer : row.owner || row.reserved) hints.push("u unassign");
   if (review) hints.push("r review");
+  if (["proposed", "in_progress"].includes(row.state)) hints.push("R return");
   return hints;
 }
 const settingValueText = (value: unknown): string => value === null || value === undefined ? "inherit" : Array.isArray(value) ? value.join(",") : String(value);
 function panelContext(s: ConsoleState, row: any): string[] {
+  if (s.panel === 3) return [...(row ? taskHints(row) : []), ...(row && s.features?.includes("task_cancel") ? ["c cancel"] : []), s.backlogView ? "b open" : "b backlog", "n add"];
   if (!row) return [];
   if (s.panel === 6) return ["e edit", ...(s.settingsUndo ? ["u undo"] : [])];
-  if (s.panel === 1) return ["p pause", "r resume", "m permission mode"];
-  if (s.panel === 3) return [...taskHints(row), ...(s.features?.includes("task_cancel") ? ["c cancel"] : [])];
+  if (s.panel === 1) return ["p pause", "r resume", "m permission mode", "w WIP limit"];
   if (s.panel === 4) return [row.state === "queued" ? "r discard" : "r resolve"];
   return [];
 }
@@ -827,7 +902,14 @@ function hint(s: ConsoleState, columns: number): string {
   if (s.detail !== undefined || s.requestDetail) return [...approvals, "j/k scroll", "Esc back", "? keys", "q quit"].join("  ");
   const rows = panelRows(s); const row = selectedPanelRow(s);
   const text = [...approvals, ...panelContext(s, row), ...(s.panel === 5 ? ["f peer", "g kind"] : []), ...(rows.length ? ["j/k move"] : []), ...(row ? ["Enter view"] : []), "? keys", ": command", "Tab stream", "q quit"].join("  ");
-  return s.panel === 1 && Bun.stringWidth(text) > columns ? text.replace("m permission mode", "m mode").replace("j/k move", "j/k").replace(": command", ": cmd") : text;
+  if (s.panel === 3 && Bun.stringWidth(text) > columns) {
+    const compact = [...panelContext(s, row), ...(rows.length ? ["j/k"] : []), "? keys", "q quit"];
+    if (Bun.stringWidth(compact.join("  ")) > columns) return compact.filter(key => key !== "j/k").join("  ");
+    return compact.join("  ");
+  }
+  if (s.panel !== 1 || Bun.stringWidth(text) <= columns) return text;
+  const compact = text.replace("m permission mode", "m mode").replace("w WIP limit", "w WIP").replace("j/k move", "j/k").replace(": command", ": cmd");
+  return Bun.stringWidth(compact) > columns ? compact.replace("Enter view", "Enter") : compact;
 }
 /** The project, then the tabs: the active one in brackets, pending approvals and held deliveries counted. */
 function header(s: ConsoleState, columns: number): Span[] {
@@ -927,7 +1009,9 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
   if (s.confirm?.type === "permission_default") lines.push(...fieldLines([["default", `${s.confirm.peer} never-ask`], ["source", s.confirm.source], ["bounds", permissionBoundary(s.confirm.peer)], ["decision", "y enables; n cancels for this hub; Esc defers; until then ask"]], columns, now).flat());
   else if (s.settingsEdit) {
     const edit = s.settingsEdit;
-    lines.push(...fieldLines([["setting", edit.key ?? s.settingsUndo ?? "last write"], ["preview", (edit.lines ?? []).join("\n")], ["decision", "Esc cancels; saving needs a reason and explicit y"]], columns, now).flat());
+    const row = s.settingsRows?.find(row => row.key === edit.key);
+    const definition: [string, unknown][] = row ? [["type", row.type], ...(row.min !== undefined || row.max !== undefined ? [["range", `${row.min ?? "-"}..${row.max ?? "-"}`] as [string, unknown]] : []), ["risk", row.risk], ["applies", row.applies]] : [];
+    lines.push(...fieldLines([["setting", edit.key ?? s.settingsUndo ?? "last write"], ...definition, ["preview", (edit.lines ?? []).join("\n")], ["decision", "Esc cancels; saving needs a reason and explicit y"]], columns, now).flat());
   }
   else if (s.help) lines.push(...keyTable(columns, !!s.petEnabled || !!s.petChoices?.length, !!s.petChoices?.length));
   else if (s.detail !== undefined || (s.requestDetail && permission)) {
@@ -935,7 +1019,7 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     lines.push(...detail.slice(Math.min(s.detailOffset, Math.max(0, detail.length - height))));
   }
   else {
-    const data = panelRows(s); const head = s.panel === 1 && showPermissionModes(s) ? ["PEER", "STATE", "MODE", ...TABLES[1]!.slice(2)] : TABLES[s.panel]; const at = selection(s);
+    const data = panelRows(s); const head = s.panel === 3 && s.backlogView ? BACKLOG_COLUMNS : s.panel === 1 && showPermissionModes(s) ? ["PEER", "STATE", "MODE", ...TABLES[1]!.slice(2)] : TABLES[s.panel]; const at = selection(s);
     // Below the Approvals table: the selected request's title, its allow options and deny, one line each. Deny always
     // shows; options that do not fit are counted, rows give way to the rest, and the title gets what is left.
     const [title = [], allow = [], deny = []] = s.panel === 2 && permission ? fieldLines(approvalFields(permission).slice(3), columns, now) : [];
@@ -944,7 +1028,8 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     const tail = [...allow, ...deny];
     const capacity = Math.max(1, s.panel === 2 ? Math.min(Math.floor(height / 2) - 1, height - 3 - tail.length) : height - (s.panel === 3 ? 2 : 1)); const start = Math.max(0, at - capacity + 1);
     const stages = new Map(progress.stages.map(stage => [stage.id, stage]));
-    const rowsOf = head ? table(head, data.map((row, i) => cells(s, row, i === at, now, stages)), columns) : undefined;
+    const cellRows = head ? data.map((row, i) => cells(s, row, i === at, now, stages)) : [];
+    const rowsOf = head ? s.panel === 1 ? optionalTable(head, cellRows, columns) : s.panel === 3 && s.backlogView ? optionalTable(head, cellRows, columns, ["AGE", "CLASS", "DEPS", "PRI"]) : table(head, cellRows, columns) : undefined;
     if (s.panel === 6) {
       const row = selectedPanelRow(s);
       const info = s.settingsProblem ?? (!s.settingsKnown ? "settings loading..." : row?.restartReason ?? row?.note ?? row?.label ?? "Settings");
@@ -955,7 +1040,9 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
         for (const pending of s.retainedConfig) lines.push(fitLine([span(`${pending.key}: ${pending.reason}`, "attention")], columns));
       }
     }
-    if (s.panel === 3) {
+    if (s.panel === 3 && s.backlogView) {
+      lines.push(fitLine([span(s.tasksKnown === false ? "backlog loading..." : `backlog ${data.length}`, s.tasksKnown === false ? "attention" : "info")], columns));
+    } else if (s.panel === 3) {
       const done = progress.total ? Math.floor(progress.counts.approved * 20 / progress.total) : 0;
       const main = s.tasksKnown === false && !progress.total ? "tasks loading..." : `${progress.counts.approved}/${progress.total} approved [${"#".repeat(done)}${".".repeat(20 - done)}] ${progress.total ? Math.floor(progress.counts.approved * 100 / progress.total) : 0}%`;
       const known = s.tasksKnown !== false || progress.total > 0;

package/src/cli/console.ts

@@ -31,7 +31,7 @@ export interface ConsoleOptions {
   /** Explicit delegation inherited only by this console's ahub subprocesses. */
   liveTest?: boolean;
   /** Injected command runner must use argv, closed stdin, and return a cancellation handle. */
-  runCommand?: (args: string[], output: (text: string) => void, done: () => void, columns?: number) => (() => void);
+  runCommand?: (args: string[], output: (text: string) => void, done: (code?: number) => void, columns?: number) => (() => void);
   pollMs?: number;
 }
 /** Exact navigation sequences only (#309, #441); anything else in a multi-character read is a paste. */
@@ -190,7 +190,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       const replies = await Promise.all([
         client.request({ t: "status" }, 3000), client.request({ t: "budget" }, 3000),
         ...(panels ? [client.request({ t: "task", op: "hub_task_list", args: {} }, 3000), client.request({ t: "queue", op: "list" }, 3000), client.request({ t: "task", op: "hub_task_list", args: { ready: true } }, 3000)] : []),
-        ...(panels && state.panel === 6 ? [client.request({ t: "settings_get" }, 3000)] : []),
+        ...(panels && (state.panel === 1 || state.panel === 6) ? [client.request({ t: "settings_get" }, 3000)] : []),
       ]);
       if (!active) return;
       const [status, budget, tasks, queue, ready, settings] = replies;
@@ -210,6 +210,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       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.taskWip = status.status.taskWip ?? {};
         state.attentionFacts = attentionFacts(status.status.attentionItems);
         state.storageBlocked = !!status.status.deliveryError;
         state.recoveryNeed = status.status.recovery ? { id: status.status.recovery.operationId, running: true } : undefined;
@@ -249,7 +250,8 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       try { while (true) { const { value, done } = await reader.read(); if (done) break; output(decoder.decode(value, { stream: true })); } const end = decoder.decode(); if (end) output(end); }
       finally { reader.releaseLock(); }
     };
-    void Promise.all([read(child.stdout), read(child.stderr), child.exited]).then(([, , code]) => { if (code) output(`command exited ${code}`); }).catch(error => output(String(error.message))).finally(finished);
+    let exitCode = 0;
+    void Promise.all([read(child.stdout), read(child.stderr), child.exited]).then(([, , code]) => { exitCode = code; if (code) output(`command exited ${code}`); }).catch(error => { exitCode = 1; output(String(error.message)); }).finally(() => finished(exitCode));
     return () => { child.kill(); };
   });
   const effect = async (action: ConsoleEffect) => {
@@ -257,7 +259,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     if (action.type === "settings_preview") {
       const response = await client.request(action.undo ? { t: "settings_preview", undo: true } : { t: "settings_preview", key: action.key, value: action.value }, 3000);
       const edit = state.settingsEdit;
-      if (!active || state.mode !== "panels" || state.panel !== 6 || !edit || edit.phase !== "preview" || edit.token !== action.token || edit.undo !== action.undo || edit.key !== action.key || (!action.undo && JSON.stringify(edit.value) !== JSON.stringify(action.value))) return;
+      if (!active || state.mode !== "panels" || !edit || state.panel !== (edit.panel ?? 6) || edit.phase !== "preview" || edit.token !== action.token || edit.undo !== action.undo || edit.key !== action.key || (!action.undo && JSON.stringify(edit.value) !== JSON.stringify(action.value))) return;
       if (response.ok === false) { state.settingsEdit = undefined; notice(String(response.error ?? "setting preview refused")); }
       else if (action.undo && (typeof response.key !== "string" || !response.key || response.key.trim() !== response.key || response.key.length > 160 || typeof response.undoDigest !== "string" || !/^[a-f0-9]{64}$/i.test(response.undoDigest))) {
         state.settingsEdit = undefined; notice("undo preview is unavailable or changed; reload settings and review it again");
@@ -299,9 +301,10 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     childRunning = true;
     stream({ text: `> ${action.args.join(" ")}`, kind: "command" });
     try {
+      let diagnostic = "";
       // Output lines sit at column 4, as message bodies do: what a command prints can carry peer text, and columns 0 and 2 are the hub's.
-      const output = (text: string) => { if (active) { stream({ text: terminalText(text).replace(/\t/g, " ").replace(/\n$/, "").replace(/^/gm, "    "), kind: "command" }); draw(); } };
-      cancelChild = run(action.args, output, () => { childRunning = false; cancelChild = undefined; if (active) void refresh(); }, Math.max(1, columns - 4));
+      const output = (text: string) => { if (active) { diagnostic = (diagnostic + terminalText(text)).slice(-2000); stream({ text: terminalText(text).replace(/\t/g, " ").replace(/\n$/, "").replace(/^/gm, "    "), kind: "command" }); draw(); } };
+      cancelChild = run(action.args, output, (code = 0) => { childRunning = false; cancelChild = undefined; if (active) { if (code) notice(diagnostic.trim() || `command exited ${code}`); void refresh(); } }, Math.max(1, columns - 4));
     } catch (error) { childRunning = false; notice(String((error as Error).message)); draw(); }
   };
   const handle = (key: string) => {

package/src/cli/help.ts

@@ -14,6 +14,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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"],
+    ["ahub completion zsh|bash|fish", "print a shell completion script; its candidates come from these help entries"],
   ]],
   ["Daemon and runtime", [
     ["ahub up [--unattended] [--no-console]", "start the daemon; interactive terminals enter console"],
@@ -51,7 +52,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub codex [--print-command] [--unattended] [args...]", "start the Codex adapter and attach the TUI"],
     ["ahub kimi [--print-command] [--mode tui|headless] [--model <alias>]", "default: Kimi's own TUI, pull-only via hub_inbox; no push, steer, watchdog, console approvals or automatic quota handoff. Select headless for ACP"],
     ["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"],
-    ["ahub agy [--print-command | --dry-run] [args...]", "optional Antigravity CLI 1.4.2 TUI in this terminal (roster.agy, default off): pull-only via hub_inbox, implementer/verifier only; native permissions unmanaged, no hub sandbox"],
+    ["ahub agy [--print-command | --dry-run] [args...]", "optional Antigravity CLI 1.4.x TUI (1.4.2 verified) in this terminal (roster.agy, default off): pull-only via hub_inbox, implementer/verifier only; native permissions unmanaged, no hub sandbox"],
     ["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", "start optional Qwen Code 0.25.0 ACP (roster.qwen, default off)"],
     ["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"],
     ["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
@@ -88,7 +89,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub backlog pull|return <id>", "person only: pull backlog into To Do or return ownerless proposed work; --backlog on task propose stages unoffered work"],
     ["ahub task show|escalate <id>", "full task with history (PII text included) / hand it to the next peer in escalate_to"],
     ["ahub task role <id> <role|none>", "person only: change bounded catalog guidance on an open task; routing and authority are unchanged"],
-    ["ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]", "name the owner (default) or reviewer; a task that still waits reserves its owner; --revision refuses stale console actions"],
+    ["ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]", "name the owner (default) or reviewer; a task that still waits reserves its owner; a peer that cannot take it is refused with the reason; --revision refuses stale console actions"],
     ["ahub task unassign <id> [--role owner|reviewer] [--revision N]", "person only: remove the owner/reservation or reviewer without routing a replacement or stopping native work"],
     ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]", "person only: close obsolete work with a reason; retain its history without stopping native work or releasing dependents"],
     ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned [--created <time>]", "your later verdict on an approved task, kept in the research records (research must be on)"],

package/src/cli/identity.ts

@@ -77,7 +77,7 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
   if (native?.cli.authority === "person") return "console";
   if (native || ["pause", "resume"].includes(command)) return "conductor";
   if (command === "board" && args[0] === "import") return "console";
-  if (["help", "version", "--version", "say", "status", "pet", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
+  if (["help", "version", "--version", "completion", "say", "status", "pet", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
   return "console";
 }
 
@@ -86,7 +86,7 @@ export function cliCommandLabel(command: string, args: readonly string[]): strin
   if (command === "backlog") return ["list", "add", "pull", "pull-ready", "split", "return", "plan", "pin", "undo"].includes(args[0] ?? "") ? `backlog ${args[0]}` : "backlog";
   if (command === "board" && args[0] === "import") return "board import";
   if (command === "release") return ["new", "list", "show", "plan", "activate", "freeze", "ship", "drop"].includes(args[0] ?? "") ? `release ${args[0]}` : "release";
-  if (!definitionOf(command) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "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", "reset", "doctor"].includes(command)) return "unknown";
+  if (!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", "reset", "doctor"].includes(command)) return "unknown";
   if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench"].includes(command)) {
     const sub = command === "bench" || command === "memory" || command === "goal" ? args.find((arg) => arg !== "--json") : args[0];
     if (sub && ["propose", "show", "assign", "unassign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "reattach", "setup", "start", "stop", "remove", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "dedupe", "decay", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take"].includes(sub)) return `${command} ${sub}`;

package/src/cli/main.js

@@ -6,4 +6,8 @@ if (!version || !(Number(version[1]) > 1 || (Number(version[1]) === 1 && (Number
   process.exit(1);
 }
 
-await import("./main.ts");
+// Shell completion asks on every Tab: answer from the help entries without loading the CLI (#603).
+if (process.argv[2] === "__complete") {
+  const { completeWords } = await import("./completion.ts");
+  console.log(completeWords(process.argv.slice(process.argv[3] === "--" ? 4 : 3)).join("\n"));
+} else await import("./main.ts");

package/src/cli/main.ts

@@ -73,6 +73,7 @@ import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, label
 import { summarize, summarizeByTask } from "../hub/report.ts";
 import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
 import { pathWarnings } from "../hub/conflicts.ts";
+import { COMPLETION_SHELLS, completionScript } from "./completion.ts";
 import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, LIVE_TEST_PERSON_REFUSAL, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
 import { recordCliAudit, recordDelegatedCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
@@ -765,6 +766,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (!text) fail(`unknown command "${topic}"; run ahub help`);
     console.log(text);
   },
+  completion: () => {
+    const script = completionScript(args[0]);
+    if (args.length !== 1 || !script) fail(`usage: ahub completion ${COMPLETION_SHELLS.join("|")}`);
+    process.stdout.write(script!);
+  },
   "--version": () => console.log(VERSION),
   version: () => console.log(VERSION),
 

package/src/cli/terminal-recovery.ts

@@ -179,6 +179,8 @@ const MAX_WAIT_MS = 10 * 60 * 1000;
 export const MAX_COMMAND_MS = 30_000;
 /** #215: a replacement's readiness is awaited in slices this long, checking between them whether its launcher still runs. */
 const EXIT_SLICE_MS = 5_000;
+/** #599: after the replacement reads idle, its session mapping is re-read this often until the deadline. */
+const MAP_POLL_MS = 1_000;
 const ALLOWED_ENV = ["CODEX_HOME", "CLAUDE_CONFIG_DIR"] as const;
 type AllowedEnvName = (typeof ALLOWED_ENV)[number];
 
@@ -909,16 +911,23 @@ export async function createTerminal(binding: TerminalBinding, options?: Command
       idle = await waitForIdle(replacement, slice(), config);
     }
     if (!idle.satisfied) return { created: true, ready: false, manualRequired: true, blockers: idle.blockers };
-    // An idle terminal may be the login shell the launcher returned to.
-    const launch = await launches();
-    if (launch.gone) return exited("exited");
-    const shown = await showBinding(replacement, config);
-    const identity = identityFrom(shown);
-    const session = sessionFrom(shown);
-    const recorded = launch.live;
     const same = (value: string | undefined) => anySession || value === binding.sessionId;
-    if ((identity !== binding.peer || !same(session)) && !(recorded && (identity === undefined || identity === binding.peer) && (session === undefined || same(session)))) {
-      return { created: true, ready: true, manualRequired: true, blockers: [blocker("ambiguous-create", `created terminal ${createdHandle} cannot be mapped to the original ${binding.peer} session`, binding.peer, createdHandle)] };
+    let session: string | undefined;
+    // An idle terminal may be the login shell the launcher returned to, or a TUI that has not yet recorded its
+    // launch or been identified by Orca (#599): poll until it maps, contradicts, or the deadline passes.
+    for (;;) {
+      const launch = await launches();
+      if (launch.gone) return exited("exited");
+      const shown = await showBinding(replacement, config);
+      const identity = identityFrom(shown);
+      session = sessionFrom(shown);
+      const recorded = launch.live;
+      if ((identity === binding.peer && same(session)) || (recorded && (identity === undefined || identity === binding.peer) && (session === undefined || same(session)))) break;
+      const contradicts = (identity !== undefined && identity !== binding.peer) || (session !== undefined && !same(session));
+      if (contradicts || Date.now() >= deadline) {
+        return { created: true, ready: true, manualRequired: true, blockers: [blocker("ambiguous-create", `created terminal ${createdHandle} cannot be mapped to the original ${binding.peer} session`, binding.peer, createdHandle)] };
+      }
+      await Bun.sleep(Math.max(1, Math.min(MAP_POLL_MS, deadline - Date.now())));
     }
     if (anySession && session) replacement = { ...replacement, sessionId: session };
     return { created: true, ready: true, manualRequired: false, binding: replacement, newBinding: replacement, blockers: [] };