@staix/agent-hub 0.14.0 → 0.15.0

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";
@@ -44,6 +45,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 +93,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");

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];
+}

package/src/hub/config-edit.ts

@@ -0,0 +1,282 @@
+import { createHash } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configRepositoryPresent, configTracked } from "./config-trust.ts";
+import { configTier, CONFIG_EDIT_FILES, type ConfigEditFile } from "./config-tier.ts";
+import { sdlcConfig } from "./sdlc.ts";
+import { VERSION } from "../version.ts";
+
+/**
+ * #689: structural config edits. This module is pure file work plus the loaders' verdict: it never publishes, never
+ * touches the board and never reads a secret. The daemon owns authority, events and reload (src/hub/daemon.ts).
+ */
+export interface ConfigEditSet { path: string[]; /** `null` removes the key. */ value: unknown }
+export interface ConfigEditRequest { file: ConfigEditFile; /** The file's revision as the form read it: a sha256, or `absent`. */ revision: string; set: ConfigEditSet[] }
+export interface ConfigDiffRow { path: string; tier: 2 | 3; before: unknown; after: unknown; applies: "restart" | "next use" }
+export type ConfigEditPlan =
+  | { ok: true; request: ConfigEditRequest; before: string | null; next: string | null; diff: ConfigDiffRow[]; tier: 2 | 3; tier3Keys: string[]; tracked?: boolean; notes: string[] }
+  | { ok: false; error: string; field?: string };
+/** The loaders' verdict on a candidate file text, thrown as the reason. `null` is a file that would not exist. */
+export type CandidateCheck = (file: ConfigEditFile, text: string | null) => void;
+
+export const MAX_EDIT_SETS = 16;
+export const MAX_VALUE_BYTES = 16 * 1024;
+const MAX_FILE_BYTES: Record<ConfigEditFile, number> = { "config.local.json": 1024 * 1024, "sdlc.toml": 64 * 1024 };
+export const BACKUPS_KEPT = 5;
+const isObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const sha = (text: string): string => createHash("sha256").update(text).digest("hex");
+export const fileRevision = (text: string | null): string => text === null ? "absent" : sha(text);
+/** A short, stable hash of a value for the audit event: the value itself never enters it. */
+export const valueHash = (value: unknown): string | null => value === undefined ? null : sha(JSON.stringify(canonical(value))).slice(0, 16);
+const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical) : isObject(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(canonical(a) ?? null) === JSON.stringify(canonical(b) ?? null);
+
+/** The field a loader's reason names, so a form can show it at that field. */
+export function reasonField(message: string): string | undefined {
+  return /\b(instances\.[a-z][a-z0-9-]*(?:\.[A-Za-z_]+)?|review\.[a-z_]+|snapshots\.[a-z_]+|approvals\.[a-z_]+|context\.[a-z_]+|sdlc\.[a-z_]+)\b/.exec(message)?.[1];
+}
+
+/** The file's text, or null when it is not there. A failure is named by its code: its own text holds absolute paths. */
+export function readEditable(cwd: string, file: ConfigEditFile): string | null {
+  // Only the last component used to be checked: a committed `.agenthub` symlink would have been read and written through.
+  try { if (!lstatSync(join(cwd, ".agenthub")).isDirectory()) throw new Error(".agenthub must be a real directory, not a link"); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; if (/must be a real directory/.test((error as Error).message)) throw error; throw new Error(`.agenthub could not be read (${(error as NodeJS.ErrnoException).code ?? "unknown error"})`); }
+  const path = join(cwd, ".agenthub", file);
+  try {
+    const info = lstatSync(path);
+    if (!info.isFile()) throw Object.assign(new Error("not a regular file"), { code: "EMLINK" });
+    if (info.size > MAX_FILE_BYTES[file]) throw Object.assign(new Error("too large"), { code: "EFBIG" });
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return null;
+    throw new Error(`.agenthub/${file} could not be read (${code ?? "unknown error"}): it must be a regular file inside its size limit`);
+  }
+}
+/** The revisions for a view: a file that cannot be read safely is `unavailable`, so one bad file never takes the whole Settings view down. */
+export const viewRevisions = (cwd: string): Record<ConfigEditFile, string> => Object.fromEntries(CONFIG_EDIT_FILES.map(file => { try { return [file, fileRevision(readEditable(cwd, file))]; } catch { return [file, "unavailable"]; } })) as Record<ConfigEditFile, string>;
+export const editRevisions = (cwd: string): Record<ConfigEditFile, string> => Object.fromEntries(CONFIG_EDIT_FILES.map(file => [file, fileRevision(readEditable(cwd, file))])) as Record<ConfigEditFile, string>;
+
+/** Strict shape of an untrusted request: unknown fields are refused, never dropped. */
+export function parseConfigEditRequest(raw: unknown): ConfigEditRequest | string {
+  if (!isObject(raw)) return "a config edit is an object with file, revision and set";
+  const extra = Object.keys(raw).find(key => !["file", "revision", "set"].includes(key));
+  if (extra) return `${extra}: unknown field; nothing was written`;
+  if (!CONFIG_EDIT_FILES.includes(raw.file as ConfigEditFile)) return `file: one of ${CONFIG_EDIT_FILES.join(", ")}`;
+  if (typeof raw.revision !== "string" || !/^(absent|[a-f0-9]{64})$/.test(raw.revision)) return "revision: the file revision the form read (reload and try again)";
+  if (!Array.isArray(raw.set) || !raw.set.length || raw.set.length > MAX_EDIT_SETS) return `set: 1 to ${MAX_EDIT_SETS} entries`;
+  const set: ConfigEditSet[] = [];
+  for (const [index, entry] of raw.set.entries()) {
+    if (!isObject(entry)) return `set[${index}]: an object with path and value`;
+    const unknown = Object.keys(entry).find(key => !["path", "value"].includes(key));
+    if (unknown) return `set[${index}].${unknown}: unknown field; nothing was written`;
+    if (!Array.isArray(entry.path) || !entry.path.length || entry.path.length > 6 || entry.path.some(part => typeof part !== "string")) return `set[${index}].path: 1 to 6 strings`;
+    if (!("value" in entry)) return `set[${index}].value: required (null removes the key)`;
+    let size: number;
+    try { size = Buffer.byteLength(JSON.stringify(entry.value) ?? "undefined"); } catch { return `set[${index}].value: must be plain JSON`; }
+    if (size > MAX_VALUE_BYTES) return `set[${index}].value: at most ${MAX_VALUE_BYTES} bytes`;
+    set.push({ path: [...entry.path as string[]], value: entry.value });
+  }
+  if (new Set(set.map(item => item.path.join("."))).size !== set.length) return "set: a path appears twice";
+  return { file: raw.file as ConfigEditFile, revision: raw.revision, set };
+}
+
+function valueAt(doc: unknown, path: readonly string[]): unknown {
+  let node = doc;
+  for (const part of path) { if (!isObject(node) || !Object.hasOwn(node, part)) return undefined; node = node[part]; }
+  return node;
+}
+/** Sets (or with null removes) one path; an emptied parent goes with it, so set then remove leaves the file as it was. */
+function putPath(doc: Record<string, unknown>, path: readonly string[], value: unknown): void {
+  const trail: [Record<string, unknown>, string][] = [];
+  let node = doc;
+  for (const part of path.slice(0, -1)) {
+    if (!Object.hasOwn(node, part)) { if (value === null) return; node[part] = {}; }
+    const next = node[part];
+    if (!isObject(next)) throw new Error(`${path.slice(0, path.indexOf(part) + 1).join(".")} is not an object in the file; fix it in your editor first`);
+    trail.push([node, part]); node = next;
+  }
+  const leaf = path.at(-1)!;
+  if (value === null) {
+    delete node[leaf];
+    for (const [parent, part] of trail.reverse()) { if (Object.keys(parent[part] as object).length) break; delete parent[part]; }
+  } else node[leaf] = structuredClone(value);
+}
+
+/** TOML top-level keys `mode` and `required_checks`, edited line by line so comments and every other table survive. */
+function tomlValue(key: string, value: unknown): string {
+  if (key === "mode") return `mode = ${JSON.stringify(value)}`;
+  return `required_checks = [${(value as string[]).map(check => JSON.stringify(check)).join(", ")}]`;
+}
+const bracketDelta = (line: string): number => {
+  const bare = line.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, "").replace(/#.*$/, "");
+  return [...bare].reduce((sum, ch) => sum + (ch === "[" ? 1 : ch === "]" ? -1 : 0), 0);
+};
+/** The top-level key spans of a TOML file (before the first table header); a multi-line array keeps its lines together. */
+function topLevel(lines: readonly string[]): { end: number; spans: Map<string, [number, number]> } {
+  const spans = new Map<string, [number, number]>();
+  let end = lines.length;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index]!;
+    if (/^\s*\[/.test(line)) { end = index; break; }
+    const key = /^\s*([A-Za-z0-9_-]+)\s*=/.exec(line)?.[1];
+    if (!key) continue;
+    let last = index, depth = bracketDelta(line.slice(line.indexOf("=") + 1));
+    while (depth > 0 && last + 1 < lines.length) depth += bracketDelta(lines[++last]!);
+    spans.set(key, [index, last]);
+    index = last;
+  }
+  return { end, spans };
+}
+/**
+ * Edits `mode` and `required_checks` line by line. Every line the edit does not touch keeps its own ending, so a one-key change never
+ * rewrites a CRLF checkout; a line the edit writes or adds takes the ending of the first line break the file has (LF for a new file).
+ */
+function editSdlcText(text: string | null, set: ConfigEditSet[]): string | null {
+  const raw = text === null ? [] : text.split("\n");
+  const trailing = raw.length > 0 && raw.at(-1) === "";
+  if (trailing) raw.pop();
+  // Parallel arrays: the line's text and the ending it had. A line that was the file's last may have had none.
+  const lines = raw.map(line => line.endsWith("\r") ? line.slice(0, -1) : line);
+  const endings = raw.map((line, index) => line.endsWith("\r") ? "\r\n" : index === raw.length - 1 && !trailing ? "" : "\n");
+  const own = text !== null && /\r?\n/.exec(text)?.[0] === "\r\n" ? "\r\n" : "\n";
+  for (const { path, value } of set) {
+    const key = path[0]!, { end, spans } = topLevel(lines), found = spans.get(key);
+    if (found) {
+      const fresh = value === null ? [] : [tomlValue(key, value)];
+      const last = endings[found[1]]!;
+      lines.splice(found[0], found[1] - found[0] + 1, ...fresh);
+      endings.splice(found[0], found[1] - found[0] + 1, ...fresh.map(() => last === "" ? own : last));
+    } else if (value !== null) {
+      // A new key goes after the last top-level line, before the first table.
+      let at = end;
+      while (at > 0 && !lines[at - 1]!.trim()) at--;
+      lines.splice(at, 0, tomlValue(key, value)); endings.splice(at, 0, own);
+      if (at > 0 && endings[at - 1] === "") endings[at - 1] = own;
+      if (at + 1 < lines.length && lines[at + 1]!.trim() !== "" && /^\s*\[/.test(lines[at + 1]!)) { lines.splice(at + 1, 0, ""); endings.splice(at + 1, 0, own); }
+    }
+  }
+  if (!lines.length) return null;
+  return lines.map((line, index) => line + (endings[index] === "" && index === lines.length - 1 ? own : endings[index])).join("");
+}
+const parseToml = (text: string | null): Record<string, unknown> => text === null ? {} : Bun.TOML.parse(text) as Record<string, unknown>;
+
+/**
+ * What the request would do, judged by the loaders before anything is written. The result carries the diff and the
+ * candidate text; nothing has been written. A refusal names the key (`field`) when the loader's reason does.
+ */
+export function planConfigEdit(cwd: string, rawRequest: unknown, check: CandidateCheck): ConfigEditPlan {
+  const request = parseConfigEditRequest(rawRequest);
+  if (typeof request === "string") return { ok: false, error: request };
+  try {
+    const before = readEditable(cwd, request.file);
+    if (fileRevision(before) !== request.revision) return { ok: false, error: `.agenthub/${request.file} changed on disk since it was read: reload it and review the change again; nothing was written` };
+    const diff: ConfigDiffRow[] = [], tier3Keys: string[] = [];
+    let next: string | null;
+    if (request.file === "sdlc.toml") {
+      for (const { path, value } of request.set) {
+        const tier = configTier("sdlc.toml", path, value);
+        if ("refused" in tier) return { ok: false, error: tier.refused, field: `sdlc.${path.join(".")}` };
+        if (path[0] === "mode" && value !== null && !["off", "advise", "enforce"].includes(String(value))) return { ok: false, error: "sdlc.mode: expected off, advise or enforce; nothing was written", field: "sdlc.mode" };
+        if (path[0] === "required_checks" && value !== null && !Array.isArray(value)) return { ok: false, error: "sdlc.required_checks: expected a list of check names; nothing was written", field: "sdlc.required_checks" };
+      }
+      const old = parseToml(before);
+      next = editSdlcText(before, request.set);
+      const after = parseToml(next);
+      const expected = structuredClone(old);
+      for (const { path, value } of request.set) putPath(expected, path, value);
+      // A layout this edit cannot keep byte-faithful is refused rather than guessed: only the named keys may differ.
+      if (!same(after, expected)) return { ok: false, error: "sdlc.toml has a layout the editor cannot change safely (a key repeated, or one split across tables); edit .agenthub/sdlc.toml in your editor; nothing was written" };
+      sdlcConfig(after, VERSION); // the loader's own verdict, with its field-level reason
+      for (const { path, value } of request.set) diff.push({ path: `sdlc.${path.join(".")}`, tier: 2, before: old[path[0]!], after: value === null ? undefined : value, applies: "restart" });
+      check("sdlc.toml", next);
+    } else {
+      let doc: Record<string, unknown>;
+      try { doc = before === null ? {} : JSON.parse(before); } catch { return { ok: false, error: ".agenthub/config.local.json is not valid JSON; fix it in your editor first; nothing was written" }; }
+      if (!isObject(doc)) return { ok: false, error: ".agenthub/config.local.json must hold a JSON object; nothing was written" };
+      const old = structuredClone(doc);
+      for (const { path, value } of request.set) {
+        const held = valueAt(old, path);
+        const tier = configTier("config.local.json", path, value, held);
+        if ("refused" in tier) return { ok: false, error: tier.refused, field: path.join(".") };
+        if (tier.tier === 3) tier3Keys.push(tier.key);
+        // A whole instance replaced by a tier 2 object must not drop a tier 3 field it held: that would silently erase a home or account.
+        if (path[0] === "instances" && path.length === 2 && isObject(held) && isObject(value)) {
+          const lost = Object.keys(held).find(field => !(field in value) && ["jcode_home", "provider", "model", "provider_profile"].includes(field));
+          if (lost) return { ok: false, error: `instances.${path[1]}.${lost}: this replacement would drop a native home or account setting; set only the fields you change (instances.${path[1]}.<field>); nothing was written`, field: `instances.${path[1]}.${lost}` };
+        }
+        putPath(doc, path, value);
+        diff.push({ path: path.join("."), tier: tier.tier, before: held, after: value === null ? undefined : value, applies: path[0] === "instances" ? "restart" : "next use" });
+      }
+      next = Object.keys(doc).length || before !== null ? `${JSON.stringify(doc, null, 2)}\n` : null;
+      if (Buffer.byteLength(next ?? "") > MAX_FILE_BYTES["config.local.json"]) return { ok: false, error: ".agenthub/config.local.json would exceed its size limit; nothing was written" };
+      check("config.local.json", next);
+    }
+    const changed = diff.filter(row => !same(row.before, row.after));
+    if (!changed.length) return { ok: false, error: "nothing to change: the file already holds this; nothing was written" };
+    const tracked = request.file === "config.local.json" ? undefined : configTracked(cwd, "sdlc.toml");
+    const notes = request.file === "sdlc.toml" && tracked ? [".agenthub/sdlc.toml is tracked by git: the change is in your working tree, commit it to share it"] : [];
+    return { ok: true, request, before, next, diff: changed, tier: tier3Keys.length ? 3 : 2, tier3Keys: [...new Set(tier3Keys)], ...(tracked === undefined ? {} : { tracked }), notes };
+  } catch (error) {
+    const message = (error as Error).message;
+    return { ok: false, error: `${message}; nothing was written`, ...(reasonField(message) ? { field: reasonField(message) } : {}) };
+  }
+}
+
+const backupDir = (stateDir: string): string => join(stateDir, "config-backups");
+export interface ConfigBackup { name: string; file: ConfigEditFile; at: number; bytes: number }
+/** The newest backups first, at most `BACKUPS_KEPT` per file. */
+export function configBackups(stateDir: string): ConfigBackup[] {
+  let names: string[];
+  try { names = readdirSync(backupDir(stateDir)); } catch { return []; }
+  return names.flatMap(name => {
+    const match = /^(config\.local\.json|sdlc\.toml)\.(\d{13})\.[a-f0-9]{8}\.bak$/.exec(name);
+    if (!match) return [];
+    try { return [{ name, file: match[1] as ConfigEditFile, at: Number(match[2]), bytes: statSync(join(backupDir(stateDir), name)).size }]; } catch { return []; }
+  }).sort((a, b) => b.at - a.at || (a.name < b.name ? 1 : -1));
+}
+
+/** Temp file and rename in the same directory: a reader sees the old file or the new one, never half of one. */
+function atomicWrite(path: string, text: string, mode: number): void {
+  const tmp = `${path}.${process.pid}.tmp`;
+  try { writeFileSync(tmp, text, { mode, flag: "wx" }); chmodSync(tmp, mode); renameSync(tmp, path); }
+  catch (error) { try { unlinkSync(tmp); } catch { /* nothing was written */ } throw error; }
+}
+
+/** A git-tracked machine-local file is never written: its content would travel with the repository. */
+function refuseTrackedLocal(cwd: string): void {
+  const tracked = configTracked(cwd, "config.local.json");
+  if (tracked) throw new Error(".agenthub/config.local.json is committed to git; structural edits write only machine-local files. Remove it from the repository (git rm --cached) and ignore it");
+  if (tracked === undefined && configRepositoryPresent(cwd)) throw new Error("git could not confirm that .agenthub/config.local.json is untracked; nothing was written");
+}
+
+/**
+ * Writes a plan that `planConfigEdit` accepted: the revision is checked once more against the disk, the previous file is kept
+ * as a bounded backup, then the file is replaced atomically. Returns what the audit event records (hashes, never values).
+ */
+export function writeConfigEdit(cwd: string, stateDir: string, plan: Extract<ConfigEditPlan, { ok: true }>, now: number = Date.now()): { backup?: string; fileBefore: string; fileAfter: string; paths: { path: string; before: string | null; after: string | null }[] } {
+  const { file } = plan.request, path = join(cwd, ".agenthub", file);
+  try {
+    if (file === "config.local.json") refuseTrackedLocal(cwd);
+    if (fileRevision(readEditable(cwd, file)) !== plan.request.revision) throw new Error(`.agenthub/${file} changed on disk since it was read: reload it and review the change again`);
+    let backup: string | undefined;
+    if (plan.before !== null) {
+      mkdirSync(backupDir(stateDir), { recursive: true, mode: 0o700 });
+      backup = `${file}.${String(now).padStart(13, "0")}.${sha(plan.before).slice(0, 8)}.bak`;
+      writeFileSync(join(backupDir(stateDir), backup), plan.before, { mode: 0o600 });
+      for (const old of configBackups(stateDir).filter(item => item.file === file).slice(BACKUPS_KEPT)) rmSync(join(backupDir(stateDir), old.name), { force: true });
+    }
+    mkdirSync(join(cwd, ".agenthub"), { recursive: true });
+    let mode = 0o600;
+    try { mode = statSync(path).mode & 0o777; } catch { /* a new file is the owner's alone */ }
+    if (plan.next === null) rmSync(path, { force: true }); else atomicWrite(path, plan.next, mode);
+    return { ...(backup ? { backup } : {}), fileBefore: fileRevision(plan.before), fileAfter: fileRevision(plan.next),
+      // A tier 3 value (a model name, a provider, a home) is low-entropy and dictionary-recoverable from an unsalted hash, so it gets none:
+      // the event shows that the key changed and the file revisions bind the change. A tier 2 value keeps its short hash.
+      paths: plan.diff.map(row => row.tier === 3 ? { path: row.path, before: row.before === undefined ? null : "(set)", after: row.after === undefined ? null : "(set)" } : { path: row.path, before: valueHash(row.before), after: valueHash(row.after) }) };
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code && !/\.agenthub|git/.test((error as Error).message)) throw new Error(`.agenthub/${file} could not be written (${code}); nothing was changed`);
+    throw error;
+  }
+}

