@staix/agent-hub 0.14.0 → 0.16.0

package/src/hub/code-facts.ts

@@ -10,9 +10,12 @@ import { releaseTrackedClean } from "./release-worktree.ts";
 
 export interface CodeSymbol { name: string; kind: string; path: string; line: number; endLine?: number; ambiguous: boolean; change: "unknown" }
 export type CodeFactResult<T> = { state: "known"; value: T } | { state: "unknown" };
-export interface CodeLocation { repo: string; head: string; private?: boolean }
+export interface CodeLocation { repo: string; head: string; private?: boolean; priority?: "optional" }
+export const OPTIONAL_CODE_UNKNOWN_TTL_MS = 5000;
 const unknown = (): {state:"unknown"} => ({state:"unknown"});
 const SHA = /^[a-f0-9]{40}$/;
+/** These host anchor spellings have no indexed-name lookup attestation in ripwire 0.6.7. */
+export const unindexedSymbolSyntax = (name: string): boolean => /#|:|->/.test(name);
 // Keep the owned group leader alive after the CLI exits, until the host has stopped every group member.
 const LAUNCHER = String.raw`
 const {writeSync,closeSync}=require("node:fs");
@@ -76,6 +79,9 @@ function changed(raw:string,head:string,base:string,cwd:string): CodeSymbol[] {
 /** Sole optional ripwire boundary. No model/config-selected command, no raw output in results or errors. */
 export class CodeFacts {
   private readonly cache=new Map<string,Promise<CodeFactResult<unknown>>>();
+  private readonly optionalUnknown=new Map<string,number>();
+  private priorityWaiting=0;
+  private active?:{id:string;optional:boolean;cancelled:boolean;done:Promise<void>};
   private busy=false;
   private closing=false;
   private pending?:Promise<CodeFactResult<unknown>>;
@@ -83,13 +89,13 @@ export class CodeFacts {
   private failedChild?:ReturnType<typeof spawn>;
   private retained?:{tree:{cwd:string;close:()=>void};child:ReturnType<typeof spawn>};
   async close():Promise<void> {
-    this.closing=true;this.cancelActive?.();await this.pending;
+    this.closing=true;this.cancelActive?.();await (this.active?.done ?? this.pending);
     if(this.retained){
       try{await stopOwnedProcess(this.retained.child,{group:true,termMs:50,killMs:500});this.retained.tree.close();this.retained=undefined;}
       catch{throw Error("code facts cleanup unconfirmed");}
     }
   }
-  constructor(private readonly options:{env?:NodeJS.ProcessEnv;timeoutMs?:number}={}) {}
+  constructor(private readonly options:{env?:NodeJS.ProcessEnv;timeoutMs?:number;now?:()=>number}={}) {}
   private git(repo:string,args:string[]) {
     return hubGitSync(["-C",repo,...args],{encoding:"utf8",env:hubGitEnv(childEnv(),{repositoryIsolation:true}),timeout:5000,maxBuffer:1024*1024});
   }
@@ -107,7 +113,7 @@ export class CodeFacts {
     return env;
   }
   private async run(bin:string,args:string[],cwd:string):Promise<{code:number;out:string}> {
-    if(this.closing)return {code:1,out:""};
+    if(this.closing || this.active?.cancelled)return {code:1,out:""};
     return new Promise(resolve=>{
       let child:ReturnType<typeof spawn>;
       try{child=spawn(process.execPath,["-e",LAUNCHER,"--",bin,...args],{cwd,env:this.nativeEnv(cwd),detached:true,stdio:["ignore","pipe","ignore","pipe"]});}catch{resolve({code:1,out:""});return;}
@@ -164,29 +170,58 @@ export class CodeFacts {
       return{cwd,close};
     }catch{close();throw Error();}
   }
-  private query<T>(at:CodeLocation,key:string,read:(cwd:string,bin:string)=>Promise<T>):Promise<CodeFactResult<T>> {
-    if(this.closing || this.retained || at.private || !SHA.test(at.head))return Promise.resolve(unknown());
-    let repo:string;try{repo=realPath(at.repo);}catch{return Promise.resolve(unknown());}
-    const id=JSON.stringify([repo,at.head,key]),hit=this.cache.get(id);if(hit)return (hit as Promise<CodeFactResult<T>>).then(value=>structuredClone(value));
-    if(this.busy)return Promise.resolve(unknown());
-    this.busy=true;this.failedChild=undefined;
+  private async query<T>(at:CodeLocation,key:string,read:(cwd:string,bin:string)=>Promise<T>):Promise<CodeFactResult<T>> {
+    if(this.closing || this.retained || at.private || !SHA.test(at.head))return unknown();
+    const optional=at.priority==="optional";
+    // A read-time graph poll must never take the next slot from review/completion work.
+    if(optional && (this.priorityWaiting>0 || this.active && !this.active.optional))return unknown();
+    let repo:string;try{repo=realPath(at.repo);}catch{return unknown();}
+    const id=JSON.stringify([repo,at.head,key]),hit=this.cache.get(id);
+    if(hit && !(this.active?.optional && !optional && this.active.id===id))return structuredClone(await hit) as CodeFactResult<T>;
+    if(!optional && this.active?.optional) {
+      const interrupted=this.active;
+      this.priorityWaiting++;
+      interrupted.cancelled=true;this.cache.delete(interrupted.id);this.cancelActive?.();
+      try{await interrupted.done;}finally{this.priorityWaiting--;}
+      return this.query(at,key,read);
+    }
+    if(optional) {
+      const now=(this.options.now ?? performance.now.bind(performance))(),until=this.optionalUnknown.get(id);
+      if(until!==undefined && until>now)return unknown();
+      this.optionalUnknown.delete(id);
+    }
+    if(this.busy)return unknown(); // Preserve default-vs-default contention semantics.
+    let finished!:()=>void;
+    const active={id,optional,cancelled:false,done:new Promise<void>(resolve=>{finished=resolve;})};
+    this.active=active;this.busy=true;this.failedChild=undefined;
     const job=(async()=>{
       let tree:ReturnType<CodeFacts["tree"]>|undefined;let answer:CodeFactResult<T>=unknown();
       try{
         const found=Bun.which("ripwire",{PATH:(this.options.env??process.env).PATH});if(!found)throw Error();const bin=realPath(found);if(within(repo,bin))throw Error();
         tree=this.tree(repo,at.head);
-        const version=await this.run(bin,["--version"],tree.cwd);if(version.code!==0 || !/^ripwire 0\.6\.7(?:\s|$)/.test(version.out))throw Error();
+        const version=await this.run(bin,["--version"],tree.cwd);if(active.cancelled || version.code!==0 || !/^ripwire 0\.6\.7(?:\s|$)/.test(version.out))throw Error();
         const value=await read(tree.cwd,bin);
-        if(this.value(tree.cwd,["rev-parse","HEAD"])!==at.head || !releaseTrackedClean(tree.cwd,args=>{const r=this.git(tree!.cwd,args);return{code:r.status??1,stdout:r.stdout};}))throw Error();
+        if(active.cancelled || this.value(tree.cwd,["rev-parse","HEAD"])!==at.head || !releaseTrackedClean(tree.cwd,args=>{const r=this.git(tree!.cwd,args);return{code:r.status??1,stdout:r.stdout};}))throw Error();
         answer={state:"known",value};
       }catch{/* Optional derived evidence is unknown, never a review refusal. */}
-      finally{if(tree && this.failedChild){this.retained={tree,child:this.failedChild};answer=unknown();}else try{tree?.close();}catch{answer=unknown();}this.busy=false;}
+      finally{
+        if(tree && this.failedChild){this.retained={tree,child:this.failedChild};answer=unknown();}else try{tree?.close();}catch{answer=unknown();}
+        this.busy=false;if(this.active===active)this.active=undefined;finished();
+      }
       return answer;
     })();
     this.pending=job;this.cache.set(id,job);
     if(this.cache.size>128)this.cache.delete(this.cache.keys().next().value!);
-    void job.then(answer=>{if(answer.state==="unknown" && this.cache.get(id)===job)this.cache.delete(id);});
-    return job.then(value=>structuredClone(value));
+    void job.then(answer=>{
+      if(answer.state==="unknown") {
+        if(this.cache.get(id)===job)this.cache.delete(id);
+        if(optional && !this.closing) {
+          this.optionalUnknown.set(id,(this.options.now ?? performance.now.bind(performance))()+OPTIONAL_CODE_UNKNOWN_TTL_MS);
+          if(this.optionalUnknown.size>128)this.optionalUnknown.delete(this.optionalUnknown.keys().next().value!);
+        }
+      } else this.optionalUnknown.delete(id);
+    });
+    return structuredClone(await job);
   }
   changedSymbols(repo:string,base:string,head:string,options:Omit<CodeLocation,"repo"|"head">={}):Promise<CodeFactResult<CodeSymbol[]>> {
     if(!SHA.test(base))return Promise.resolve(unknown());
@@ -205,12 +240,17 @@ export class CodeFacts {
     if(v.of!==symbol || !Number.isSafeInteger(v.defs)||v.defs<1 || !Number.isSafeInteger(v.count)||v.count<0 || !Array.isArray(v[kind])||v.count!==v[kind].length || v.count>MAX_SYMBOLS || realPath(v.root)!==realPath(cwd) || ![0,1,false,true].includes(v.counts_floor)
       || !Number.isSafeInteger(v.hop_tested)||v.hop_tested<0||!Number.isSafeInteger(v.hop_untested)||v.hop_untested<0
       || !Number.isSafeInteger(v.graph_ambiguous)||v.graph_ambiguous<0||!Number.isSafeInteger(v.graph_unresolved)||v.graph_unresolved<0)throw Error();
+    if(v.defs!==1 || v.via!==undefined && v.via!=="resolved")throw Error(); // A name-only or multiply-defined seed is unknown, never a known empty neighbourhood.
     return {defs:v.defs,countsFloor:!!v.counts_floor,items:v[kind].map((s:Record<string,unknown>)=>({...cleanSymbol(s.n,s.t,s.p,s.via),ambiguous:s.via==="name" || v.defs>1 || v.graph_ambiguous>0}))};
   }
   exists(repo:string,head:string,symbol:string,options:Omit<CodeLocation,"repo"|"head">={}):Promise<CodeFactResult<{exists:boolean;ambiguous:boolean}>> {
     if(!text(symbol))return Promise.resolve(unknown());
     return this.query({...options,repo,head},`exists:${symbol}`,async(cwd,bin)=>{const r=await this.run(bin,[cwd,`--callers=${symbol}`,"--no-cache"],cwd);
-      if(r.code!==0){const n=xml(r.out);if(n.tag==="callers" && n.attrs.schema==="ripwire.callers/v1" && n.attrs.of===symbol && n.attrs.found==="0")return{exists:false,ambiguous:false};throw Error();}
+      if(r.code!==0){const n=xml(r.out);if(n.tag==="callers" && n.attrs.schema==="ripwire.callers/v1" && n.attrs.of===symbol && n.attrs.found==="0") {
+        // ponytail: ripwire 0.6.7 can miss a qualified name whose bare method exists. Require a CLI/schema qualified-lookup attestation before trusting its absence.
+        if(symbol.includes(".") || unindexedSymbolSyntax(symbol))throw Error();
+        return{exists:false,ambiguous:false};
+      }throw Error();}
       const n=xml(r.out);if(n.tag!=="callers" || n.attrs.schema!=="ripwire.callers/v1" || n.attrs.of!==symbol || !integer(n.attrs.defs)||Number(n.attrs.defs)<1)throw Error();return{exists:true,ambiguous:n.attrs.via==="name" || Number(n.attrs.defs)>1};});
   }
   neighbours(repo:string,head:string,symbol:string,depth=1,options:Omit<CodeLocation,"repo"|"head">={}):Promise<CodeFactResult<{callers:CodeSymbol[];callees:CodeSymbol[];hiddenAmbiguous:number;countsFloor:boolean}>> {

package/src/hub/conductor.ts

@@ -9,6 +9,7 @@ import type { StartMode } from "./start-mode.ts";
 import type { HubEvent } from "./events.ts";
 import type { SupervisionFeed } from "./supervision.ts";
 import type { Budget } from "./budget.ts";
+import { windowKind, type WindowKind } from "./window-kind.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { supportsHeadlessInstances } from "./instances.ts";
 
@@ -17,9 +18,11 @@ export function conductorProgressSink(record: (event: HubEvent) => void, feed: P
   return event => { record(event); if (event.type === "stuck") feed.milestone(event.task, "stuck", { reason: event.category }); };
 }
 
-export function publicPeerBudget(status: ReturnType<Budget["status"]>, nameable: (text: string) => boolean): Record<string, unknown> {
+/** What `Budget.status` returns, with the fields added after it optional so an older shape still projects. */
+type PublicBudgetStatus = Record<string, { windows: (Omit<ReturnType<Budget["status"]>[string]["windows"][number], "kind" | "superseded"> & { kind?: WindowKind; superseded?: boolean })[]; paused?: ReturnType<Budget["status"]>[string]["paused"] }>;
+export function publicPeerBudget(status: PublicBudgetStatus, nameable: (text: string) => boolean): Record<string, unknown> {
   return Object.fromEntries(Object.entries(status).map(([peer, value]) => [peer, {
-    windows: value.windows.map(window => ({ id: window.id, used: window.used, at: window.at, stale: window.stale,
+    windows: value.windows.map(window => ({ id: window.id, kind: windowKind(window), used: window.used, at: window.at, stale: window.stale, ...(window.superseded ? { superseded: true } : {}),
       ...(window.resetsAt === undefined ? {} : { resetsAt: window.resetsAt }),
       ...(window.windowMins === undefined ? {} : { windowMins: window.windowMins }),
       source: nameable(window.source) ? window.source : "[quota source withheld]",

package/src/hub/config-apply.ts

@@ -5,6 +5,7 @@ import { externalMetadataDefinitions, type ExternalAdapterMetadata } from "../ad
 import { reviewerPoolConfig } from "./reviewer-pool-config.ts";
 import type { HubConfig } from "./daemon.ts";
 import { ALL_MACHINE_LOCAL, configRepositoryPresent, configTracked } from "./config-trust.ts";
+import { structuralLeaf } from "./config-tier.ts";
 import { createProjectAdapterCatalog, type ProjectAdapterCatalog, ADAPTERS, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS, SUPPORTED_PEERS, PLANNER_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
 import { CLASSES } from "./board.ts";
 import { permissionDefaults } from "./permission-mode.ts";
@@ -16,6 +17,7 @@ import { projectionConfig } from "./text-projection.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
 import { peerRosterConfig, staleInstanceKey } from "./roster.ts";
 import { CHARACTER_IDS } from "../pet/characters.ts";
+import { checkSettingValue, settingDef } from "./settings.ts";
 import { petPalette } from "../pet/config.ts";
 
 export type ApplyClass = "live" | "next use" | "restart";
@@ -44,6 +46,8 @@ export interface ConfigAuthorizationInput {
   acceptedFallback?: boolean;
   /** The prospective settled planner/conductor holder sets change, even if the raw role list shrinks. */
   settledHolderChange?: boolean;
+  /** #689: the daemon sets this only for a structural edit it validated and wrote itself; `structuralLeaf` still decides the key. */
+  structural?: boolean;
   guard?: ReloadGuard;
 }
 export interface ConfigAuthorizationDecision { key: string; allowed: boolean; guarded: boolean; reason: string }
@@ -90,6 +94,8 @@ export function authorizeConfigLeaf(input: ConfigAuthorizationInput): ConfigAuth
   // Every other policy change is conservative: person intent never turns tracked or unknown code into host authority.
   if (input.tracked !== false) return result(false, true, input.tracked ? "guarded source is tracked; retain the running value" : "guarded source trust is unknown; retain the running value");
   if (input.authority === "ordinary") return result(false, true, "guarded change needs a selected setting or a confirmed terminal reload");
+  // #689: a structural key (never an executable or secret one) written by the daemon's own validated edit, from a settings session.
+  if (input.authority === "settings" && !guard && input.structural === true && input.confirmed === true && input.source === "config" && input.sourceFile === "config.local.json" && structuralLeaf(key)) return result(true, true, "confirmed structural edit");
   if (input.authority === "settings" && !guard) return result(false, true, "nonregistered policy requires a confirmed terminal reload");
   if (input.confirmed !== true) return result(false, true, "guarded change needs explicit confirmation for this key");
   return result(true, true, guard ? "confirmed registered setting" : "confirmed terminal reload");
@@ -184,6 +190,12 @@ export function validateRawConfig(raw: unknown, declarations?: InstancesConfig,
   const instances = validateInstances(value.instances ?? declarations, catalog);
   block({ ...schema,
     instances: v => { validateInstances(v, catalog); },
+    planner: v => {
+      if (v === null) fail("config.planner", "takes a peer id or a nonempty list");
+      const def = settingDef("planner", instances, catalog);
+      if (typeof def === "string") return fail("config.planner", def);
+      checkSettingValue(def, v);
+    },
     permission_modes: v => { permissionDefaults(v, instances, catalog); },
     roster: v => { peerRosterConfig(v, instances, catalog, inertModuleRoster); },
     peers: v => { peerStartConfig(v, instances, catalog); },

package/src/hub/config-edit-host.ts

@@ -0,0 +1,173 @@
+import { configBackups, parseConfigEditRequest, viewRevisions, planConfigEdit, writeConfigEdit, type CandidateCheck, type ConfigEditPlan } from "./config-edit.ts";
+import { configTier, maskTier3, TIER2_INSTANCE_FIELDS, TIER3_INSTANCE_FIELDS, TIER3_PREFIXES, type ConfigEditFile } from "./config-tier.ts";
+import type { HubEvent } from "./events.ts";
+
+/**
+ * #689: the daemon's side of structural config edits. Everything the daemon decides is here, with its ports injected, so the
+ * daemon itself carries only a few lines of wiring: who may edit (authority), the typed confirmation for tier 3, the hold during
+ * recovery or shutdown, the audit event and the scoped reload that applies or marks each key.
+ */
+export type EditAuthority = "ordinary" | "settings" | "terminal";
+export interface ConfigEditHost {
+  cwd: string;
+  stateDir: string;
+  /** The loaders' verdict on a candidate file; throws the loader's reason. */
+  check: CandidateCheck;
+  /** A reason edits are held now (recovery or shutdown), or undefined. */
+  held: () => string | undefined;
+  /** Publishes one changed key through the daemon's only reload path, scoped to it. */
+  reload: (authority: EditAuthority, key: string) => Promise<Record<string, unknown>>;
+  event: (event: Extract<HubEvent, { type: "config_edit" }>) => void;
+  notify: (text: string) => void;
+  /** Called after a write so status.json and the console snapshot show what is now pending. */
+  changed: () => void;
+  /** What waits for a restart now, from the reload's own bookkeeping (instance declarations are restart-bound). */
+  pending: () => { key: string; reason: string }[];
+  /** The running hub's value at a config path, for the form. */
+  effective: (path: readonly string[]) => unknown;
+  /** The lifecycle the running hub holds, to say what a changed sdlc.toml waits for. */
+  runningSdlc: () => { mode: string; requiredChecks: readonly string[] };
+  /** The lifecycle the file would give at the next start, or the loader's reason. */
+  fileSdlc: () => { mode: string; requiredChecks: readonly string[] } | string;
+  /** The declared instances of the running hub: id to its tier 2 fields. */
+  declared: () => Record<string, Record<string, unknown>>;
+  /** config.local.json as the file holds it now, parsed once per call (`{}` when it is missing or unreadable). Never sent anywhere: it is read for what is set, never shown. */
+  localConfig: () => Record<string, unknown>;
+}
+export interface ConfigEditView {
+  revisions: Record<ConfigEditFile, string>;
+  instances: { id: string; fields: Record<string, unknown>; tier3: string[] }[];
+  /** The instance ids config.local.json holds now, including ones the running hub has not started with yet: the forms change those leaf by leaf. */
+  known: string[];
+  blocks: { path: string; value: unknown }[];
+  sdlc: { mode: string; requiredChecks: readonly string[]; pending: boolean; problem?: string };
+  /** Tier 3 keys with the console command that changes them; the dashboard shows exactly this, read-only. */
+  tier3: { key: string; set: boolean; command: string }[];
+  backups: { name: string; file: ConfigEditFile; at: number; bytes: number }[];
+  fields: { instance: readonly string[]; tier3Instance: readonly string[] };
+}
+const REASON_BYTES = 400;
+const BLOCKS: readonly (readonly string[])[] = [["review", "adaptive"], ["review", "min_reviews"], ["review", "pool"], ["review", "rerotate"], ["snapshots", "keep"], ["approvals", "timeout_s"], ["context", "gate"]];
+
+export const CONFIG_EDIT_OPS = ["config_edit_get", "config_edit_preview", "config_edit_apply"] as const;
+
+export function createConfigEditor(host: ConfigEditHost) {
+  const sdlcPending = (): boolean => {
+    const file = host.fileSdlc(), running = host.runningSdlc();
+    return typeof file !== "string" && (file.mode !== running.mode || JSON.stringify(file.requiredChecks) !== JSON.stringify(running.requiredChecks));
+  };
+  /** What a changed sdlc.toml waits for: shown with the other pending restarts. */
+  const sdlcRestart = (): { key: string; reason: string }[] => {
+    const file = host.fileSdlc(), running = host.runningSdlc();
+    if (typeof file === "string") return [];
+    return [...(file.mode !== running.mode ? [{ key: "sdlc.mode", reason: "the lifecycle is read once at hub start" }] : []),
+      ...(JSON.stringify(file.requiredChecks) !== JSON.stringify(running.requiredChecks) ? [{ key: "sdlc.required_checks", reason: "the lifecycle is read once at hub start" }] : [])];
+  };
+  const pendingRestart = (): { key: string; reason: string }[] => sdlcRestart();
+  const allPending = (): string[] => [...host.pending().map(row => row.key), ...sdlcRestart().map(row => row.key)];
+  function view(): ConfigEditView {
+    const file = host.fileSdlc(), running = host.runningSdlc();
+    let local: Record<string, unknown> = {};
+    try { local = host.localConfig(); } catch { /* the revisions say the file is unavailable */ }
+    const fileInstances = local.instances && typeof local.instances === "object" && !Array.isArray(local.instances) ? Object.keys(local.instances) : [];
+    const isSet = (path: readonly string[]): boolean => { let node: unknown = local; for (const part of path) { if (!node || typeof node !== "object" || !Object.hasOwn(node, part)) return false; node = (node as Record<string, unknown>)[part]; } return node !== undefined; };
+    const declared = host.declared();
+    return {
+      revisions: viewRevisions(host.cwd),
+      known: fileInstances,
+      instances: Object.entries(declared).map(([id, fields]) => ({ id, fields: Object.fromEntries(TIER2_INSTANCE_FIELDS.filter(field => fields[field] !== undefined).map(field => [field, fields[field]])),
+        tier3: TIER3_INSTANCE_FIELDS.filter(field => fields[field] !== undefined) as string[] })),
+      blocks: BLOCKS.map(path => ({ path: path.join("."), value: host.effective(path) ?? null })),
+      sdlc: { mode: running.mode, requiredChecks: running.requiredChecks, pending: sdlcPending(), ...(typeof file === "string" ? { problem: file } : {}) },
+      tier3: [...TIER3_PREFIXES.map(key => ({ key, set: isSet(key.split(".")), command: `ahub settings edit config.local.json set ${key} <json>` })),
+        ...Object.entries(declared).flatMap(([id, fields]) => TIER3_INSTANCE_FIELDS.filter(field => fields[field] !== undefined).map(field => ({ key: `instances.${id}.${field}`, set: true, command: `ahub settings edit config.local.json set instances.${id}.${field} <json>` })))],
+      backups: configBackups(host.stateDir).slice(0, 10),
+      fields: { instance: TIER2_INSTANCE_FIELDS, tier3Instance: TIER3_INSTANCE_FIELDS },
+    };
+  }
+  /** A refusal before any loader runs: an unauthorized or unclassifiable request learns nothing about the project. */
+  function authorize(raw: unknown, authority: EditAuthority): { ok: true; tier3: string[] } | { ok: false; error: string } {
+    if (authority === "ordinary") return { ok: false, error: "structural config edits need a settings session: open one with ahub ui --settings, or use the console" };
+    const request = parseConfigEditRequest(raw);
+    if (typeof request === "string") return { ok: false, error: request };
+    const tier3: string[] = [];
+    for (const { path, value } of request.set) {
+      const tier = configTier(request.file, path, value);
+      if ("refused" in tier) return { ok: false, error: tier.refused };
+      if (tier.tier === 3) tier3.push(tier.key);
+    }
+    if (tier3.length && authority !== "terminal") return { ok: false, error: `${tier3[0]} chooses what the hub runs or where secrets go: it is never editable from the dashboard; change it in the console (ahub settings edit config.local.json set ${tier3[0]} <json>)` };
+    if (tier3.length > 1) return { ok: false, error: "change one executable or secret-locating key at a time: each needs its own typed confirmation" };
+    return { ok: true, tier3 };
+  }
+  function planned(raw: unknown, authority: EditAuthority): { ok: true; plan: Extract<ConfigEditPlan, { ok: true }> } | { ok: false; error: string; field?: string } {
+    const allowed = authorize(raw, authority);
+    if (!allowed.ok) return allowed;
+    const held = host.held();
+    if (held) return { ok: false, error: `${held} is holding config edits` };
+    const plan = planConfigEdit(host.cwd, raw, host.check);
+    if (!plan.ok) return plan;
+    // The plan reads the file itself: if it finds a tier 3 key the request alone did not show, a dashboard still learns nothing.
+    if (plan.tier === 3 && authority !== "terminal") return { ok: false, error: `${plan.tier3Keys[0]} chooses what the hub runs or where secrets go: it is never editable from the dashboard; change it in the console` };
+    // The request names some tier 3 keys and the file adds others (an instance it holds a home for): one write changes exactly one, and each is typed.
+    if (plan.tier3Keys.length > 1) return { ok: false, error: "change one executable or secret-locating key at a time: each needs its own typed confirmation" };
+    return { ok: true, plan };
+  }
+  function diffText(plan: Extract<ConfigEditPlan, { ok: true }>): string[] {
+    const show = (path: string, value: unknown): string => { const masked = maskTier3(path.split("."), value); return masked === undefined ? "(unset)" : JSON.stringify(masked); };
+    return plan.diff.map(row => `${row.path}: ${show(row.path, row.before)} -> ${show(row.path, row.after)} (${row.applies === "restart" ? "pending restart" : "applies at next use"})`);
+  }
+  function preview(raw: unknown, authority: EditAuthority): Record<string, unknown> {
+    const result = planned(raw, authority);
+    if (!result.ok) return { ok: false, error: result.error, ...(result.field ? { field: result.field } : {}) };
+    const { plan } = result;
+    return { ok: true, file: plan.request.file, revision: plan.request.revision, tier: plan.tier, lines: [...diffText(plan), ...plan.notes],
+      diff: plan.diff.map(row => ({ path: row.path, tier: row.tier, applies: row.applies, before: maskTier3(row.path.split("."), row.before) ?? null, after: maskTier3(row.path.split("."), row.after) ?? null })),
+      ...(plan.tier === 3 ? { confirm: plan.tier3Keys[0], warning: "this runs code with the daemon's rights, or chooses where secrets are read from" } : {}) };
+  }
+  async function apply(raw: unknown, authority: EditAuthority, confirm?: unknown, rawReason?: unknown): Promise<Record<string, unknown>> {
+    let reason: string | undefined;
+    if (rawReason !== undefined) {
+      if (typeof rawReason !== "string" || !rawReason.trim() || Buffer.byteLength(rawReason) > REASON_BYTES) return { ok: false, error: `reason must contain 1..${REASON_BYTES} UTF-8 bytes` };
+      reason = rawReason.trim().replace(/[\x00-\x1f\x7f]/g, " ");
+    }
+    const result = planned(raw, authority);
+    if (!result.ok) return { ok: false, error: result.error, ...(result.field ? { field: result.field } : {}) };
+    const { plan } = result;
+    if (plan.tier === 3 && confirm !== plan.tier3Keys[0]) return { ok: false, error: `${plan.tier3Keys[0]} runs code with the daemon's rights or locates secrets: type the key name to confirm; nothing was written`, confirm: plan.tier3Keys[0] };
+    let written: ReturnType<typeof writeConfigEdit>;
+    try { written = writeConfigEdit(host.cwd, host.stateDir, plan); }
+    catch (error) { return { ok: false, error: `${(error as Error).message}; nothing was changed` }; }
+    const source = authority === "terminal" ? "terminal" as const : "dashboard" as const;
+    host.event({ type: "config_edit", file: plan.request.file, paths: written.paths, fileBefore: written.fileBefore, fileAfter: written.fileAfter, tier: plan.tier, by: "person", source, ...(written.backup ? { backup: written.backup } : {}), ...(reason ? { reason } : {}) });
+    try { host.notify(`config edit: ${plan.request.file} ${plan.diff.map(row => row.path).join(", ")} (${source})`); } catch { /* the write stands */ }
+    const settled = () => { try { host.changed(); } catch { /* the write stands; the next status write shows it */ } };
+    if (plan.request.file === "sdlc.toml") { settled(); return { ok: true, saved: true, ...(written.backup ? { backup: written.backup } : {}), lines: diffText(plan), text: `sdlc.toml written; the lifecycle is read once at hub start: restart pending`, restartPending: allPending() }; }
+    const failures: string[] = [];
+    for (const key of leafKeys(plan)) {
+      let reloaded: Record<string, unknown>;
+      try { reloaded = await host.reload(authority, key); } catch { reloaded = { ok: false, error: "the change was saved but could not be published; inspect hub.log" }; }
+      if (reloaded.ok !== true) failures.push(`${key}: ${String(reloaded.error ?? "not published")}`);
+    }
+    settled();
+    if (failures.length) return { ok: false, saved: true, error: `saved, but not published: ${failures.join("; ")}; run ahub settings reload to review it`, ...(written.backup ? { backup: written.backup } : {}) };
+    return { ok: true, saved: true, ...(written.backup ? { backup: written.backup } : {}), lines: diffText(plan), text: `config.local.json written: ${plan.diff.map(row => row.path).join(", ")}${plan.diff.some(row => row.applies === "restart") ? "; restart pending" : ""}`, restartPending: allPending() };
+  }
+  return { view, preview, apply, pendingRestart };
+}
+
+/** The leaf keys a plan changed, so each is published through its own scoped reload. */
+function leafKeys(plan: Extract<ConfigEditPlan, { ok: true }>): string[] {
+  const out = new Set<string>();
+  const walk = (prefix: string, before: unknown, after: unknown): void => {
+    const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+    if (object(before) || object(after)) {
+      const old = object(before) ? before : {}, next = object(after) ? after : {};
+      for (const key of new Set([...Object.keys(old), ...Object.keys(next)])) walk(`${prefix}.${key}`, old[key], next[key]);
+      return;
+    }
+    if (JSON.stringify(before ?? null) !== JSON.stringify(after ?? null)) out.add(prefix);
+  };
+  for (const row of plan.diff) walk(row.path, row.before, row.after);
+  return [...out];
+}