@staix/agent-hub 0.14.0 → 0.16.0

package/src/cli/console-config.ts

@@ -0,0 +1,123 @@
+/**
+ * #689: the console's structural config form (Settings panel, key `c`). A pure reducer: it collects answers, builds the one request the
+ * hub validates (`config_edit_preview`, then `config_edit_apply`) and never judges a value itself. The loaders' reasons come back from
+ * the hub and are shown as they are. A tier 3 key is confirmed by typing its name, never by `y`.
+ */
+export interface ConfigEditBody { file: "config.local.json" | "sdlc.toml"; revision: string; set: { path: string[]; value: unknown }[] }
+export type ConfigFormKind = "instance" | "sdlc" | "other";
+export interface ConfigForm {
+  kind: ConfigFormKind; token: number;
+  /** The instance ids the hub reports: an id in it changes leaf by leaf, a new id is added as one object. */
+  known?: readonly string[];
+  /** True until the person has chosen what to edit (1, 2 or 3). */
+  choosing?: boolean;
+  phase: "fields" | "preview" | "reason" | "confirm" | "typed";
+  step: number; answers: string[]; text: string;
+  edit?: ConfigEditBody; lines?: string[]; reason?: string;
+  /** The key a tier 3 edit must be confirmed with, from the hub's preview. */
+  typed?: string; warning?: string;
+}
+export type ConfigFormEffect =
+  | { type: "config_preview"; token: number; edit: ConfigEditBody }
+  | { type: "config_write"; edit: ConfigEditBody; reason: string; confirm?: string };
+export interface ConfigFormStep { form?: ConfigForm; effect?: ConfigFormEffect; note?: string }
+
+const FIELDS: Record<ConfigFormKind, readonly { name: string; ask: string }[]> = {
+  instance: [
+    { name: "id", ask: "instance id, <kind>-<name> (e.g. codex-review)" }, { name: "kind", ask: "kind (claude, codex, kimi, jcode, ...; empty for an instance that exists already)" },
+    { name: "roles", ask: "roles, comma list (planner, implementer, verifier, reviewer; empty leaves it)" },
+    { name: "start_mode", ask: "start_mode (headless; empty leaves it, clear removes it)" }, { name: "review_mode", ask: "review_mode (fresh; empty leaves it unset)" },
+    { name: "worktree", ask: "worktree path (empty leaves it unset)" }, { name: "permission_mode", ask: "permission_mode (ask, ask-when-needed, never-ask; empty leaves it unset)" },
+    { name: "readOnly", ask: "readOnly (true or false; empty leaves it unset)" },
+  ],
+  sdlc: [{ name: "mode", ask: "sdlc mode (off, advise, enforce; empty leaves it)" }, { name: "required_checks", ask: "required checks, comma list (empty leaves them)" }],
+  other: [{ name: "path", ask: "key path, dot separated (e.g. review.pool)" }, { name: "json", ask: "JSON value (empty removes the key)" }],
+};
+const a1x = (text: string | undefined): text is string => !!text;
+const list = (text: string): string[] => text.split(",").map(item => item.trim()).filter(Boolean);
+
+/** `1` an instance, `2` the lifecycle, `3` another structural key; anything else opens nothing. */
+export function openConfigForm(choice: string, token: number, known: readonly string[] = []): ConfigForm | undefined {
+  const kind = ({ "1": "instance", "2": "sdlc", "3": "other" } as const)[choice as "1"];
+  return kind ? { kind, token, phase: "fields", step: 0, answers: [], text: "", ...(known.length ? { known } : {}) } : undefined;
+}
+
+export function configFormPrompt(form: ConfigForm): string {
+  if (form.choosing) return "edit: 1 instance  2 sdlc lifecycle  3 another key  Esc cancel";
+  if (form.phase === "fields") return `${FIELDS[form.kind][form.step]!.ask}: ${form.text}`;
+  if (form.phase === "preview") return "checking the change with the hub's loaders; Esc cancels";
+  if (form.phase === "reason") return `reason: ${form.text}`;
+  if (form.phase === "typed") return `${form.warning ?? "this runs code with the daemon's rights"}; type ${form.typed} to confirm: ${form.text}`;
+  return `write ${form.edit?.file} (${form.reason})? y/N`;
+}
+
+/** The request the answers describe, or the first reason they cannot. */
+function build(form: ConfigForm, revisions: Record<string, string>): { edit: ConfigEditBody } | { note: string } {
+  const [a0 = "", a1 = ""] = form.answers;
+  if (form.kind === "instance") {
+    const names = ["kind", "roles", "start_mode", "review_mode", "worktree", "permission_mode", "readOnly"] as const;
+    const typed = names.flatMap((name, index) => a1x(form.answers[index + 1]) ? [[name, form.answers[index + 1]!] as const] : []);
+    const ro = typed.find(([name]) => name === "readOnly");
+    if (ro && !["true", "false", "clear"].includes(ro[1])) return { note: "readOnly is true or false (or clear)" };
+    const convert = (name: string, text: string): unknown => name === "roles" ? list(text) : name === "readOnly" ? text === "true" : text;
+    const file = revisions["config.local.json"] ?? "absent";
+    if (form.known?.includes(a0)) {
+      // An existing instance changes leaf by leaf: a blank field keeps its value, and a tier 3 field it holds is never part of the request.
+      if (!typed.length) return { note: "type a field to change, or clear to remove one" };
+      return { edit: { file: "config.local.json", revision: file, set: typed.map(([name, text]) => ({ path: ["instances", a0, name], value: text === "clear" ? null : convert(name, text) })) } };
+    }
+    if (!a1) return { note: "the kind is required for a new instance" };
+    const value: Record<string, unknown> = {};
+    for (const [name, text] of typed) if (text !== "clear") value[name] = convert(name, text);
+    return { edit: { file: "config.local.json", revision: file, set: [{ path: ["instances", a0], value }] } };
+  }
+  if (form.kind === "sdlc") {
+    const set: ConfigEditBody["set"] = [];
+    if (a0) set.push({ path: ["mode"], value: a0 });
+    if (a1) set.push({ path: ["required_checks"], value: list(a1) });
+    if (!set.length) return { note: "give a mode or the required checks" };
+    return { edit: { file: "sdlc.toml", revision: revisions["sdlc.toml"] ?? "absent", set } };
+  }
+  let value: unknown = null;
+  if (a1.trim()) { try { value = JSON.parse(a1); } catch { return { note: "the value is not valid JSON (strings need their quotes)" }; } }
+  return { edit: { file: "config.local.json", revision: revisions["config.local.json"] ?? "absent", set: [{ path: a0.split("."), value }] } };
+}
+
+/** One key. A chunk longer than one key is pasted text: it is text in a text phase and never an answer to y/N. */
+export function reduceConfigForm(form: ConfigForm, key: string, revisions: Record<string, string>): ConfigFormStep {
+  if (key === "\x1b") return { form: undefined };
+  if (form.choosing) {
+    const chosen = key.length === 1 ? openConfigForm(key, form.token, form.known) : undefined;
+    return { form: chosen ?? form };
+  }
+  if (form.phase === "preview") return { form };
+  if (form.phase === "confirm") {
+    if (key === "n") return { form: undefined };
+    if (key !== "y") return { form };
+    return { form: undefined, effect: { type: "config_write", edit: form.edit!, reason: form.reason! } };
+  }
+  const text = (current: ConfigForm): ConfigFormStep => {
+    if (key === "\x7f" || key === "\b") return { form: { ...current, text: Array.from(current.text).slice(0, -1).join("") } };
+    if (key === "\x15") return { form: { ...current, text: "" } };
+    if (key.startsWith("\x1b") || key === "\r" || key === "\n") return { form: current };
+    return { form: { ...current, text: (current.text + key.replace(/[\x00-\x1f\x7f]/g, "")).slice(0, 4000) } };
+  };
+  if (key !== "\r" && key !== "\n") return text(form);
+  const answer = form.text.trim();
+  if (form.phase === "reason") {
+    if (!answer || Buffer.byteLength(answer) > 400) return { form, note: "give a reason from 1 to 400 UTF-8 bytes" };
+    return { form: { ...form, reason: answer, text: "", phase: form.typed ? "typed" : "confirm" } };
+  }
+  if (form.phase === "typed") {
+    if (answer !== form.typed) return { form, note: `type exactly ${form.typed}` };
+    return { form: undefined, effect: { type: "config_write", edit: form.edit!, reason: form.reason!, confirm: form.typed } };
+  }
+  // phase "fields"
+  if (form.kind === "instance" && form.step === 0 && !answer) return { form, note: "an instance id is required" };
+  if (form.kind === "other" && form.step === 0 && (!answer || answer.startsWith(".") || answer.endsWith(".") || answer.includes(".."))) return { form, note: "give a key path such as review.pool" };
+  const answers = [...form.answers, answer];
+  if (form.step + 1 < FIELDS[form.kind].length) return { form: { ...form, answers, step: form.step + 1, text: "" } };
+  const built = build({ ...form, answers }, revisions);
+  if ("note" in built) return { form: { ...form, answers: answers.slice(0, -1), text: answer }, note: built.note };
+  return { form: { ...form, answers, text: "", phase: "preview", edit: built.edit }, effect: { type: "config_preview", token: form.token, edit: built.edit } };
+}