package/src/hub/config-tier.ts

@@ -0,0 +1,89 @@
+import { NEVER_EDITABLE, SETTINGS } from "./settings.ts";
+
+/**
+ * #689: which structural keys a person may edit, and from where.
+ * Tier 1 is the settings registry (already editable, unchanged). Tier 2 is structural config, editable from the console and
+ * from a dashboard settings session. Tier 3 chooses what the hub executes or where secrets go: console only, typed key.
+ * One rule serves the editor, the dashboard's server-side refusal and reload authority, so none of them can drift.
+ */
+export const CONFIG_EDIT_FILES = ["config.local.json", "sdlc.toml"] as const;
+export type ConfigEditFile = typeof CONFIG_EDIT_FILES[number];
+export type ConfigTier = { tier: 2 } | { tier: 3; key: string } | { refused: string };
+
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+const UNSAFE = new Set(["__proto__", "constructor", "prototype"]);
+/** Instance fields that choose no executable and no home. */
+export const TIER2_INSTANCE_FIELDS = ["kind", "roles", "start_mode", "review_mode", "readOnly", "worktree", "permission_mode"] as const;
+/** Instance fields that choose a native home, account or model: tier 3 (#685). */
+export const TIER3_INSTANCE_FIELDS = ["jcode_home", "provider", "model", "provider_profile"] as const;
+/** Every NEVER_EDITABLE key except `instances`, which splits by field. */
+export const TIER3_PREFIXES: readonly string[] = NEVER_EDITABLE.filter(key => key !== "instances");
+const TIER2_BLOCKS: Readonly<Record<string, readonly string[]>> = {
+  review: ["adaptive", "min_reviews", "pool", "rerotate"],
+  snapshots: ["keep"],
+  approvals: ["timeout_s"],
+  context: ["gate"],
+};
+const SDLC_KEYS = ["mode", "required_checks"] as const;
+/** Registry-owned keys keep their own write path: a roster change moves tasks and stops peers, and a WIP limit applies live. */
+const REGISTRY_PREFIXES = ["roster", "tasks.wip_limits", "permission_modes", "catalog_roles", "peers"] as const;
+const registryKey = (key: string): boolean => SETTINGS.some(def => def.key === key || def.path.join(".") === key) || REGISTRY_PREFIXES.some(prefix => key === prefix || key.startsWith(`${prefix}.`));
+
+const refuse = (reason: string): { refused: string } => ({ refused: `${reason}; nothing was written` });
+const isObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * The tier of one edit. `value` is only read for a whole `instances.<id>` object, whose fields are classified one by one
+ * (the highest tier wins, an unknown field is refused by name, never dropped).
+ */
+export function configTier(file: ConfigEditFile, path: readonly string[], value?: unknown, held?: unknown): ConfigTier {
+  if (!path.length || path.some(part => typeof part !== "string" || !part || part.length > 64 || UNSAFE.has(part) || /[\s\x00-\x1f]/.test(part))) return refuse("invalid configuration path");
+  const key = path.join(".");
+  if (file === "sdlc.toml") return path.length === 1 && (SDLC_KEYS as readonly string[]).includes(path[0]!) ? { tier: 2 } : refuse(`sdlc.${key} is not editable here: only mode and required_checks are; edit .agenthub/sdlc.toml in your editor`);
+  if (registryKey(key)) return { refused: `${key} is already editable with ahub settings set ${key}; nothing was written` };
+  if (path[0] === "instances") {
+    if (path.length === 1) return refuse("instances: name one instance (instances.<id>)");
+    if (!PEER.test(path[1]!)) return refuse(`instances.${path[1]}: an instance id is lower-case letters, digits and hyphens`);
+    if (path.length === 2) {
+      // A whole instance that already holds a native home, account or model is tier 3 to remove or replace, whatever the new value is:
+      // its values are what a browser must never see or delete (#689 review).
+      if (isObject(held) && TIER3_INSTANCE_FIELDS.some(field => Object.hasOwn(held, field))) return { tier: 3, key: `instances.${path[1]}` };
+      if (value === undefined || value === null) return { tier: 2 }; // removal of a whole declaration; the loaders judge what depends on it
+      if (!isObject(value)) return refuse(`instances.${path[1]}: must be an object of instance fields`);
+      let tier3: string | undefined;
+      for (const field of Object.keys(value)) {
+        if ((TIER3_INSTANCE_FIELDS as readonly string[]).includes(field)) tier3 = `instances.${path[1]}`;
+        else if (!(TIER2_INSTANCE_FIELDS as readonly string[]).includes(field)) return refuse(`instances.${path[1]}.${field}: unknown instance field`);
+      }
+      return tier3 ? { tier: 3, key: tier3 } : { tier: 2 };
+    }
+    if (path.length === 3) {
+      if ((TIER3_INSTANCE_FIELDS as readonly string[]).includes(path[2]!)) return { tier: 3, key };
+      if ((TIER2_INSTANCE_FIELDS as readonly string[]).includes(path[2]!)) return { tier: 2 };
+    }
+    return refuse(`${key}: unknown instance field`);
+  }
+  const never = TIER3_PREFIXES.find(prefix => key === prefix || key.startsWith(`${prefix}.`));
+  if (never) return { tier: 3, key };
+  const fields = TIER2_BLOCKS[path[0]!];
+  if (fields && path.length === 2 && fields.includes(path[1]!)) return { tier: 2 };
+  return refuse(`${key} is not a structural setting`);
+}
+
+/** Whether reload authority may take this key as a confirmed structural edit: tier 2 only, never an executable or secret key. */
+export function structuralLeaf(key: string): boolean {
+  const path = key.split(".");
+  const tier = configTier("config.local.json", path);
+  return "tier" in tier && tier.tier === 2;
+}
+
+/** A value as a reply may show it: a tier 3 key is only ever `(set)`, and inside a whole instance only its tier 3 fields are. */
+export function maskTier3(path: readonly string[], value: unknown): unknown {
+  if (value === undefined) return undefined;
+  const key = path.join(".");
+  if (path[0] === "instances" && path.length === 2 && isObject(value)) return Object.fromEntries(Object.entries(value).map(([field, item]) => [field, (TIER3_INSTANCE_FIELDS as readonly string[]).includes(field) ? "(set)" : item]));
+  const tier = configTier("config.local.json", path, undefined);
+  if ("tier" in tier && tier.tier === 3) return "(set)";
+  if (TIER3_PREFIXES.some(prefix => key === prefix || key.startsWith(`${prefix}.`))) return "(set)";
+  return value;
+}

