@staix/agent-hub 0.13.0 → 0.15.0

package/src/cli/help.ts

@@ -35,6 +35,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub sdlc train report|configure|cut <release-id> [revision] [json]", "plan a release and freeze its approved scope after resource/quota admission"],
     ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason...>", "assign approved/in-flight work without changing execution"],
     ["ahub sdlc costs [owner/repo]", "read bounded planner cost metrics for linked merged PRs"],
+    ["ahub sdlc metrics [--since <YYYY-MM-DD|ISO time>]", "read SDLC metrics and control band tiers from board history (planner or person; read-only)"],
     ["ahub backlog groom | return <task> <revision> <reason...>", "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 --all [--json] [--color=auto|always|never]", "show every registered project"],
@@ -72,6 +73,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff; remove also deletes the roster key of an instance no longer declared"],
     ["ahub settings [list] [--json] | get <key> [--json]", "human only: the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
     ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "human only: change or reload validated settings, written to .agenthub/config.local.json or routing.local.toml (never a tracked file); --preview shows the effect and saves nothing; undo puts back the last write"],
+    ["ahub 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, 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] [--color=auto|always|never]", "inspect durable deliveries"],
     ["ahub queue show <delivery-id> [--json] [--color=auto|always|never]", "inspect one delivery and revision"],
@@ -80,9 +82,9 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ]],
   ["Tasks and review", [
     ["ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]", "person only: read bounded open issues into deduplicated Backlog; never writes GitHub"],
-    ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--json] [--full] [--color=auto|always|never]", "the task board; --ready: proposed tasks with nothing left to wait for"],
+    ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--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"],
     ["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 backlog list | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision>", "person only: stage and plan work, preserve pins/frozen scope and refuse stale edits"],
+    ["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>", "person only: stage and plan work, preserve pins/frozen scope and refuse stale edits; list is a table by rank (--json: the raw listing)"],
     ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision>", "person only: planned UTC millisecond dates and phased scope; ship records a time after approval, never tags or publishes"],
     ["ahub backlog split <id> <revision> <parts-json> <reason...>", "person only: stage2..8 child prerequisites; original task retains integration, undo refuses used or changed children"],
     ["ahub backlog pull-ready <id> <revision> <reason...>", "person only: reserve an eligible WIP slot before routing; pending unowned work can be undone"],
@@ -95,7 +97,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned [--created <time>]", "your later verdict on an approved task, kept in the research records (research must be on)"],
     ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>] [--findings <json>]", "give a review verdict on a task; the person can do the same in ahub console: Tasks, select the task, r, then a (approve) or c (request changes, with a note)"],
     ["ahub review brief <id>", "print the review brief of a task's commit: reviewable and excluded files, rules, coverage to account for"],
-    ["ahub route explain <id>", "why a task went where it went, its reserved owner included"],
+    ["ahub route explain <id>", "why a task went where it went, its reserved owner and the planner walk included"],
     ["ahub route explain --class <c> <title...>", "what would happen to such a task now"],
     ["ahub ask [--remember] <question...>", "answer from the task board, shared memory and this run's log, with the ids it rests on"],
     ["ahub remember <text...>", "save a note to the memory all agents share"],