package/src/cli/console-state.ts

@@ -9,6 +9,8 @@ import { sanitize } from "../hub/envelope.ts";
 import type { SettingRow, SettingValue } from "../hub/settings.ts";
 import { symbolFields, overlapFields } from "./console-symbols.ts";
 import { choicePrompt, reviewChoiceFor, reviewHint, reviewRefusal, verdictGuide, verdictInput, type ReviewChoice, type Verdict } from "./console-review.ts";
+import { configFormPrompt, reduceConfigForm, type ConfigEditBody, type ConfigForm } from "./console-config.ts";
+import { windowKind } from "../hub/window-kind.ts";
 import { USAGE_DROP, USAGE_HEAD, usageCells, usageDetail, usagePeers, usageTaskLines, type UsageState } from "./console-usage.ts";
 
 export interface Approval {
@@ -24,6 +26,8 @@ export interface SettingsEdit {
   text: string; value?: SettingValue; reason?: string; lines?: string[]; confirm?: string; undoDigest?: string;
 }
 export interface ConsoleState {
+  /** #689: the structural config form (Settings panel, key c) and the file revisions the hub last reported. */
+  configForm?: ConfigForm; configRevisions?: Record<string, string>; configInstances?: string[];
   settingsRows?: SettingRow[]; settingsKnown?: boolean; settingsUndo?: string; settingsProblem?: string;
   settingsEdit?: SettingsEdit; settingsSequence?: number;
   pendingRestart?: { key: string; reason: string }[];
@@ -65,6 +69,7 @@ export interface ConsoleState {
 export type Detail = string | Record<string, unknown>;
 export type ConsoleEffect = { type: "exit" } | { type: "permit"; id: string; option?: string } |
   { type: "settings_preview"; token: number; key?: string; value?: SettingValue; undo: boolean } |
+  { type: "config_preview"; token: number; edit: ConfigEditBody } | { type: "config_write"; edit: ConfigEditBody; reason: string; confirm?: string } |
   { type: "settings_write"; key?: string; value?: SettingValue; undo: boolean; reason: string; confirm?: string; undoDigest?: string } |
   { type: "permission_default"; peer: string; confirmed: boolean } | { type: "command"; args: string[] } | { type: "show"; panel: number; id: string } | { type: "print"; text: string; kind: string; tone?: Tone } | { type: "keys" };
 export function initialConsoleState(panels = false): ConsoleState {
@@ -330,8 +335,25 @@ function taskFields(detail: Record<string, unknown>): [string, unknown][] {
   const at = fields.findIndex(([key]) => key === "plan");
   return at < 0 ? [...fields, ...block] : [...fields.slice(0, at + 1), ...block, ...fields.slice(at + 1)];
 }
-const detailLines = (detail: Detail, columns: number, now: number, task = false): Span[][] =>
-  typeof detail === "string" ? wrap(detail, columns).map(text => [span(text)]) : fieldLines(task ? taskFields(detail) : Object.entries(detail), columns, now).flat();
+/**
+ * The Peers panel's detail row carries the whole peer, `budget` included. Its windows read as one line each: `5h 23% resets in 10m, native, claude status line, measured 6s ago`,
+ * so a person sees what each number is and where it came from (#285 AC7). A window without a kind (an older hub) is classified like the CLI does.
+ */
+export function budgetFields(budget: any, now: number): [string, unknown][] {
+  if (!budget || typeof budget !== "object") return [];
+  const windows = Array.isArray(budget.windows) ? budget.windows : [];
+  const lines = windows.map((w: any) => {
+    const stale = w.stale ? " (stale)" : w.superseded ? " (information only: a measurement outranks it)" : "";
+    return `${w.id} ${Math.round(Number(w.used) * 100)}%${typeof w.resetsAt === "number" ? ` resets ${relative(w.resetsAt, now)}` : ""}, ${windowKind({ id: String(w.id), source: typeof w.source === "string" ? w.source : "", kind: w.kind })}, ${typeof w.source === "string" ? w.source : "unknown source"}${typeof w.at === "number" ? `, measured ${relative(w.at, now)}` : ""}${stale}`;
+  });
+  return [["quota", lines.length ? lines : typeof budget.note === "string" ? budget.note : "no reading"], ...(lines.length && typeof budget.note === "string" ? [["quota note", budget.note] as [string, unknown]] : [])];
+}
+const detailLines = (detail: Detail, columns: number, now: number, task = false): Span[][] => {
+  if (typeof detail === "string") return wrap(detail, columns).map(text => [span(text)]);
+  const { budget, ...rest } = detail as Record<string, unknown>;
+  const entries: [string, unknown][] = task ? taskFields(detail) : "budget" in detail && !task ? [...Object.entries(rest), ...budgetFields(budget, now)] : Object.entries(detail);
+  return fieldLines(entries, columns, now).flat();
+};
 const allowOptions = (a: Approval) => a.options.filter(o => o.kind.startsWith("allow"));
 /** A pushed request as the console keeps it: every agent-supplied field a string, so no draw can throw on one. */
 export function approvalFrom(msg: any): Approval {
@@ -490,6 +512,13 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
   const done = () => ({ state: bound(s), effects });
   const answered = (id: string) => { s.approvals = s.approvals.filter(a => a.id !== id); if (s.approvalId === id) s.approvalId = undefined; };
   if (key === "\x03") { effects.push({ type: "exit" }); return done(); }
+  if (s.configForm) {
+    const step = reduceConfigForm(s.configForm, key, s.configRevisions ?? {});
+    s.configForm = step.form;
+    if (step.note) notify(s, step.note, now);
+    if (step.effect) effects.push(step.effect);
+    return done();
+  }
   if (s.settingsEdit) {
     const edit = { ...s.settingsEdit }; s.settingsEdit = edit;
     if (key === "\x1b") { s.settingsEdit = undefined; return done(); }
@@ -684,6 +713,14 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     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 === "c") {
+    const token = (s.settingsSequence ?? 0) + 1; s.settingsSequence = token;
+    s.configForm = { kind: "other", token, phase: "fields", step: 0, answers: [], text: "", choosing: true, ...(s.configInstances?.length ? { known: s.configInstances } : {}) };
+    return done();
+  }
+  if (s.mode === "panels" && s.panel === 6 && s.detail === undefined && key === "R" && s.pendingRestart?.length) {
+    s.input = "restart"; s.editing = true; 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(); }
@@ -962,8 +999,9 @@ function taskHints(row: any): string[] {
 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"];
+  // The structural config form and the restart prefill need no selected row (#689).
+  if (s.panel === 6) return [...(row ? ["e edit"] : []), "c config", ...(s.settingsUndo ? ["u undo"] : []), ...(s.pendingRestart?.length ? ["R restart"] : [])];
   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", "w WIP limit"];
   if (s.panel === 4) return [row.state === "queued" ? "r discard" : "r resolve"];       // D (the peer's whole backlog) is in the ? key table: it must not push j/k off an 80-column footer
   return [];
@@ -1044,6 +1082,7 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
   let prompt = s.editing ? `: ${s.input}` : hint(s, columns);
   if (s.confirm?.type === "permission") prompt = `allow ${quoted(s.confirm.option)} for ${s.confirm.peer} (request ${s.confirm.id})? y/N`;
   if (s.confirm?.type === "command") prompt = `${s.confirm.prompt ?? s.confirm.args.join(" ")}? y/N`;
+  if (s.configForm) prompt = configFormPrompt(s.configForm);
   if (s.settingsEdit) {
     const edit = s.settingsEdit;
     prompt = edit.phase === "value" ? `value for ${edit.key} (inherit removes): ${edit.text}` : edit.phase === "preview" ? "checking setting preview; Esc cancels" : edit.phase === "reason" ? `reason: ${edit.text}` : `${edit.undo ? "undo last setting" : `set ${edit.key}`} (${edit.reason})? y/N`;
@@ -1094,6 +1133,12 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
   const height = bodyHeight - noticeLines.length;
   const lines: Span[][] = [];
   if (s.confirm?.type === "permission_default") lines.push(...fieldLines([["default", `${s.confirm.peer} never-ask`], ["source", s.confirm.source], ["bounds", permissionBoundary(s.confirm.peer, undefined, createProjectAdapterCatalog())], ["decision", "y enables; n cancels for this hub; Esc defers; until then ask"]], columns, now).flat());
+  else if (s.configForm && !s.configForm.choosing && (s.configForm.lines?.length || s.configForm.phase !== "fields")) {
+    // #689: what the hub's loaders said about the request, as the person will confirm it: the diff, then the decision.
+    const form = s.configForm;
+    lines.push(...fieldLines([["file", form.edit?.file ?? "-"], ["diff", (form.lines ?? ["checking with the hub's loaders..."]).join("\n")], ...(form.warning ? [["warning", form.warning] as [string, unknown]] : []),
+      ["decision", form.typed ? `Esc cancels; type ${form.typed} to confirm` : "Esc cancels; saving needs a reason and explicit y"]], columns, now).flat());
+  }
   else if (s.settingsEdit) {
     const edit = s.settingsEdit;
     const row = s.settingsRows?.find(row => row.key === edit.key);

package/src/cli/console-symbols.ts

@@ -40,8 +40,9 @@ export function classifySymbols(task: any): SymbolBlock {
 export function symbolFields(task: any): [string, unknown][] {
   // Only a task as `task_show` shapes it (a numeric id and a state): any other detail an agent or a test hands the Tasks panel keeps its own layout.
   if (!task || typeof task.id !== "number" || typeof task.state !== "string" || isPrivate(task)) return [];
+  const related: [string, unknown][] = task.relatedMemory ? [["related notes", task.relatedMemory.state === "known" && Number.isSafeInteger(task.relatedMemory.count) && task.relatedMemory.count >= 0 ? task.relatedMemory.count : "unknown"]] : [];
   const block = classifySymbols(task);
-  if (block.state === "unknown") return [["symbols", "changed symbols: unknown (no code facts)"]];
+  if (block.state === "unknown") return [...related, ["symbols", "changed symbols: unknown (no code facts)"]];
   const items: Record<string, string>[] = [
     ...block.matching.map(s => ({ matching: s.name, in: s.path })), ...block.unplanned.map(s => ({ unplanned: s.name, in: s.path })), ...block.untouched.map(name => ({ untouched: name })),
   ];
@@ -49,7 +50,7 @@ export function symbolFields(task: any): [string, unknown][] {
   const note = [`changed symbols: ${block.matching.length} matching, ${block.unplanned.length} unplanned, ${block.untouched.length} untouched${block.head ? ` at ${block.head}` : ""}`,
     block.complete ? "" : "incomplete: some changed symbols were not listed, so an untouched one may have changed",
     "advisory: deleted symbols are not reported"].filter(Boolean).join("; ");
-  return [["symbols", shown.length ? shown : "none observed"], ["symbols note", items.length > shown.length ? `${note}; ${items.length - shown.length} more not shown` : note]];
+  return [...related, ["symbols", shown.length ? shown : "none observed"], ["symbols note", items.length > shown.length ? `${note}; ${items.length - shown.length} more not shown` : note]];
 }
 
 

package/src/cli/console-usage.ts

@@ -1,3 +1,4 @@
+import { windowKind, type WindowKind } from "../hub/window-kind.ts";
 import type { Counter, LimitsResult, UsageResult, UsageRow } from "../hub/usage-rollup.ts";
 
 // #683 U3: what the console's Usage panel shows, as plain strings. No terminal code and no state import here: console-state.ts renders it.
@@ -32,7 +33,7 @@ export function usagePeers(usage: UsageState | undefined, budget: Record<string,
   return [...ids].sort().map(id => ({ id }));
 }
 
-interface Budget { windows?: { id: string; used: number; resetsAt?: number }[]; paused?: { resetsAt: number } }
+interface Budget { windows?: { id: string; used: number; resetsAt?: number; kind?: string; source?: string }[]; paused?: { resetsAt: number }; note?: string }
 const windowText = (w: { id: string; used: number; resetsAt?: number }, rel: (at: number) => string) =>
   `${w.id} ${Math.round(w.used * 100)}%${typeof w.resetsAt === "number" ? ` ${rel(w.resetsAt)}` : ""}`;
 const lastResets = (limits: LimitsResult | undefined, peer: string, count: number) =>
@@ -66,7 +67,9 @@ export function usageDetail(usage: UsageState | undefined, peer: string, budget:
   const resets = lastResets(usage?.limits, peer, 3).map(h => `${h.window} ${rel(Date.parse(h.at))}`);
   const out: Record<string, string> = {
     peer,
-    quota: budget?.windows?.length ? budget.windows.map(w => windowText(w, rel)).join(", ") : "no reading",
+    quota: budget?.windows?.length ? budget.windows.map(w => windowText(w, rel)).join(", ") : budget?.note ?? "no reading",
+    // What each number is and where it came from (#285 AC7), in its own field so the quota line keeps its shape.
+    ...(budget?.windows?.length ? { "quota sources": budget.windows.map(w => `${w.id} ${windowKind({ id: w.id, source: w.source, kind: w.kind as WindowKind | undefined })}${w.source ? `, ${w.source}` : ""}`).join("; ") } : {}),
     pause: budget?.paused ? `budget pause, resumes ${rel(budget.paused.resetsAt)}` : "none",
     "last resets": resets.length ? resets.join(", ") : "none recorded",
     today: splitText(rowOf(usage?.today, peer)),

package/src/cli/console.ts

@@ -102,7 +102,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   let pendingStream: ConsoleEvent[] = []; let droppedStream = 0;
   let priorStreamFooterStart: number | undefined;
   let lastExpandedNotice = "";
-  const notice = (text: string) => notify(state, text, Date.now());
+  const notice = (text: string, tone: Tone = "failure") => notify(state, text, Date.now(), tone);
   const safeWrite = (text: string) => terminal.write(paint([{ text }], color));
   const streamLines = (event: ConsoleEvent) => terminalText(event.text).replace(/\t/g, " ").split("\n").flatMap((text, index) => {
     // Tabs are flattened before measuring, as wrap() does; commands already wrap cells at their own offsets.
@@ -226,7 +226,11 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
         state.recoveryNeed = status.status.recovery ? { id: status.status.recovery.operationId, running: true } : undefined;
       }
       if (syncPermissionDefaults(state, status.status?.permissionDefaults) && state.confirm?.type === "permission_default") stream({ text: permissionDefaultText(state.confirm), kind: "permission_default", peer: state.confirm.peer, tone: "attention" });
-      if (budget.budget) state.budget = budget.budget;
+      if (budget.budget) {
+        // #285: the hub's note per peer (no quota, nothing read yet) rides next to the windows, so the peer detail says why a number is missing.
+        const notes = new Map<string, any>((Array.isArray(budget.peers) ? budget.peers : []).map((n: any) => [String(n?.peer), n] as const));
+        state.budget = Object.fromEntries([...new Set([...Object.keys(budget.budget), ...notes.keys()])].map(peer => [peer, { windows: [], ...budget.budget[peer], ...(notes.get(peer)?.note ? { note: String(notes.get(peer).note) } : {}) }]));
+      }
       if (usageReplies) {
         const [today, week, life, limits, task] = usageReplies, failed = usageReplies.find(reply => reply?.ok === false);
         if (failed || !today?.usage || !week?.usage || !life?.usage || !limits?.limits) state.usage = { ...state.usage, problem: String(failed?.error ?? "usage is unavailable") };
@@ -243,6 +247,10 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
         if (settings.ok && Array.isArray(settings.rows)) {
           state.settingsRows = settings.rows; state.settingsKnown = true; state.settingsProblem = undefined;
           state.settingsUndo = typeof settings.undo === "string" ? settings.undo : undefined;
+          const revisions = (settings.configEdit as { revisions?: unknown } | undefined)?.revisions;
+          const known = (settings.configEdit as { known?: unknown } | undefined)?.known;
+          state.configInstances = Array.isArray(known) ? known.map(String).filter(Boolean) : [];
+          if (revisions && typeof revisions === "object") state.configRevisions = Object.fromEntries(Object.entries(revisions).filter(([, value]) => typeof value === "string")) as Record<string, string>;
           state.pendingRestart = Array.isArray(settings.pendingRestart) ? settings.pendingRestart : [];
           state.retainedConfig = Array.isArray(settings.retainedConfig) ? settings.retainedConfig : [];
         } else state.settingsProblem = String(settings.error ?? "settings are unavailable");
@@ -282,6 +290,26 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       } else state.settingsEdit = { ...edit, ...(action.undo ? { key: response.key, undoDigest: response.undoDigest } : {}), phase: "reason", text: "", lines: [...(Array.isArray(response.lines) ? response.lines.map(String) : []), ...(Array.isArray(response.tasks) ? response.tasks.flatMap((task: any) => [String(task.before?.join("\n") ?? ""), String(task.after?.join("\n") ?? "")]) : []), ...(response.hidden ? [`${response.hidden} more open tasks are not shown`] : [])], ...(typeof response.confirm === "string" ? { confirm: response.confirm } : {}) };
       draw(); return;
     }
+    if (action.type === "config_preview") {
+      const response = await client.request({ t: "config_edit_preview", edit: action.edit }, 5000);
+      const form = state.configForm;
+      // A reply for a form that was cancelled or replaced is dropped: it never opens a confirmation of its own.
+      if (!active || state.mode !== "panels" || !form || form.token !== action.token) return; // every form has its own token and one outstanding preview
+      if (response.ok === false) { state.configForm = undefined; notice(String(response.error ?? "config preview refused")); }
+      else state.configForm = { ...form, phase: "reason", text: "", lines: (Array.isArray(response.lines) ? response.lines : []).map(String).slice(0, 40),
+        ...(typeof response.confirm === "string" ? { typed: response.confirm, warning: typeof response.warning === "string" ? response.warning : undefined } : {}) };
+      draw(); return;
+    }
+    if (action.type === "config_write") {
+      const result = await client.request({ t: "config_edit_apply", edit: action.edit, reason: action.reason, ...(action.confirm ? { confirm: action.confirm } : {}) }, 35_000);
+      if (!active) return;
+      if (result.ok === false) notice(String(result.error ?? "config write refused"));
+      else {
+        const text = [String(result.text ?? "config saved"), ...(Array.isArray(result.restartPending) && result.restartPending.length ? [`restart pending: ${result.restartPending.join(", ")}`] : [])].join("; ");
+        stream({ text, kind: "settings" }); notice(text, "info");
+      }
+      await refresh(); draw(); return;
+    }
     if (action.type === "settings_write") {
       const result = await client.request({ t: action.undo ? "settings_undo" : "settings_set", key: action.key, ...(!action.undo ? { value: action.value } : { undoDigest: action.undoDigest }), reason: action.reason, ...(action.confirm ? { confirm: action.confirm } : {}) }, 35_000);
       if (!active) return;

package/src/cli/facts-hook.ts

@@ -65,7 +65,7 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
     const port = definitionOf(peer)?.hooks?.factsHook;
     const payload: unknown = JSON.parse(stdin);
     if (!port?.decode(nativeEvent, payload)) return undefined;
-    const hub = await ControlClient.connect(stateDir, { role: "tools", peer }, timeoutMs);
+    const hub = await ControlClient.connect(stateDir, { role: "tools", peer, ...(nativeHookIdentity(stateDir, peer).nativeLaunchId ? { launchId: nativeHookIdentity(stateDir, peer).nativeLaunchId } : {}) }, timeoutMs);
     try {
       const reply = await hub.request({ t: "native_facts", event: nativeEvent, payload, ...nativeHookIdentity(stateDir, peer) }, timeoutMs);
       const output = reply.ok ? port.encode(nativeEvent, typeof reply.text === "string" ? reply.text : undefined) : undefined;
@@ -74,7 +74,7 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
   }
   const input = JSON.parse(stdin) as { hook_event_name?: unknown; tool_name?: unknown; tool_input?: unknown; tool_use_id?: unknown; session_id?: unknown; transcript_path?: unknown };
   const phase = ({ SessionStart: "session", UserPromptSubmit: "start", PostToolUse: "post", Stop: "stop" } as Record<string, string>)[String(input.hook_event_name)] ?? "pre";
-  const hub = await ControlClient.connect(stateDir, { role: "tools", peer }, timeoutMs);
+  const hub = await ControlClient.connect(stateDir, { role: "tools", peer, ...(nativeHookIdentity(stateDir, peer).nativeLaunchId ? { launchId: nativeHookIdentity(stateDir, peer).nativeLaunchId } : {}) }, timeoutMs);
   try {
     const res = await hub.request({
       t: "facts",
@@ -90,10 +90,14 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
     if (phase !== "pre" || !res?.ok) return undefined;
     const permission = isPermissionMode(res.permission) ? res.permission : "ask";
     const fileTool = projectFileTool(input.tool_name, input.tool_input, res.projectRoot, res.protectInstructionFiles === true);
-    const allow = input.hook_event_name === "PreToolUse" && (permission === "never-ask" || permission === "ask-when-needed" && fileTool);
+    // Always-ask (#636): the hub classed this call (publish, external-write, destroy, install). `ask` wins over every allow, never-ask included.
+    // A present value that is not an empty list asks, even when malformed: the hook never turns an unreadable classification into an allow.
+    const classed = res.actionClasses !== undefined && !(Array.isArray(res.actionClasses) && res.actionClasses.length === 0);
+    const classNames = Array.isArray(res.actionClasses) ? res.actionClasses.filter((key: unknown): key is string => typeof key === "string" && /^[a-z-]{1,32}$/.test(key)) : [];
+    const allow = !classed && input.hook_event_name === "PreToolUse" && (permission === "never-ask" || permission === "ask-when-needed" && fileTool);
     const text = typeof res.text === "string" && res.text ? res.text : undefined;
-    if (!allow && !text) return undefined;
-    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", ...(text ? { additionalContext: text } : {}), ...(allow ? { permissionDecision: "allow" } : {}) } });
+    if (!allow && !classed && !text) return undefined;
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", ...(text ? { additionalContext: text } : {}), ...(classed ? { permissionDecision: "ask", permissionDecisionReason: `agent-hub always-ask${classNames.length ? `: ${classNames.join(", ")}` : ""}` } : allow ? { permissionDecision: "allow" } : {}) } });
   } finally {
     hub.close();
   }

package/src/cli/help.ts

@@ -40,7 +40,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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"],
     ["ahub logs [-f]", "the last 100 lines of hub.log; -f shows the last 10 and follows it"],
-    ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models and memory worker this project uses"],
+    ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models and memory library this project uses"],
+    ["ahub doctor --stale-anchors [--json]", "read-only bounded report of public memory symbol anchors at current HEAD; private or unavailable evidence stays unknown"],
     ["ahub doctor --orphans [--kill] [--json] [--color=auto|always|never]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
     ["ahub agents [--json]", "show each gated agent CLI's installed version and verdict (verified, in-line, trusted, refused or unknown)"],
     ["ahub agents trust <id> <version> [--revoke]", "accept an untested agent CLI version on this machine (person only; runtime proofs still run)"],
@@ -73,6 +74,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"],
@@ -83,26 +85,27 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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, 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: plan work with a reason; {} records a note-only revision, fields.sdlc sets backlog repo/issue identity and clears old spec acceptance; preserve pins/frozen scope and refuse stale edits; list is by rank (--json: raw listing)"],
     ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision>", "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"],
     ["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 deliverables [--task <id>] [--approved] [--check] [--json] [--color=auto|always|never]", "person only: what each task delivered and a reviewer approved, by id, hash and size (a path only where the PII screen allows); --check measures the files now and marks one changed since review"],
     ["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; a peer that cannot take it is refused with the reason; --revision refuses stale console actions"],
+    ["ahub task assign <id> <peer> [--role owner|reviewer|planner] [--revision N]", "name the owner (default), reviewer or person-only planner; 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)"],
     ["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"],
   ]],
   ["Budget", [
-    ["ahub budget [--json] [--full] [--color=auto|always|never]", "quota windows per peer, and who is paused until when"],
+    ["ahub budget [--json] [--full] [--color=auto|always|never]", "quota windows per peer with each number's kind (native, count, manual) and source, why a peer shows no number, and who is paused until when"],
     ["ahub budget set <peer> <0..1> [--resets-in 30m] [--window 5h|week]", "feed a reading by hand (also: test the relay)"],
     ["ahub budget resume <peer>", "override a budget pause; readings are ignored for that peer until the window resets"],
     ["ahub budget execution status [id] [--json] [--color=auto|always|never]", "read execution counters and limits"],
@@ -128,7 +131,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub bench export [--format jsonl|csv]", "benchmark records for outside analysis: ids, outcomes and counts, never suite text"],
     ["ahub check-path <file> [--peer <id>]", "other owners' open tasks that claim or changed a file"],
     ["ahub memory [list] [--tier short|long] [--kind <kind>] [--peer <p>] [--machine <id>] [--since <iso>] [--limit N] [--json]", "the hub's own memory for this project: decisions, contracts, fails and findings, short- and long-term (docs/memory.md)"],
-    ["ahub memory search <words> | show <id> | graph <id|node> [--hops 1|2] [--json]", "find entries, read one with its provenance, or list its graph neighbourhood"],
+    ["ahub memory search <words> | show <id> | graph <id|node> [--hops 1|2] [--history | --as-of <iso>] [--json]", "find entries, read one with its provenance, or list its graph neighbourhood; superseded and expired entries are hidden unless a person asks for --history or --as-of"],
     ["ahub memory promote|demote|forget <id> | supersede <old> <new> | rebuild", "a person's changes to memory: move an entry between tiers, forget it, mark it superseded, or rebuild the index from the logs"],
     ["ahub memory sync [--remote <private git url>] | machine [--label <name>]", "sync hub memory with your other machines through a private git remote (a person's), or show or name this machine"],
     ["ahub memory import claude-mem [--db <path>] [--limit N] [--restart] | dedupe [--apply] | suggestions | confirm|reject <id>", "copy the hub's notes from claude-mem into hub memory (a person's); review the model's suggested edges"],
@@ -143,7 +146,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/identity.ts

@@ -17,7 +17,7 @@ export function liveTestRefusal(command: string, args: readonly string[], contex
   if (command === "sdlc" && (args[0] === "authorize-release" || args[0] === "plan-review" || args[0] === "release-assign" || args[0] === "train" && args[1] !== "report")) return true;
   if (args.some(arg => arg === "--as-user" || arg.startsWith("--as-user="))) return true;
   const sub = command === "recovery" ? recoveryAction(args) : args.find(arg => arg !== "--json");
-  return ["task", "role", "goal"].includes(command)
+  return ["task", "role", "goal", "deliverables"].includes(command)
     || (command === "backlog" && sub !== "list") || (command === "release" && !["list", "show"].includes(sub ?? ""))
     || (command === "memory" && sub !== "graph")
     || (command === "recovery" && (sub === "reattach" || sub === "dispose" && context.repairedFresh === true))
@@ -68,6 +68,8 @@ export function classifyPeerCommand(command: string, args: readonly string[], ca
     if (["assign", "escalate"].includes(args[0] ?? "")) return "conductor";
     return "console";
   }
+  // #317: the deliverable list is the person's view of the board (it can name files); an agent reads its own tasks through hub_task_show.
+  if (command === "deliverables") return "console";
   if (command === "route") return args[0] === "explain" ? "allowed" : "console";
   // #691: reading agent CLI versions is harmless; trusting an untested version on this machine is a person's.
   if (command === "agents") return args.every(arg => arg === "--json") ? "allowed" : "console";

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 {