package/src/hub/control-client.ts

@@ -9,10 +9,29 @@ export function stateDirFor(cwd: string): string {
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
 export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated"] as const;
+export const DAEMON_FEATURES = ["external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "role_stages", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;
 
+/** Only a launch retries transient transport failures. Refusals and identity mismatches
+ * remain terminal; every attempt rereads the descriptor and applies the instance pin. */
+export async function retryLaunchConnect<T>(attempt: (timeoutMs: number) => Promise<T>, onRetry: () => void,
+  ports: { now(): number; sleep(ms: number): Promise<unknown> } = { now: Date.now, sleep: ms => Bun.sleep(ms) }): Promise<T> {
+  const until = ports.now() + 15_000;
+  let backoff = 250, announced = false;
+  for (;;) {
+    try { return await attempt(Math.max(1, Math.min(3000, until - ports.now()))); }
+    catch (error) {
+      const code = (error as { code?: unknown } | null)?.code;
+      if (!["AHUB_CONNECT_TIMEOUT", 1006].includes(code as string | number) || ports.now() >= until) throw error;
+      if (!announced) { announced = true; onRetry(); }
+      await ports.sleep(Math.min(backoff, until - ports.now()));
+      if (ports.now() >= until) throw error;
+      backoff = Math.min(1000, backoff * 2);
+    }
+  }
+}
+
 export interface Hello {
   /** `tools`: acts for `peer` (task tools, hub_send) without being a delivery target: the MCP server Kimi and Codex run. */
   role: "peer" | "console" | "tools";
@@ -21,6 +40,8 @@ export interface Hello {
   channel?: boolean;
   /** Managed Claude launch identity; absent for plain or pre-daemon sessions. */
   launchId?: string;
+  /** Optional canonical native execution cwd; ownership requires independent host proof. */
+  cwd?: string;
   /** Reclaim after replacement, never an intentional initial takeover. */
   standby?: boolean;
   projectId?: string;
@@ -110,9 +131,9 @@ export class ControlClient {
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(control.url);
       const client = new ControlClient(ws);
-      const timer = setTimeout(() => refuse(new Error(`hub connection timed out at ${control.url}`)), timeoutMs);
+      const timer = setTimeout(() => refuse(Object.assign(new Error(`hub connection timed out at ${control.url}`), { code: "AHUB_CONNECT_TIMEOUT" })), timeoutMs);
       const refuse = (error: Error) => { clearTimeout(timer); reject(error); ws.close(); };
-      ws.onerror = () => refuse(new Error(`cannot reach hub at ${control.url}`));
+      ws.onerror = () => refuse(Object.assign(new Error(`cannot reach hub at ${control.url}`), { code: "AHUB_CONNECT_UNREACHABLE" }));
       ws.onclose = (ev) => {
         clearTimeout(timer);
         // A refused hello carries its reason (bad token, wire version, peer id); say that, not a guess.