@@ -142,7 +144,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ]],
   ["Dashboard", [
     ["ahub ui [--no-open]", "open the local dashboard with configured attention character (or print its one-time link)"],
-    ["ahub ui --settings [--no-open]", "human only: open it with a settings session, which for 15 minutes may change permission modes, routing and start settings"],
+    ["ahub ui --settings [--no-open]", "human only: open it with a settings session, which for 15 minutes may change permission modes, routing, start settings and structural config"],
     ["ahub ui --all [--no-open]", "open the unified project dashboard"],
     ["ahub ui --all --stop", "stop only the dashboard manager"],
     ["ahub manager", "internal: the dashboard manager process that ahub ui --all starts"],

package/src/cli/launch.ts

@@ -30,10 +30,14 @@ export function instanceLaunchArguments(command: string, raw: readonly string[],
     const declaration = instances && Object.hasOwn(instances, id) ? instances[id] : undefined;
     if (!declaration || declaration.kind !== command || !definitionOf(id, instances)) throw new Error("--as must name a declared instance of this command's native kind");
     // #223: a headless reviewer is started by the hub, never from this terminal.
-    hubStarted = definitionOf(id, instances) === definitionOf(command)?.reviewerVariant;
+    const runtime = definitionOf(id, instances), base = definitionOf(command);
+    hubStarted = runtime === base?.reviewerVariant || runtime === base?.headlessVariant;
     instance = id;
   }
-  if (hubStarted && args.some(arg => arg !== "--print-command" && arg !== "--dry-run")) throw new Error(`${instance} is a headless reviewer the hub runs per review: ahub ${command} --as ${instance} takes no launch arguments`);
+  if (hubStarted && args.some(arg => arg !== "--print-command" && arg !== "--dry-run")) {
+    const writer = definitionOf(instance!, instances) === definitionOf(command)?.headlessVariant;
+    throw new Error(`${instance} is a headless ${writer ? "implementer the hub runs per task" : "reviewer the hub runs per review"}: ahub ${command} --as ${instance} takes no launch arguments`);
+  }
   return { ...(instance ? { instance } : {}), args, ...(hubStarted ? { hubStarted: true as const } : {}) };
 }
 
@@ -108,6 +112,8 @@ export interface ClaudeLaunchRecord extends Record<string, unknown> {
   instanceId: string; launchId: string; settingsFile?: string; launcherPid: number; launcherSignature?: string;
   /** A claude-<name> instance (#450 I3); absent for the builtin claude peer, whose file keeps its original name. */
   peer?: string;
+  /** Validated terminal instance root; absent for legacy/canonical launches. */
+  executionCwd?: string;
 }
 
 export interface ClaudeLaunchPublication { recorded: boolean; warning?: string; }
@@ -172,10 +178,10 @@ export function recordClaudeLaunch(stateDir: string, record: ClaudeLaunchRecord)
 
 function sameClaudeLaunch(left: ClaudeLaunchRecord, right: ClaudeLaunchRecord): boolean {
   return left.instanceId === right.instanceId && left.launchId === right.launchId && left.settingsFile === right.settingsFile
-    && left.launcherPid === right.launcherPid && left.launcherSignature === right.launcherSignature;
+    && left.launcherPid === right.launcherPid && left.launcherSignature === right.launcherSignature && left.executionCwd === right.executionCwd;
 }
 function nativeAttestationPath(stateDir: string, launch: ClaudeLaunchRecord): string {
-  const hash = createHash("sha256").update(JSON.stringify([launch.instanceId, launch.launchId, launch.settingsFile, launch.launcherPid, launch.launcherSignature])).digest("hex");
+  const hash = createHash("sha256").update(JSON.stringify([launch.instanceId, launch.launchId, launch.settingsFile, launch.launcherPid, launch.launcherSignature, ...(launch.executionCwd ? [launch.executionCwd] : [])])).digest("hex");
   return join(stateDir, `claude-native-${hash}.json`);
 }
 function privateClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): { file: string; stat: ReturnType<typeof lstatSync>; record: ClaudeLaunchRecord } | undefined {

package/src/cli/main.ts

@@ -18,6 +18,7 @@ import { matchesPolicy } from "../hub/path-policy.ts";
 import { projectedDiff } from "../hub/projected-diff.ts";
 import { TextProjections } from "../hub/text-projection.ts";
 import { terminalText } from "./console-state.ts";
+import { parseSettingsEditArgs, runSettingsEdit, SETTINGS_EDIT_USAGE } from "./settings-edit.ts";
 import { petView, readPet, renderPet } from "./pet.ts";
 import { startPetWindow, closePetWindow } from "../pet/window.ts";
 import { loadPetConfig, savePetPalette } from "./pet-config.ts";
@@ -36,7 +37,7 @@ import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
-import { ControlClient, readControl } from "../hub/control-client.ts";
+import { retryLaunchConnect, ControlClient, readControl } from "../hub/control-client.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { factsHook } from "./facts-hook.ts";
 import { hubHome, projectContext, projectRoot, realPath } from "../hub/project.ts";
@@ -89,7 +90,7 @@ import { agentShellCause, classifyPeerCommand, cliCommandLabel, detectCliIdentit
 import { recordCliAudit, recordDelegatedCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
-import { outputWidth, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
+import { outputWidth, renderRoster, renderStatus, renderBoard, renderBacklog, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
 import { renderHelp, configuredAcpHelp } from "./help.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
@@ -274,13 +275,15 @@ function printOutput(lines: Span[][], color: boolean): void {
 }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
 const lifecycle = { inspectProject, startProject, stopProject };
-const connect = async () => {
+const connect = async (timeoutMs = 3000) => {
   assertDelegatedAuditConsumer();
   if (delegatedAuditHub && !delegatedConnectionTaken) { delegatedConnectionTaken = true; return delegatedAuditHub; }
   return ControlClient.connect(stateDir, identity.role === "tools" ? { role: "tools", peer: identity.peer, projectRoot: cwd }
-    : { role: "console", projectRoot: cwd, ...(delegatedAuditHub ? { instanceId: delegatedAuditHub.instanceId } : {}) });
+    : { role: "console", projectRoot: cwd, ...(delegatedAuditHub ? { instanceId: delegatedAuditHub.instanceId } : {}) }, timeoutMs);
 };
 
+const connectLaunch = () => retryLaunchConnect(connect, () => console.error("hub busy, retrying"));
+
 function registeredProject(): Project {
   const registry = new Registry();
   try { return registry.register(cwd, stateDir); }
@@ -943,7 +946,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     // Preserve the original guard before native effects; previews remain read-only and precede this guard.
     if (entry.lifecycleAdmission && !args.includes("--print-command") && !args.includes("--dry-run")) assertLifecycleAvailable();
     const nativeConnect = async () => {
-      const hub = await connect();
+      const hub = await connectLaunch();
       try { if (selectedInstance) { requirePeerInstances(hub.features); requireActiveInstance((await hub.request({ t: "status" })).status, selectedInstance); } return hub; }
       catch (error) { hub.close(); throw error; }
     };
@@ -955,7 +958,10 @@ const commands: Record<string, () => Promise<void> | void> = {
       projectConfig, connect: nativeConnect, fail,
       exec: (bin, argv, tool) => exec(bin, argv, tool, context.executionCwd),
       execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, selectedInstance ?? entry.command, context.executionCwd), takeFlags,
-      helpers: { launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, prepareTerminalLaunch, registerTerminalLaunch, recoveryLock, processSignature,
+      helpers: { resolveExecutionCwd: peer => {
+        const current = readInstanceRoleConfig(cwd);
+        return resolveInstanceExecutionCwd(cwd, peer, current.instances, effectiveInstanceRoles(peer, current.instances, current.roles, current.catalog), current.catalog);
+      }, launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, prepareTerminalLaunch, registerTerminalLaunch, recoveryLock, processSignature,
         buildLaunch, claudeObservationHooks, recordClaudeLaunch, cleanupStaleClaudeSettings, cleanupClaudeSettings,
         nativeLaunchEnv, runClaudeLaunch, childEnv, qwenSessionId, configureJcodeMcp, configureKimiMcp,
         buildKimiTuiLaunch, startModeOf },
@@ -1141,7 +1147,15 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   backlog: async () => {
     const [sub, id, revision, value, ...reason] = args;
-    if (sub === "list" && args.length === 1) return console.log(await taskOp("hub_backlog_list", {}));
+    if (sub === "list" && outputArguments().length === 1) {
+      // #399: a table by default; --json prints the hub's listing unchanged, and a refusal is printed as it came.
+      const options = outputOptions(), raw = await taskOp("hub_backlog_list", {});
+      if (options.json) return console.log(raw);
+      let cards: unknown;
+      try { cards = JSON.parse(raw); } catch { return console.log(raw); }
+      if (!Array.isArray(cards)) return console.log(raw);
+      return printOutput(renderBacklog(cards, options.columns, Date.now(), options.full), options.color);
+    }
     if (sub === "groom" && args.length === 1) return console.log(await taskOp("hub_planner_groom", {}));
     if (["return", "return-untouched"].includes(sub ?? "") && /^[1-9]\d*$/.test(id ?? "") && /^\d+$/.test(revision ?? "") && args.length >= 4) {
       return console.log(await taskOp("hub_backlog_return_untouched", { id: Number(id), revision: Number(revision), reason: args.slice(3).join(" ") }));
@@ -1295,6 +1309,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (args.length > 2) fail("usage: ahub sdlc costs [owner/repository]");
       return console.log(await taskOp("hub_sdlc_costs", { ...(args[1] ? { repo: args[1] } : {}) }));
     }
+    if (sub === "metrics") {
+      const flags = takeFlags(args.slice(1), ["--since"], []);
+      if (flags.rest.length) fail("usage: ahub sdlc metrics [--since <YYYY-MM-DD|ISO time>]");
+      return console.log(await taskOp("hub_sdlc_metrics", { ...(flags.one["--since"] !== undefined ? { since: flags.one["--since"] } : {}) }));
+    }
     if (sub === "plan-review") {
       const revision = Number(args[2]);
       if (!Number.isSafeInteger(id) || id! <= 0 || !Number.isSafeInteger(revision) || revision < 0 || args.length < 4) fail("usage: ahub sdlc plan-review <task> <revision> <reason...>");
@@ -1504,7 +1523,31 @@ const commands: Record<string, () => Promise<void> | void> = {
     } finally { hub.close(); }
   },
   settings: async () => {
-    const usage = "usage: ahub settings [list] [--json] | get <key> [--json] | set <key> <value|inherit> [--yes] [--preview] | undo | reload";
+    // #689: structural config edits (instances, review, snapshots, approvals, context.gate, sdlc.toml) and their backups. The hub validates and writes.
+    if (args[0] === "edit" || args[0] === "backups") {
+      // A command line the parser refuses never reaches the hub, not even as a connection.
+      const early = args[0] === "backups" ? (args.length > 2 || (args[1] !== undefined && args[1] !== "--json") ? SETTINGS_EDIT_USAGE : undefined) : (() => { const parsed = parseSettingsEditArgs(args.slice(1)); return typeof parsed === "string" ? parsed : undefined; })();
+      if (early) fail(early);
+      const hub = await connect();
+      try {
+        const rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+        const usage = await runSettingsEdit(args, {
+          request: async message => {
+            const reply = await hub.request(message, 35_000);
+            if (reply.ok !== true) {
+              const error = String(reply.error ?? "config edit refused");
+              fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "config_edit/i.test(error) ? `${error}; upgrade and restart the running hub to use ahub settings edit` : error);
+            }
+            return reply;
+          },
+          ask: async prompt => { if (!rl) return null; try { return await rl.question(prompt); } catch { return null; } },
+          print: line => console.log(terminalText(line)),
+        }).finally(() => rl?.close());
+        if (usage) fail(usage);
+      } finally { hub.close(); }
+      return;
+    }
+    const usage = "usage: ahub settings [list] [--json] | get <key> [--json] | set <key> <value|inherit> [--yes] [--preview] | undo | reload | edit <file> ... | backups";
     const flags = args.filter((arg) => arg.startsWith("--")), [sub = "list", key, text, ...extra] = args.filter((arg) => !arg.startsWith("--"));
     const allowed: Record<string, string[]> = { list: ["--json"], get: ["--json"], set: ["--yes", "--preview", "--now"], undo: [], reload: [] };
     if (!Object.hasOwn(allowed, sub) || flags.some((flag) => !allowed[sub]!.includes(flag)) || extra.length) fail(usage);
@@ -2249,7 +2292,7 @@ async function runConductorCommand(): Promise<void> {
 const runConfigured = configuredCommand ? async () => {
   const selection = parseConfiguredAcpArguments(cmd, args, projectCatalog, declaredInstances);
   if (!selection.preview) assertLifecycleAvailable();
-  await runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, connect, print: text => console.log(text), operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  await runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, connect: connectLaunch, print: text => console.log(text), operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
 } : undefined;
 const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : (Object.hasOwn(commands, cmd) ? commands[cmd] : undefined) ?? runConfigured ?? (() => fail(`unknown command "${cmd}"; run ahub help`));
 try {

package/src/cli/output.ts

@@ -248,6 +248,8 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     if (p.pullOnly && definitionOf(id)?.attach?.pullOnlyForms?.includes("tui")) out.push(...detail(`${id} last read`, typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never", columns, "muted"));
     const actionPolicy = data.actionPolicyInfo?.[id];
     if (actionPolicy?.note) out.push(...detail(`${id} action policy`, actionPolicy.note, columns, actionPolicy.enforceable ? "muted" : "attention"));
+    if (typeof p.reviewerUnavailable === "string" && p.reviewerUnavailable) out.push(...detail("reviewer", flat(p.reviewerUnavailable), columns, "failure")); // #722: the cause class, never a path
+    if (p.ownerIsolationNote) out.push(...detail("owner isolation", p.ownerIsolationNote, columns, "attention"));
     if (p.permissionNote) out.push(...detail("permission", p.permissionNote, columns, "muted"));
     if (typeof p.statusNotice?.message === "string" && p.statusNotice.message) out.push(...detail("status notice", p.statusNotice.message, columns, "attention"));
     if (p.requestedModel && p.servedBy && p.requestedModel !== p.servedBy) out.push(...detail("requested model", p.requestedModel, columns));
@@ -268,10 +270,82 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (counts) out.push([], ...lines(`TASKS  ${counts} (ahub board)`, columns));
   return out;
 }
-export function renderBoard(tasks: any[], columns?: number, now = Date.now(), _full = false, allTasks: any[] | null = tasks): Span[][] {
+// #724: short next-step codes for the compact board, keyed on the blocker texts of src/hub/sdlc.ts; the full advice stays in --full and ahub task show.
+const STAGE_CODES: [string, string][] = [["issue identity missing", "issue?"], ["PR identity missing", "PR?"], ["PR is not open", "PR closed"], ["current PR evidence unknown", "PR state?"],
+  ["required check", "CI?"], ["local gate", "gate?"], ["current head has not been reviewed", "review?"], ["GitHub review approval", "approval?"], ["review requests", "requests?"],
+  ["review threads", "threads?"], ["open important review findings", "findings"], ["person may inspect merge readiness", "ready"]];
+export function stageCode(next: string): string {
+  const known = STAGE_CODES.find(([prefix]) => next.startsWith(prefix));
+  return known ? known[1] : width(next) <= 12 ? next : characters(next).slice(0, 9).join("") + "...";
+}
+const BOARD_LEGEND = "STAGE: [#---] SDLC progress, stage: next step. issue? no issue, PR? no PR, CI? checks, review? not reviewed, threads? open threads. Full advice: ahub board --full.";
+const ellipsis = (text: string, room: number) => width(text) <= room ? text : room <= 3 ? ".".repeat(Math.max(0, room)) : (() => { let out = ""; for (const unit of characters(text)) { if (width(out + unit) > room - 3) break; out += unit; } return out + "..."; })();
+/**
+ * #399: `ahub backlog list` as a table: one line per card, by rank (unranked last) then id. With a width, TITLE goes last and is
+ * cut like the compact board, and AGE then CLASS give way first on a narrow terminal; without one (piped) or with full, titles are whole.
+ */
+export function renderBacklog(cards: any[], columns?: number, now = Date.now(), full = false): Span[][] {
+  if (!cards.length) return [[span("no backlog cards")]];
+  const sorted = [...cards].sort((a, b) => (typeof a.rank === "number" ? a.rank : Infinity) - (typeof b.rank === "number" ? b.rank : Infinity) || a.id - b.id);
+  let names = ["RANK", "ID", "PRI", "RESERVED", "AFTER", "CLASS", "AGE", "TITLE"];
+  let table: OutputCell[][] = sorted.map(card => {
+    const deps: number[] = Array.isArray(card.deps) ? card.deps : [];
+    return [span(typeof card.rank === "number" ? card.rank : "-", "muted", true), span(`#${card.id}`, "info", true), span(typeof card.priority === "number" ? `P${card.priority}` : "-", undefined, true),
+      span(card.reserved ?? "-", peerTone(card.reserved ?? ""), true), span(deps.length ? (full || columns === undefined ? deps.map(id => `#${id}`).join(",") : `#${deps[0]}${deps.length > 1 ? `,+${deps.length - 1}` : ""}`) : "-", undefined, true), span(card.class ?? "-", undefined, true),
+      span(typeof card.created === "number" ? duration(now - card.created) : "-", "muted", true), span(flat(card.title))];
+  });
+  if (!full && columns !== undefined) {
+    const drop = (name: string) => { const at = names.indexOf(name); if (at < 0) return; names = names.filter((_, i) => i !== at); table = table.map(row => row.filter((_, i) => i !== at)); };
+    const room = () => columns - names.reduce((sum, name, i) => name === "TITLE" ? sum : sum + Math.max(width(name), ...table.map(row => width(flat(row[i]!.text)))), 0) - 2 * (names.length - 1);
+    const want = Math.min(30, Math.max(...table.map(row => width(row[row.length - 1]!.text))));
+    for (const name of ["AGE", "CLASS", "PRI"]) if (room() < want) drop(name);
+    const titleRoom = Math.max(5, room());
+    table = table.map(row => [...row.slice(0, -1), { ...row[row.length - 1]!, text: ellipsis(row[row.length - 1]!.text, titleRoom) }]);
+  }
+  const owners = new Map<string, number>();
+  for (const card of sorted) owners.set(card.reserved ?? "unreserved", (owners.get(card.reserved ?? "unreserved") ?? 0) + 1);
+  const summary = `${plural(sorted.length, "backlog card")}; reserved: ${[...owners].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([owner, n]) => `${owner} ${n}`).join(", ")}`;
+  return [...rows(names, table, columns), [], ...lines(summary, columns)];
+}
+/** #724: one line per task. TITLE goes last and is cut to the room left; at a narrow width REVIEWER, CLASS and AGE give way first. */
+function compactBoard(tasks: any[], data: OutputCell[][], columns: number, staged: boolean): Span[][] {
+  const head = ["ID", "STATE", "OWNER", "REVIEWER", "CLASS", "AGE", "AFTER", ...(staged ? ["STAGE"] : []), "TITLE"];
+  let table = tasks.map((task, i) => {
+    const row = data[i]!, deps: number[] = task.deps ?? [];
+    const after = deps.length ? `#${deps[0]}${deps.length > 1 ? `,+${deps.length - 1}` : ""}` : "-";
+    const meter = /^\[[^\]]*\](?: cancelled)?/.exec(row[7]?.text ?? "")?.[0] ?? "[----]";
+    const stage = task.lifecycle ? `${meter} ${task.lifecycle.stage}: ${stageCode(String(task.lifecycle.next ?? ""))}` : meter;
+    const short = task.lifecycle ? `${meter} ${stageCode(String(task.lifecycle.next ?? ""))}` : meter;
+    return [row[0]!, row[1]!, row[2]!, row[3]!, row[4]!, row[5]!, span(after, undefined, true), ...(staged ? [{ ...span(stage, row[7]!.tone, true), short }] : []), span(flat(task.title))];
+  });
+  let names = [...head];
+  const drop = (name: string) => { const at = names.indexOf(name); if (at < 0) return; names = names.filter((_, i) => i !== at); table = table.map(row => row.filter((_, i) => i !== at)); };
+  for (const name of [...names]) if (name !== "TITLE" && table.every(row => flat(row[names.indexOf(name)]?.text) === "-")) drop(name);
+  const room = () => { const t = names.indexOf("TITLE"); return columns - names.reduce((sum, name, i) => i === t ? sum : sum + Math.max(width(name), ...table.map(row => width(flat(row[i]!.text)))), 0) - 2 * (names.length - 1); };
+  const want = Math.min(30, Math.max(...table.map(row => width(row[row.length - 1]!.text))));
+  for (const name of ["REVIEWER", "CLASS", "AGE", "STAGE"]) if (room() < want) {
+    // STAGE is never dropped: it falls back to the meter and the code, the stage name being the meter's position.
+    if (name !== "STAGE") drop(name);
+    else { const at = names.indexOf("STAGE"); if (at >= 0) table = table.map(row => row.map((cell, i) => i === at ? { ...cell, text: (cell as OutputCell & { short?: string }).short ?? cell.text } : cell)); }
+  }
+  // Still too narrow (a long instance id as OWNER): AFTER gives way, then OWNER is cut, so the row never becomes linked bands.
+  if (room() < 8) drop("AFTER");
+  const owner = names.indexOf("OWNER");
+  if (room() < 8 && owner >= 0) { const cut = Math.max(5, Math.max(...table.map(row => width(flat(row[owner]!.text)))) - (8 - room())); table = table.map(row => row.map((cell, i) => i === owner ? { ...cell, text: ellipsis(flat(cell.text), cut) } : cell)); }
+  const titleRoom = Math.max(5, room());
+  // A PII row keeps its whole "ahub task show" hint when 8 columns of title remain; the cut title is never wrapped.
+  table = table.map((row, i) => { const pii = `  (ahub task show ${tasks[i].id})`, hint = tasks[i].signals?.includes("pii") && titleRoom - width(pii) >= 8 ? pii : ""; return [...row.slice(0, -1), { ...row[row.length - 1]!, text: ellipsis(row[row.length - 1]!.text, Math.max(4, titleRoom - width(hint))) + hint }]; });
+  return rows(names, table, columns);
+}
+export function renderBoard(tasks: any[], columns?: number, now = Date.now(), full = false, allTasks: any[] | null = tasks): Span[][] {
   if (!tasks.length) return [[span("no tasks")]];
   const s = initialConsoleState(); s.panel = 3; s.tasks = tasks;
   const stages = allTasks === null ? undefined : new Map(taskProgress(boardColumnContext(tasks, allTasks)).stages.map(stage => [stage.id, stage]));
+  const counts = [...new Set(tasks.map(task => task.state))].map(state => `${tasks.filter(task => task.state === state).length} ${state}`).join(", ");
+  if (!full && columns !== undefined) {
+    const data = tasks.map(task => { const row = cells(s, task, false, now, stages); row[2] = span(row[2]!.text, peerTone(task.owner ?? "")); row[3] = span(row[3]!.text, peerTone(task.reviewer ?? "")); return row; });
+    return [...compactBoard(tasks, data, columns, allTasks !== null), [], ...lines(`${plural(tasks.length, "task")}: ${counts}`, columns), ...(allTasks !== null ? lines(BOARD_LEGEND, columns, "muted") : [])];
+  }
   const data = tasks.map(task => {
     const row = cells(s, task, false, now, stages);
     row[2] = span(row[2]!.text, peerTone(task.owner ?? ""));
@@ -280,7 +354,6 @@ export function renderBoard(tasks: any[], columns?: number, now = Date.now(), _f
     if (allTasks === null) row.pop();
     return row;
   });
-  const counts = [...new Set(tasks.map(task => task.state))].map(state => `${tasks.filter(task => task.state === state).length} ${state}`).join(", ");
   return [...rows(allTasks === null ? TABLES[3]!.slice(0, -1) : [...TABLES[3]!], data, columns), [], ...lines(`${plural(tasks.length, "task")}: ${counts}`, columns)];
 }
 export function renderBudget(data: BudgetOutput, columns?: number, now = Date.now(), _full = false): Span[][] {

package/src/cli/reset.ts

@@ -11,7 +11,7 @@ import { HUB_DB_BUSY_TIMEOUT_MS } from "../hub/db-timeout.ts";
 /** Agent session resume pointers. `pi-sessions/` holds Pi transcripts, history rather than pointers, and stays. */
 export const SESSION_POINTERS = ["sessions.json", "claude-session.json", "claude-context.json"];
 /** The fixed pointers plus each Claude instance's own session and context files (#450 I3). */
-const sessionPointers = (stateDir: string): string[] => [...SESSION_POINTERS, ...(existsSync(stateDir) ? readdirSync(stateDir).filter(name => /^claude-(session|context)\.[a-z][a-z0-9-]{0,31}\.json$/.test(name)) : [])];
+const sessionPointers = (stateDir: string): string[] => [...SESSION_POINTERS, ...(existsSync(stateDir) ? readdirSync(stateDir).filter(name => /^claude-(session|context|task-sessions)\.[a-z][a-z0-9-]{0,31}\.json$/.test(name)) : [])];
 /** What a running daemon publishes; a daemon that did not stop cleanly (crash, SIGKILL, forced exit) leaves it. */
 export const MANIFEST = ["status.json", "control-token", "hub.pid"];
 

package/src/cli/settings-edit.ts

@@ -0,0 +1,89 @@
+/** #689: `ahub settings edit` and `ahub settings backups`. Parsing and rendering only; the hub validates, previews and writes. */
+export interface SettingsEditArgs { file: "config.local.json" | "sdlc.toml"; set: { path: string[]; value: unknown }[]; reason?: string; preview: boolean; yes: boolean }
+export const SETTINGS_EDIT_USAGE = "usage: ahub settings edit <config.local.json|sdlc.toml> (set <path> <json> | remove <path>)... [--reason <text>] [--preview] [--yes] | ahub settings backups [--json]";
+
+/** The request a command line asks for, or the usage line. Values are JSON, so a string needs its quotes. */
+export function parseSettingsEditArgs(argv: readonly string[]): SettingsEditArgs | string {
+  const [file, ...rest] = argv;
+  if (file !== "config.local.json" && file !== "sdlc.toml") return SETTINGS_EDIT_USAGE;
+  const set: SettingsEditArgs["set"] = [];
+  let reason: string | undefined, preview = false, yes = false;
+  const path = (text: string | undefined): string[] | undefined => {
+    if (!text || text.startsWith(".") || text.endsWith(".") || text.includes("..")) return undefined;
+    return text.split(".");
+  };
+  for (let index = 0; index < rest.length; index++) {
+    const word = rest[index]!;
+    if (word === "--preview") preview = true;
+    else if (word === "--yes") yes = true;
+    else if (word === "--reason") { reason = rest[++index]; if (reason === undefined) return SETTINGS_EDIT_USAGE; }
+    else if (word === "set") {
+      const target = path(rest[++index]), text = rest[++index];
+      if (!target || text === undefined) return SETTINGS_EDIT_USAGE;
+      try { set.push({ path: target, value: JSON.parse(text) }); } catch { return SETTINGS_EDIT_USAGE; }
+    } else if (word === "remove") {
+      const target = path(rest[++index]);
+      if (!target) return SETTINGS_EDIT_USAGE;
+      set.push({ path: target, value: null });
+    } else return SETTINGS_EDIT_USAGE;
+  }
+  if (!set.length) return SETTINGS_EDIT_USAGE;
+  return { file, set, ...(reason !== undefined ? { reason } : {}), preview, yes };
+}
+
+/** What a person reads before confirming: the diff lines, the warning of a tier 3 key and the word to type. */
+export function renderEditPreview(reply: { ok?: unknown; lines?: unknown; warning?: unknown; confirm?: unknown }): string[] {
+  const lines = Array.isArray(reply.lines) ? reply.lines.map(line => String(line)) : [];
+  if (typeof reply.warning === "string") lines.push(`warning: ${reply.warning}`);
+  if (typeof reply.confirm === "string") lines.push(`type ${reply.confirm} to confirm`);
+  return lines;
+}
+
+export interface SettingsEditPorts {
+  request: (message: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  /** Asks one line on a terminal; null when there is none. */
+  ask: (prompt: string) => Promise<string | null>;
+  print: (line: string) => void;
+}
+/**
+ * The whole command, with its ports injected. The person's terminal is the only place a tier 3 key can be changed, and only by
+ * typing the key's name: `--yes` confirms an ordinary structural edit and never a tier 3 one.
+ */
+export async function runSettingsEdit(argv: readonly string[], ports: SettingsEditPorts): Promise<string | undefined> {
+  const { request, ask, print } = ports;
+  if (argv[0] === "backups") {
+    if (argv.length > 2 || (argv[1] !== undefined && argv[1] !== "--json")) return SETTINGS_EDIT_USAGE;
+    const view = await request({ t: "config_edit_get" });
+    const backups = Array.isArray(view.backups) ? view.backups as { name: string; file: string; at: number; bytes: number }[] : [];
+    if (argv[1] === "--json") print(JSON.stringify(backups, null, 2));
+    else if (!backups.length) print("no config backups yet");
+    else for (const item of backups) print(`${new Date(item.at).toISOString()}  ${item.file}  ${item.bytes} bytes  ${item.name}`);
+    return undefined;
+  }
+  const parsed = parseSettingsEditArgs(argv[0] === "edit" ? argv.slice(1) : argv);
+  if (typeof parsed === "string") return parsed;
+  const view = await request({ t: "config_edit_get" });
+  const revisions = view.revisions as Record<string, string> | undefined;
+  const revision = revisions?.[parsed.file];
+  if (typeof revision !== "string") return "the running hub does not report config revisions: upgrade and restart it to use ahub settings edit";
+  const body = { file: parsed.file, revision, set: parsed.set };
+  const preview = await request({ t: "config_edit_preview", edit: body });
+  for (const line of renderEditPreview(preview)) print(line);
+  if (parsed.preview) { print("preview only; nothing was changed"); return undefined; }
+  const typed = typeof preview.confirm === "string" ? preview.confirm : undefined;
+  let confirm: string | undefined;
+  if (typed) {
+    const answer = await ask(`Type ${typed} to confirm: `);
+    if (answer === null) return "not a terminal: a key that runs code or locates secrets is confirmed by typing its name; nothing was changed";
+    if (answer.trim() !== typed) { print("nothing was changed"); return undefined; }
+    confirm = typed;
+  } else if (!parsed.yes) {
+    const answer = await ask("Write this change? [y/N] ");
+    if (answer === null) return "not a terminal: nothing was changed; rerun with --yes after reviewing the preview";
+    if (!/^(y|yes)$/i.test(answer.trim())) { print("nothing was changed"); return undefined; }
+  }
+  const result = await request({ t: "config_edit_apply", edit: body, ...(confirm ? { confirm } : {}), ...(parsed.reason !== undefined ? { reason: parsed.reason } : {}) });
+  print(String(result.text ?? "config written"));
+  if (Array.isArray(result.restartPending) && result.restartPending.length) print(`restart pending: ${result.restartPending.join(", ")}; restart the hub (ahub restart) to apply`);
+  return undefined;
+}

package/src/cli/status-lines.ts

@@ -1,7 +1,7 @@
 import type { ContextView } from "../hub/context-window.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; importantWaitingSince?: number; importantWaitingNote?: string; attached?: boolean; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; importantWaitingSince?: number; importantWaitingNote?: string; attached?: boolean; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; reviewerUnavailable?: string; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string; coolingUntil?: string; failures?: number; failingUntil?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */

package/src/cli/terminal-recovery.ts

@@ -328,7 +328,7 @@ export function recordPath(stateDir: string): string {
   return join(stateDir, RECORD_FILE);
 }
 
-/** Extra terminal ownership is supported only for the native proxy transport; other I2 extras stay headless. */
+/** Resolve declared terminal roots without treating a launch candidate as daemon ownership proof. */
 function executionRoot(peer: string, projectRoot: string, captured?: string): string {
   const builtin = definitionOf(peer);
   if (builtin?.session.launchRecord) return projectRoot;
@@ -336,11 +336,6 @@ function executionRoot(peer: string, projectRoot: string, captured?: string): st
   const definition = catalog.definitionOf(peer, declarations);
   if (!definition?.session.launchRecord) throw new Error(`${peer}: no managed terminal recovery adapter`);
   if (!declarations?.[peer] || definition.transport !== "codex-appserver" && definition.transport !== "claude-channel") throw new Error(`${peer}: extra instance has no managed terminal support`);
-  // #450 I3: a Claude instance reviews or plans in the canonical checkout; it never owns an execution worktree.
-  if (definition.transport === "claude-channel") {
-    if (captured !== undefined && captured !== projectRoot) throw new Error(`${peer}: recorded execution root changed; manual recovery required`);
-    return projectRoot;
-  }
   const expected = resolveInstanceExecutionCwd(projectRoot, peer, declarations, effectiveInstanceRoles(peer, declarations, roles, catalog), catalog);
   if (captured !== undefined && captured !== expected) throw new Error(`${peer}: declared execution worktree changed; manual recovery required`);
   return expected;

package/src/hub/action-enforce.ts

@@ -0,0 +1,82 @@
+import { ACTION_CLASSES, classifyAction, type ActionClass } from "./action-class.ts";
+import { actionApprovalText, actionPolicyConfig, type ActionBudgets, type ActionPolicyConfig } from "./action-policy.ts";
+import type { ActionGateVerdict } from "../adapters/acp.ts";
+
+/**
+ * Where the always-ask policy (#636) meets the two surfaces that see a tool call before it runs: the Claude PreToolUse hook and ACP
+ * `session/request_permission`. The classifier (`action-class.ts`) and the budget ledger (`action-policy.ts`) decide; this file only
+ * connects them, and only ever adds an approval: an empty result keeps the native permission policy.
+ */
+
+/** One native tool call as an adapter saw it: every name it is known by, the ACP tool kind when reported, and its arguments. */
+export interface ActionCall { names: readonly string[]; kind?: string; input: unknown }
+
+/** The classes of one call. ACP names a shell call `execute` by kind whatever its tool is called, so that kind is also read as a shell. */
+export function classifyCall(call: ActionCall, root: string): ActionClass[] {
+  const names = new Set(call.names.filter(name => typeof name === "string" && name.length > 0));
+  if (call.kind === "execute") names.add("bash");
+  const found = new Set<ActionClass>();
+  for (const name of names) for (const key of classifyAction(name, call.input, root)) found.add(key);
+  return ACTION_CLASSES.filter(key => found.has(key));
+}
+
+/**
+ * The classes the Claude PreToolUse hook must `ask` about, in every permission mode. The budget never relaxes it: Claude's own dialog
+ * cannot carry a class-budget choice, so every classed Claude call asks (a count of zero approved calls, always). A handle-less request
+ * selects the classes without touching any session ledger.
+ */
+export function claudeActionClasses(budgets: ActionBudgets, tool: string, input: unknown, root: string): ActionClass[] {
+  const classes = classifyAction(tool, input, root);
+  if (!classes.length) return [];
+  const decision = budgets.request(undefined, classes);
+  return decision.kind === "ask" ? decision.classes : [];
+}
+
+/** The command line an approval shows: the shell command when there is one, else the arguments. Bounded by the caller's screen. */
+export function commandText(input: unknown): string {
+  let value: unknown = input;
+  if (typeof input === "string") { try { value = JSON.parse(input) as unknown; } catch { return input; } }
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const record = value as Record<string, unknown>, command = record.command ?? record.cmd;
+    if (typeof command === "string") return command;
+    if (Array.isArray(command) && command.every(word => typeof word === "string")) return (command as string[]).join(" ");
+    if (Array.isArray(record.args) && record.args.every(word => typeof word === "string")) return ["git", ...(record.args as string[])].join(" ");
+  }
+  try { return JSON.stringify(value) ?? ""; } catch { return ""; }
+}
+
+export interface ActionGatePorts<T> {
+  budgets: ActionBudgets;
+  policy(): ActionPolicyConfig | undefined;
+  /** The peer's execution root: a delete outside it is classed. */
+  root(peer: string): string;
+  /** The task the peer is working on, for the approval line. */
+  task(peer: string): T | undefined;
+  /** The task's public view (`Tasks.publicView`): the only way a task title reaches an approval. */
+  publicView(task: T): Record<string, unknown>;
+  /** A private turn or an open PII task: the command is withheld. */
+  isPrivate(peer: string): boolean;
+  /** The PII screen for text (`Tasks.nameable`). */
+  nameable(text: string): boolean;
+}
+
+/**
+ * The ACP gate of one peer. It returns a verdict only when a person must be asked: a classed call with no session budget left. A call
+ * within an approved class budget, and every unclassed call, return undefined and follow the permission mode as before (the budget
+ * spends here, once per request).
+ */
+export function actionGate<T>(ports: ActionGatePorts<T>, peer: string): (call: ActionCall, session: string) => ActionGateVerdict | undefined {
+  return (call, session) => {
+    const classes = classifyCall(call, ports.root(peer));
+    if (!classes.length) return undefined;
+    const decision = ports.budgets.request(ports.budgets.bindSession(peer, session), classes);
+    if (decision.kind !== "ask") return undefined; // native, or within an approved class budget
+    const title = actionApprovalText(decision.classes, commandText(call.input), ports.task(peer), {
+      publicView: task => ports.publicView(task), private: ports.isPrivate(peer), commandView: command => ports.nameable(command) ? command : undefined });
+    const challenge = decision.challenge, limits = actionPolicyConfig(ports.policy()).budgets;
+    // A budget of one is this call alone: the ordinary allow already says that, so no second choice is offered for it.
+    if (!challenge || !decision.classes.some(key => limits[key] > 1)) return { title };
+    return { title, budget: { label: decision.classes.map(key => `${key} x${limits[key]}`).join(", "), approve: () => ports.budgets.approve(challenge) } };
+  };
+}