@staix/agent-hub 0.13.0 → 0.15.0

package/src/adapters/registry-types.ts

@@ -1,3 +1,4 @@
+import type { ClaudeImplementerOptions } from "./claude-implementer.ts";
 import type { ReviewerBackend, ReviewerPrintOptions } from "./reviewer-print.ts";
 import type { SettingDef } from "../hub/settings.ts";
 import type { Addon } from "../hub/tooling.ts";
@@ -20,7 +21,7 @@ import type { BuiltinCliEntry } from "./definitions/native-cli-entry-types.ts";
 import type { NativePreviewBuilder } from "./definitions/native-cli-preview-common.ts";
 
 export type StartForm = "tui" | "headless";
-export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print" | "reviewer-print";
+export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print" | "reviewer-print" | "claude-implementer";
 
 /** Existing buildLaunch inputs plus the startup-bound instance and project identity. */
 export interface LaunchContext {
@@ -62,7 +63,8 @@ export type DaemonPorts =
   | { pi: PiOptions }
   | { local: LocalOptions }
   | { claudePrint: ClaudePrintOptions }
-  | { reviewerPrint: ReviewerPrintOptions };
+  | { reviewerPrint: ReviewerPrintOptions }
+  | { claudeImplementer: ClaudeImplementerOptions };
 
 export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   instance: string;
@@ -200,7 +202,7 @@ export interface AdapterDefinition {
     ownedFlags: readonly string[];
     conductorStartArgs?(args: string[]): { mode?: StartForm } | Error;
   };
-  identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin" };
+  identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin"; currentChild?: true };
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
   instances?: { mode: "external" | "headless"; roles?: readonly string[];
     /** Each declared instance runs its own native data home (`jcode_home`) and may pass its own provider, model and profile names (#685). Fixed builtins only. */
@@ -300,6 +302,8 @@ export interface AdapterDefinition {
   hooks?: Partial<NativeHooks>;
   /** #223: what a declared headless reviewer-only instance of this kind runs as. Fixed builtins only. */
   reviewerVariant?: AdapterDefinition;
+  /** #525: fixed builtin variant for declared headless implementer instances. */
+  headlessVariant?: AdapterDefinition;
   /** Fixed host backend; runtime isolation proof is required before bus admission. */
   reviewer?: { backend?: ReviewerBackend; defaultPool: boolean; unavailable?: string; declaration: "automatic" | "explicit" };
 }

package/src/adapters/registry.ts

@@ -24,7 +24,10 @@ function immutable<T>(value: T, seen = new WeakSet<object>()): T {
 }
 
 const fixedBuiltinDefinitions = new Set<AdapterDefinition>([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION, AGY_DEFINITION, AGY_REVIEWER_VARIANT]);
-for (const definition of [...fixedBuiltinDefinitions]) if (definition.reviewerVariant) fixedBuiltinDefinitions.add(definition.reviewerVariant);
+for (const definition of [...fixedBuiltinDefinitions]) {
+  if (definition.reviewerVariant) fixedBuiltinDefinitions.add(definition.reviewerVariant);
+  if (definition.headlessVariant) fixedBuiltinDefinitions.add(definition.headlessVariant);
+}
 
 /** Keep the native catalog's order, independently of the legacy default-role object order. */
 export const ADAPTERS: readonly AdapterDefinition[] = immutable([
@@ -65,6 +68,7 @@ for (const definition of [...ADAPTERS, ...declarationOnlyDefinitions]) {
   assertDefinitionCoherence(definition);
   assertNativeCapabilityScope(definition);
   if (definition.reviewerVariant) { assertDefinitionCoherence(definition.reviewerVariant); assertNativeCapabilityScope(definition.reviewerVariant); }
+  if (definition.headlessVariant) { assertDefinitionCoherence(definition.headlessVariant); assertNativeCapabilityScope(definition.headlessVariant); }
   if (definition.api !== ADAPTER_API || definitions.has(definition.kind)) throw new Error("invalid builtin adapter registry");
   definitions.set(definition.kind, definition);
 }
@@ -114,7 +118,11 @@ function resolvedDefinition(id: string, kind: string | undefined, instances: Kin
   const reviewerOnly = Array.isArray(roles) && !types.isProxy(roles) && roles.length === 1 && Object.getOwnPropertyDescriptor(roles, "0")?.value === "reviewer";
   const variant = definition?.reviewerVariant;
   const fresh = variant?.reviewer?.declaration === "automatic" || ownField(declaration, "review_mode") === "fresh";
-  return variant && kind !== id && reviewerOnly && ownField(declaration, "start_mode") === "headless" && fresh ? variant : definition;
+  const headless = kind !== id && ownField(declaration, "start_mode") === "headless";
+  if (variant && headless && reviewerOnly && fresh) return variant;
+  const roleValues = Array.isArray(roles) && !types.isProxy(roles) && roles.length <= 4 ? Array.from({ length: roles.length }, (_, index) => Object.getOwnPropertyDescriptor(roles, String(index))?.value) : [];
+  const writerRoles = roleValues.includes("implementer") && roleValues.every(role => role === "implementer" || role === "verifier");
+  return headless && writerRoles && definition?.headlessVariant ? definition.headlessVariant : definition;
 }
 export function familyOf(id: string, instances?: KindMap): string | undefined {
   return definitionOf(id, instances)?.family;
@@ -217,6 +225,7 @@ export function assertDefinitionCoherence(definition: AdapterDefinition): void {
     }
   }
   if (definition.reviewerVariant && !definition.reviewerVariant.reviewer) fail("reviewerVariant.reviewer", "reviewer variant lacks reviewer policy");
+  if (definition.headlessVariant && (definition.headlessVariant.transport !== "hub-native" || !definition.headlessVariant.start.create || definition.headlessVariant.instances?.mode !== "headless")) fail("headlessVariant", "implementer variant requires its headless hub-native factory");
   if (definition.reviewer?.unavailable && (definition.start.create || definition.reviewer.backend)) fail("reviewer", "unavailable reviewer must remain metadata-only");
 }
 
@@ -233,7 +242,10 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["routing", definition.routing !== undefined],
     ["projection", definition.projection !== undefined],
     ["instances.nativeHome", declared(definition.instances, "nativeHome")], // #685: a fixed-builtin assumption, one native data home per declared instance
+    ["identity.currentChild", declared(definition.identity, "currentChild")],
     ["reviewerVariant", definition.reviewerVariant !== undefined],
+    ["headlessVariant", definition.headlessVariant !== undefined],
+    ["start.daemonPort claude-implementer", definition.start.daemonPort === "claude-implementer"],
     ["reviewer", definition.reviewer !== undefined],
     ["hooks.factsHook", declared(definition.hooks, "factsHook")],
     ["cli.entry", declared(definition.cli, "entry")],

package/src/adapters/reviewer-print.ts

@@ -1,11 +1,33 @@
-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";
 import type { ReviewerMcpSession } from "./reviewer-mcp.ts";
 
+/** #722: the closed list of legs a reviewer's per-review start can fail on. A class names a leg, never a path, content or token. */
+export const REVIEWER_CAUSE_CLASSES = ["version", "binary", "mcp_inventory", "plugins_hooks_apps", "sandbox_proof", "credential_root", "timeout", "unknown"] as const;
+export type ReviewerCauseClass = typeof REVIEWER_CAUSE_CLASSES[number];
+const REVIEWER_CAUSE_HINT: Record<ReviewerCauseClass, string> = {
+  version: "the CLI version is neither verified nor trusted; see ahub agents",
+  binary: "the CLI binary or a watched config file could not be bound, or changed during the proof; check the configured binary and retry",
+  mcp_inventory: "the MCP server inventory or the hub server entry did not match the proof",
+  plugins_hooks_apps: "plugins, hooks or apps could not be proven disabled",
+  sandbox_proof: "the native sandbox proof did not pass",
+  credential_root: "a host credential root is unusable; remove or repair it",
+  timeout: "a proof command timed out",
+  unknown: "unclassified; inspect hub.log",
+};
+/** The one wording for the unavailable reason, the log and `ahub status`. `detail` is only ever a credential-root path class. */
+export function reviewerUnavailableReason(cause: ReviewerCauseClass, detail?: string): string {
+  return `reviewer isolation unavailable [cause: ${cause}]: ${REVIEWER_CAUSE_HINT[cause]}${detail ? ` (${detail})` : ""}`;
+}
+/** A prepare refusal that carries its class to the host; the message stays the backend's own text. */
+export class ReviewerUnavailableError extends Error {
+  constructor(message: string, readonly causeClass: ReviewerCauseClass, readonly detail?: string) { super(message); }
+}
+
 export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 export interface ReviewerIsolationReceipt {
   backend: string;
@@ -51,7 +73,7 @@ export interface ReviewerBackend {
   id: string;
   taskMcp?: true;
   nativePolicy?: true;
-  prepare(context: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string }>;
+  prepare(context: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string; causeClass?: ReviewerCauseClass; detail?: string }>;
   usage?(event: unknown): ReviewerPrintUsage | undefined;
   failure?(event: unknown): "quota" | undefined;
 }
@@ -60,6 +82,9 @@ export interface ReviewerFailure {
   head?: string;
   flowRevision?: number;
   cause: "start_failed" | "quota" | "no_verdict";
+  /** Only for `start_failed`: the leg that refused (#722). */
+  causeClass?: ReviewerCauseClass;
+  causeDetail?: string;
 }
 
 export interface ReviewerReviewBinding { readonly head?: string; readonly flowRevision?: number }
@@ -82,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 => {
@@ -93,8 +115,8 @@ const reviewTarget = (env: Envelope): ReviewTarget | undefined => {
   const revision = Number(env.refs?.reviewRevision);
   return { task, ...(typeof env.refs?.commit === "string" ? { head: env.refs.commit } : {}), ...(Number.isSafeInteger(revision) && revision > 0 ? { flowRevision: revision } : {}) };
 };
-const remainingFailures = (batch: ReviewBatch, start: number, cause: ReviewerFailure["cause"]): ReviewerFailure[] =>
-  batch.targets.slice(start).flatMap(target => target ? [{ ...target, cause }] : []);
+const remainingFailures = (batch: ReviewBatch, start: number, cause: ReviewerFailure["cause"], why?: { causeClass: ReviewerCauseClass; causeDetail?: string }): ReviewerFailure[] =>
+  batch.targets.slice(start).flatMap(target => target ? [{ ...target, cause, ...(why ? { causeClass: why.causeClass, ...(why.causeDetail ? { causeDetail: why.causeDetail } : {}) } : {}) }] : []);
 const reviewTask = (env: Envelope): number | undefined => {
   if (env.from !== HUB || env.kind !== "review") return undefined;
   const id = Number(env.refs?.task);
@@ -104,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;
@@ -217,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}`);
@@ -225,7 +246,9 @@ export class ReviewerPrintPeer extends BasePeer {
         }
         // Once an earlier review in this batch ran, the batch had effects: hold it for a person, never requeue it.
         failure = { state: started ? "needs_review" : "failed_safe", reason: `reviewer could not start: ${(error as Error).message}` };
-        reroute.push(...remainingFailures(batch, index, "start_failed"));
+        const why = error instanceof ReviewerUnavailableError ? { causeClass: error.causeClass, causeDetail: error.detail } : { causeClass: "unknown" as const };
+        this.opts.log?.(`[${this.id}] review of task #${task} could not start [cause: ${why.causeClass}]`);
+        reroute.push(...remainingFailures(batch, index, "start_failed", why));
         batch.next = envs.length;
         break;
       }
@@ -273,14 +296,14 @@ export class ReviewerPrintPeer extends BasePeer {
         mcpConfig: this.opts.backend.taskMcp ? (mcpConfig ?? '{"mcpServers":{}}') : this.opts.mcpConfig,
         systemPrompt: this.opts.systemPrompt, privatePaths: this.opts.privatePaths ?? [], command: this.opts.command, signal: abort.signal,
         ...(input === undefined ? {} : { input }), ...(task === undefined ? {} : { task }) });
-      if ("unavailable" in launch) throw new Error(launch.unavailable);
+      if ("unavailable" in launch) throw new ReviewerUnavailableError(launch.unavailable, launch.causeClass ?? "unknown", launch.detail);
       const proof = launch.isolation;
       const policy = this.opts.backend.nativePolicy
         ? proof?.enforcement === "native-policy" && proof.freshSession === true && proof.hubToolsOnly === true
         : proof?.strictMcp === true && proof.ephemeral === true;
       if (abort.signal.aborted || !proof || proof.backend !== this.opts.backend.id || proof.readOnly !== true || !policy || !proof.binary || !proof.version || !proof.profile || !proof.evidence.length || !launch.command.length) {
         await launch.cleanup?.();
-        throw new Error("reviewer isolation is unavailable or preparation was cancelled");
+        throw new ReviewerUnavailableError("reviewer isolation is unavailable or preparation was cancelled", "unknown");
       }
       return launch;
     })();
@@ -302,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 Error("reviewer isolation or admission changed before child spawn");
+    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);
@@ -376,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();
   }