@staix/agent-hub 0.14.0 → 0.15.0

package/src/adapters/reviewer-print.ts

@@ -1,6 +1,6 @@
-import { spawn, type ChildProcess } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { OwnedPrintChild, PrintChildCleanupError } from "./claude-print-child.ts";
 import { randomUUID } from "node:crypto";
-import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { HUB, frame } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
@@ -107,9 +107,6 @@ export interface ReviewerPrintOptions {
   bindingCurrent?(task: number, binding: ReviewerReviewBinding): boolean;
 }
 
-// ponytail: 256 KiB per NDJSON frame and 4 MiB stdout per review child. Raise only with measured native receipts.
-const MAX_REVIEW_FRAME_BYTES = 256 * 1024, MAX_REVIEW_OUTPUT_BYTES = 4 * 1024 * 1024;
-class GroupCleanupError extends Error {}
 type ReviewTarget = Omit<ReviewerFailure, "cause">;
 interface ReviewBatch { targets: (ReviewTarget | undefined)[]; next: number; failures: ReviewerFailure[] }
 const reviewTarget = (env: Envelope): ReviewTarget | undefined => {
@@ -129,8 +126,7 @@ const reviewTask = (env: Envelope): number | undefined => {
 export class ReviewerPrintPeer extends BasePeer {
   readonly hubNative = true;
   private generation = 0;
-  private child: ChildProcess | undefined;
-  private childStop: ((child: ChildProcess) => Promise<void>) | undefined;
+  private child: OwnedPrintChild | undefined;
   private childCleanup: (() => Promise<void>) | undefined;
   private childCurrent: (() => boolean) | undefined;
   private reviewMcpClose: (() => void) | undefined;
@@ -242,7 +238,7 @@ export class ReviewerPrintPeer extends BasePeer {
       try { result = await this.review(env, task, generation); }
       catch (error) {
         if (generation !== this.generation) return;
-        if (error instanceof GroupCleanupError) {
+        if (error instanceof PrintChildCleanupError) {
           // Unavailable until a stop confirms the group gone: no new review runs beside the survivors.
           this.opts.log?.(`[${this.id}] review of task #${task}: ${error.message}`);
           this.settle("needs_review", `review process group still running: ${error.message}`);
@@ -329,60 +325,41 @@ export class ReviewerPrintPeer extends BasePeer {
     let mcpClosed=false;
     const closeMcp=()=>{ if(mcpClosed)return; mcpClosed=true; mcp?.close(); if(this.reviewMcpClose===closeMcp)this.reviewMcpClose=undefined; };
     this.reviewMcpClose=closeMcp;
-    let ownedChild: ChildProcess | undefined, releasing: Promise<void> | undefined;
+    let ownedChild: OwnedPrintChild | undefined, releasing: Promise<void> | undefined;
     let policyTimer: ReturnType<typeof setInterval> | undefined;
     const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
     launch = await this.prepare(randomUUID(), input, task, mcp?.config);
     if (generation !== this.generation || this.opts.admit?.(env) === false || launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation or admission changed before child spawn", launch.current?.() === false ? "binary" : "unknown");
     this.receipt = launch.isolation;
-    const [cmd, ...prefix] = launch.command;
     let quota = false;
-    return await new Promise<{ code: number | null; quota: boolean }>((resolve, reject) => {
-      const child = spawn(cmd!, [...prefix, ...launch!.args], { cwd: launch!.cwd ?? this.opts.cwd, detached: true,
-        env: peerChildEnv(this.id, launch!.envMode === "replace" ? launch!.env : { ...process.env, ...launch!.env }), stdio: ["pipe", "pipe", "ignore"] });
-      // Owned before any await, so a stop that lands before "spawn" still finds and kills it.
-      this.child = child;
-      ownedChild = child;
-      this.childStop = launch!.stop;
-      this.childCleanup = release;
-      this.childCurrent = launch!.watchCurrent ? launch!.current : undefined;
-      child.once("error", error => { if (this.child === child) { this.child = undefined; this.childStop = undefined; } reject(error); });
-      child.stdin!.on("error", () => { /* the child exited before reading its prompt; its exit settles the review */ });
-      child.once("spawn", () => {
-        trackGroup(child);
-        if (generation !== this.generation) { child.stdin!.destroy(); return; } // stopped meanwhile: no prompt
+    const child = new OwnedPrintChild({ peer: this.id, command: launch.command, args: launch.args,
+      cwd: launch.cwd ?? this.opts.cwd, env: launch.env, envMode: launch.envMode, input,
+      current: () => generation === this.generation, stop: launch.stop,
+      onError: () => { if (this.child === child) this.child = undefined; },
+      onSpawn: () => {
         this.runningBinding={task,binding};
         this.reviewing = task; this.reviewSeq++;
         if (this.childCurrent) policyTimer = setInterval(() => { this.reviewToken(task); }, 100);
-        child.stdin!.end(input);
-      });
-      let buffer = "", outputBytes = 0;
-      child.stdout!.on("data", (chunk: Buffer) => {
-        if (generation !== this.generation) return;
-        outputBytes += chunk.length;
-        if (outputBytes > MAX_REVIEW_OUTPUT_BYTES) { this.abortReview("review output limit exceeded"); return; }
-        buffer += chunk.toString("utf8");
-        for (let i; (i = buffer.indexOf("\n")) >= 0;) {
-          const line = buffer.slice(0, i); buffer = buffer.slice(i + 1);
-          if (Buffer.byteLength(line) > MAX_REVIEW_FRAME_BYTES) { this.abortReview("review output limit exceeded"); return; }
-          try {
-            const event: unknown = JSON.parse(line);
-            const usage = this.opts.backend.usage?.(event);
-            if (usage) this.opts.onUsage?.(usage, task);
-            if (this.opts.backend.failure?.(event) === "quota") quota = true;
-          } catch { /* not a stream-json line */ }
-        }
-        if (Buffer.byteLength(buffer) > MAX_REVIEW_FRAME_BYTES) { this.abortReview("review output limit exceeded"); return; }
-        this.touch();
-      });
-      child.once("exit", code => {
-        if (this.child === child) { this.reviewing = undefined; this.runningBinding=undefined; } // the verdict authority ends with the leader
-        // The review ends when its whole process group is gone (an MCP server or other descendant may outlive the leader).
-        (launch!.stop ? launch!.stop(child) : stopOwnedProcess(child, { group: true })).then(() => { if (this.child === child) { this.child = undefined; this.childStop = undefined; } resolve({ code, quota }); },
-          (error: Error) => reject(new GroupCleanupError(error.message)));
-      });
+      },
+      onFrame: event => {
+        const usage = this.opts.backend.usage?.(event);
+        if (usage) this.opts.onUsage?.(usage, task);
+        if (this.opts.backend.failure?.(event) === "quota") quota = true;
+      },
+      onActivity: () => this.touch(),
+      onLimit: () => this.abortReview("review output limit exceeded"),
+      onLeaderExit: () => {
+        if (this.child === child) { this.reviewing = undefined; this.runningBinding=undefined; }
+      },
     });
+    // Owned before any await, so a stop that lands before "spawn" still finds and kills it.
+    this.child = ownedChild = child;
+    this.childCleanup = release;
+    this.childCurrent = launch.watchCurrent ? launch.current : undefined;
+    const code = await child.done;
+    if (this.child === child) this.child = undefined;
+    return { code, quota };
     } finally {
       closeMcp();
       if (policyTimer) clearInterval(policyTimer);
@@ -403,8 +380,8 @@ export class ReviewerPrintPeer extends BasePeer {
     this.runningBinding=undefined;
     const child = this.child;
     if (!child) return;
-    await (this.childStop ? this.childStop(child) : stopOwnedProcess(child, { group: true }));
-    if (this.child === child) { await this.childCleanup?.(); this.child = undefined; this.childStop = undefined; this.childCleanup = undefined; this.childCurrent = undefined; }
+    await child.stop();
+    if (this.child === child) { await this.childCleanup?.(); this.child = undefined; this.childCleanup = undefined; this.childCurrent = undefined; }
   }
 }
 

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,7 @@ 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 { USAGE_DROP, USAGE_HEAD, usageCells, usageDetail, usagePeers, usageTaskLines, type UsageState } from "./console-usage.ts";
 
 export interface Approval {
@@ -24,6 +25,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 +68,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 {
@@ -490,6 +494,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 +695,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 +981,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 +1064,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 +1115,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.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.
@@ -243,6 +243,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 +286,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

@@ -73,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"],
@@ -83,7 +84,7 @@ 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: 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"],
@@ -96,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"],
@@ -143,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 {