@staix/agent-hub 0.13.0 → 0.15.0

package/src/hub/action-policy.ts

@@ -31,24 +31,25 @@ export function actionPolicyConfig(value?: unknown): ActionPolicyConfig {
 export interface ActionSessionBudget { readonly peer: string; readonly session: string }
 export interface ActionChallenge { readonly classes: readonly ActionClass[] }
 export type ActionDecision = { kind: "native" } | { kind: "ask"; classes: ActionClass[]; challenge?: ActionChallenge } | { kind: "budget"; classes: ActionClass[] };
-interface Session { handle: ActionSessionBudget; policy: string; remaining: Record<ActionClass, number> }
+/** `grants` counts the class-budget approvals of this session and policy: a challenge remembers it, so a later approval can tell that another one landed first. */
+interface Session { handle: ActionSessionBudget; policy: string; remaining: Record<ActionClass, number>; grants: Record<ActionClass, number> }
 const empty = (): Record<ActionClass, number> => ({ publish: 0, destroy: 0, "external-write": 0, install: 0 });
 /** Host-only ledger: session ids and policy come from current runtime ports, never a tool argument. */
 export class ActionBudgets {
   private sessions = new Map<string, Session>();
-  private challenges = new WeakMap<ActionChallenge, { handle: ActionSessionBudget; policy: string; classes: ActionClass[] }>();
+  private challenges = new WeakMap<ActionChallenge, { handle: ActionSessionBudget; policy: string; classes: ActionClass[]; grants: Record<ActionClass, number> }>();
   constructor(private readonly config: () => ActionPolicyConfig | undefined, private readonly currentSession: (peer: string) => string | undefined) {}
   bindSession(peer: string, session: string): ActionSessionBudget | undefined {
     if (!session || this.currentSession(peer) !== session) return undefined;
     const previous = this.sessions.get(peer);
     if (previous?.handle.session === session) return previous.handle;
     const handle = Object.freeze({ peer, session });
-    this.sessions.set(peer, { handle, policy: "", remaining: empty() });
+    this.sessions.set(peer, { handle, policy: "", remaining: empty(), grants: empty() });
     return handle;
   }
   revoke(peer: string): void { this.sessions.delete(peer); }
   policyChanged(): void {
-    for (const state of this.sessions.values()) { state.policy = ""; state.remaining = empty(); }
+    for (const state of this.sessions.values()) { state.policy = ""; state.remaining = empty(); state.grants = empty(); }
     this.challenges = new WeakMap();
   }
   private current(handle: ActionSessionBudget | undefined): Session | undefined {
@@ -56,7 +57,7 @@ export class ActionBudgets {
     const state = this.sessions.get(handle.peer);
     if (state?.handle !== handle || this.currentSession(handle.peer) !== handle.session) return undefined;
     const policy = JSON.stringify(actionPolicyConfig(this.config()));
-    if (state.policy !== policy) { state.policy = policy; state.remaining = empty(); }
+    if (state.policy !== policy) { state.policy = policy; state.remaining = empty(); state.grants = empty(); }
     return state;
   }
   private selected(actions: readonly ActionClass[]): ActionClass[] {
@@ -70,28 +71,39 @@ export class ActionBudgets {
     if (!state) return { kind: "ask", classes };
     if (classes.some(key => state.remaining[key] <= 0)) {
       const challenge = Object.freeze({ classes: Object.freeze([...classes]) });
-      this.challenges.set(challenge, { handle: state.handle, policy: state.policy, classes: [...classes] });
+      this.challenges.set(challenge, { handle: state.handle, policy: state.policy, classes: [...classes], grants: { ...state.grants } });
       return { kind: "ask", classes, challenge };
     }
     for (const key of classes) state.remaining[key]--;
     return { kind: "budget", classes };
   }
-  /** Explicit class-budget approval only, never an ordinary allow_once; this invocation consumes slot one. */
+  /**
+   * Explicit class-budget approval only, never an ordinary allow_once; this invocation consumes slot one. Requests run concurrently, so
+   * two challenges can be issued while a class is spent: the first approval opens the allowance (budget minus this call), and an approval of
+   * a challenge issued before it is a later call inside that allowance, which consumes one slot instead of opening another. With no slot
+   * left it is refused (the person asks again and sees a fresh challenge), so N approved calls is the most any budget lets through.
+   * Every class is checked before any is spent: a refusal changes nothing.
+   */
   approve(challenge: ActionChallenge | undefined): boolean {
     if (!challenge) return false;
     const grant = this.challenges.get(challenge); this.challenges.delete(challenge);
     if (!grant) return false;
     const state = this.current(grant.handle), config = actionPolicyConfig(this.config());
     if (!state || state.policy !== grant.policy) return false;
-    for (const key of grant.classes) state.remaining[key] = Math.max(0, config.budgets[key] - 1);
+    const late = (key: ActionClass) => state.grants[key] !== grant.grants[key];
+    if (grant.classes.some(key => late(key) && state.remaining[key] <= 0)) return false;
+    for (const key of grant.classes) {
+      state.remaining[key] = late(key) ? state.remaining[key] - 1 : Math.max(0, config.budgets[key] - 1);
+      state.grants[key]++;
+    }
     return true;
   }
   /** Read-only projection: no session is created, rebound or reset by a status poll. */
-  status(peer: string, enforced: boolean) {
+  status(peer: string, enforced: boolean, reason = "adapter integration pending") {
     const config = actionPolicyConfig(this.config()), state = this.sessions.get(peer);
     const bound = !!state && this.currentSession(peer) === state.handle.session && state.policy === JSON.stringify(config);
     return { enabled: config.enabled, alwaysAsk: [...config.always_ask], limits: { ...config.budgets }, remaining: bound ? { ...state.remaining } : empty(), sessionBound: bound,
-      enforceable: enforced, note: !enforced ? `always-ask not enforceable: adapter integration pending${config.enabled ? "" : "; policy disabled"}` : config.enabled ? "always-ask active" : "always-ask disabled" };
+      enforceable: enforced, note: !enforced ? `always-ask not enforceable: ${reason}${config.enabled ? "" : "; policy disabled"}` : config.enabled ? "always-ask active" : "always-ask disabled" };
   }
 }
 

package/src/hub/board.ts

@@ -9,6 +9,7 @@ import type { SweepRecord } from "./task-sweep.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import type { SdlcReceipt } from "./sdlc.ts";
 import { parseReviewFindings, type ReviewFindingSet } from "./review-findings.ts";
+import { parseDeliverableRecords, type DeliverableRecord } from "./deliverables.ts";
 import type { CostPlan, ReviewCost } from "./cost-governance.ts";
 
 export const CLASSES = ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] as const;
@@ -66,6 +67,14 @@ export interface HistoryEntry {
   reviewContext?: "fresh" | "continuing";
   /** Structured review report bound to the reviewed artifact, stored in the existing history JSON. */
   reviewFindings?: ReviewFindingSet;
+  /**
+   * #509a: the files a `done`, a lifecycle record or an approval bound, with the content hashes the hub computed. An approval carries the hashes
+   * it was given at review time, so a later edit reads as "deliverable changed since review". Full paths live here; every view goes through
+   * `publicDeliverables`.
+   */
+  deliverables?: DeliverableRecord[];
+  /** #507b: the recorded acceptance criteria (S8 checklist ids) a verdict's unmet items named; derived by the hub from the checklist, never free text. */
+  unmetCriteria?: string[];
   /** Host-authored plan content revision, separate from backlog planningRevision. */
   planRevision?: { revision: number; fingerprint: string };
   planObservation?: { repo: string; pr: number; head: string; revision: number; fingerprint: string };
@@ -77,6 +86,11 @@ export interface HistoryEntry {
   reviewerFailure?: { peer: string; head?: string; cause: "start_failed" | "quota" | "no_verdict" };
   planning?: { revision: number; fields: (keyof PlanningFields)[]; previous: PlanningFields; pull?: true; split?: { children: { id: number; revision: number; history: number }[] } };
 }
+/** The ids a stored verdict may carry (#507b): bounded criterion identifiers in the S8 checklist's own format, at most its 32, each once. */
+function criterionIdList(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length > 32 || value.some(id => typeof id !== "string" || !/^[A-Za-z][A-Za-z0-9-]{0,47}$/.test(id)) || new Set(value).size !== value.length) throw new Error("unmet criteria: expected up to 32 distinct criterion ids");
+  return [...value] as string[];
+}
 export type ReviewerHistory = Pick<HistoryEntry, "reviewerFamily" | "reviewerReason" | "reviewBlocked" | "reviewerFailure">;
 function reviewerHistory(extra: ReviewerHistory): ReviewerHistory {
   const id = (value: unknown) => typeof value === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(value);
@@ -222,6 +236,8 @@ export class Board {
     // And from before issue #207: existing rows reserve nobody.
     for (const col of ["offer", "cancelled"]) if (!have.has(col)) this.db.run(`ALTER TABLE tasks ADD COLUMN ${col} TEXT`);
     this.db.run("CREATE TABLE IF NOT EXISTS task_stalls (task INTEGER PRIMARY KEY, payload TEXT NOT NULL)");
+    // #481 S7: one row per log-tier band breach episode already announced, so a restart never repeats the notice.
+    this.db.run("CREATE TABLE IF NOT EXISTS band_notices (marker TEXT PRIMARY KEY, at INTEGER NOT NULL)");
     // Derived status-cache generation: only Board task/stall writes advance it, never journal writes.
     this.db.run("CREATE TABLE IF NOT EXISTS board_status_revision (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL)");
     this.db.run("INSERT OR IGNORE INTO board_status_revision VALUES (1,0)");
@@ -300,6 +316,11 @@ export class Board {
     this.taskWrite(() => this.db.query("INSERT INTO task_stalls(task,payload) VALUES(?,?) ON CONFLICT(task) DO UPDATE SET payload=excluded.payload").run(stall.task, JSON.stringify(stall)));
     return true;
   }
+  /** True when the marker was new (and is now recorded), false when it was announced before. Ids, metric names and task numbers only. */
+  recordBandNotice(marker: string): boolean {
+    if (!/^[a-z_]{1,64}:#[1-9][0-9]{0,9}:log$/.test(marker)) throw new Error("invalid band notice marker");
+    return this.db.query("INSERT OR IGNORE INTO band_notices(marker, at) VALUES(?, ?)").run(marker, Date.now()).changes > 0;
+  }
   clearStall(task: number): void { this.taskWrite(() => this.db.query("DELETE FROM task_stalls WHERE task=?").run(task)); }
   stalls(): TaskStall[] {
     return (this.db.query("SELECT payload FROM task_stalls ORDER BY task").all() as { payload: string }[]).flatMap(row => {
@@ -325,7 +346,7 @@ export class Board {
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
   /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "capacity" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewFindings" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "capacity" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewFindings" | "unmetCriteria" | "deliverables" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (expectedFlowRevision !== undefined && (!Number.isSafeInteger(expectedFlowRevision) || expectedFlowRevision < 0 || task.history.length !== expectedFlowRevision)) throw new Error("task flow revision changed");
@@ -359,6 +380,16 @@ export class Board {
       if (head !== undefined && !/^[a-f0-9]{40}$/.test(head)) throw new Error("finding metadata requires a full reviewed head");
       reviewFindings = { ...(head ? { head } : {}), items: parseReviewFindings(extra.reviewFindings.items, { person: by === "user", maxNits: 64 }) };
     }
+    let deliverables: DeliverableRecord[] | undefined;
+    if (extra.deliverables !== undefined) {
+      if (!["done", "done (checking)", "lifecycle", "approved"].includes(event)) throw new Error("deliverable records require a done, a lifecycle record or an approval");
+      deliverables = parseDeliverableRecords(extra.deliverables);
+    }
+    let unmetCriteria: string[] | undefined;
+    if (extra.unmetCriteria !== undefined) {
+      if (!["approved", "changes_requested"].includes(event) || patch.state !== event) throw new Error("unmet criteria require a saved review verdict");
+      unmetCriteria = criterionIdList(extra.unmetCriteria);
+    }
     if (extra.planDeparture && (by !== "user" || event !== "plan departure accepted")) throw new Error("plan departure acceptance is person-only");
     const trackPlan = this.trackPlanRevisions?.() === true, hasDeparture = task.history.some(h => h.planDeparture);
     const fingerprint = patch.plan && (trackPlan || hasDeparture) ? planFingerprint(next.plan ?? {}) : undefined;
@@ -367,7 +398,7 @@ export class Board {
     // Disabling reporting must not let plan or repository refs edits/reverts resurrect prior consent.
     const repositoryRefsChanged = patch.refs !== undefined && JSON.stringify([task.refs.repo, task.refs.paths]) !== JSON.stringify([next.refs.repo, next.refs.paths]);
     const departureInvalidated = extra.planDepartureInvalidated === true || hasDeparture && (planChanged || repositoryRefsChanged);
-    const history = [...task.history, { at: Date.now(), by, event, ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}) }];
+    const history = [...task.history, { at: Date.now(), by, event, ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}) }];
     this.taskWrite(() => {
       const result = this.db.query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, updated = ? WHERE id = ?")
         .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), id);
@@ -403,12 +434,26 @@ export class Board {
     const task = this.get(id);
     if (!task || (task.planningRevision ?? 0) !== revision || task.state !== "backlog" || task.owner || !taskCanPlan(task)) throw new Error("planner pull changed or already started");
     const now = Date.now(), entry: HistoryEntry = { at: now, by, event: "backlog pulled", planning: { revision: revision + 1, fields: ["reserved"], previous: { reserved: task.reserved ?? null }, pull: true }, note, ...(withheld ? { withheld: true as const } : {}) };
-    const result = this.taskWrite(() => this.db.query("UPDATE tasks SET state='proposed',owner=NULL,reviewer=NULL,reserved=?,planning_revision=planning_revision+1,history=?,updated=? WHERE id=? AND planning_revision=? AND state='backlog' AND owner IS NULL")
+    const result = this.taskWrite(() => this.db.query("UPDATE tasks SET state='proposed',owner=NULL,reviewer=NULL,offer=NULL,reserved=?,planning_revision=planning_revision+1,history=?,updated=? WHERE id=? AND planning_revision=? AND state='backlog' AND owner IS NULL")
       .run(reserved, JSON.stringify([...task.history, entry]), now, id, revision));
     if (result.changes !== 1) throw new Error("planner pull changed");
     const updated = this.get(id)!; this.changed(updated, entry); return updated;
   }
 
+  /** Publish no intermediate ownerless pull: Tasks has already admitted the exact reserved peer. */
+  pullAssigned(id: number, by: PeerId, owner: PeerId, revision: number, note: string, withheld: boolean,
+    reviewer: PeerId | null, assignmentNote: string, extra: Parameters<Board["update"]>[5], expectedFlowRevision: number): Task {
+    return this.atomic(() => {
+      const current = this.get(id);
+      if (!current || current.history.length !== expectedFlowRevision) throw new Error("task flow revision changed");
+      const pulled = this.pullPlanned(id, by, owner, revision, note, withheld);
+      const assigned = this.update(id, by, "assigned", { owner, reviewer }, assignmentNote, extra, pulled.history.length);
+      // Both deferred events describe the committed handoff, including the callback payload.
+      for (const change of this.pendingChanges ?? []) if (change.task.id === id) change.task = assigned;
+      return assigned;
+    });
+  }
+
   /** No owner or execution evidence may be taken back by planning undo. */
   undoPlannedPull(id: number, by: PeerId, revision: number): Task {
     const task = this.get(id), pull = task ? planningUndoEntry(task)?.planning : undefined;

package/src/hub/budget.ts

@@ -248,6 +248,11 @@ export class Budget {
     this.evaluate(peer, hard).catch((e: Error) => this.closed || this.hooks.notify(`budget: evaluating ${peer} failed: ${e.message}`));
   }
 
+  /** A source that can no longer be trusted drops its reading of one window: the window shows unknown, never the last number. */
+  forget(peer: PeerId, id: UsageWindow["id"]): void {
+    this.readings.get(this.account(peer))?.delete(id);
+  }
+
   /** Readings that still say something: not stale, and not about a window that has reset since they were taken. */
   private fresh(peer: PeerId): Reading[] {
     peer = this.account(peer);

package/src/hub/bus.ts

@@ -429,14 +429,14 @@ export class Bus {
   }
 
   knownPeers(): string[] {
-    const pending = this.storageError ? [] : this.journal?.list().filter((row) => ["queued", "dispatching", "accepted", "needs_review"].includes(row.state)).map((row) => row.peer) ?? [];
+    const pending = this.storageError ? [] : this.journal?.pendingPeers() ?? [];
     return [...new Set([...this.peers.keys(), ...[...this.queues].filter(([, queue]) => queue.length).map(([id]) => id), ...pending])].sort();
   }
 
-  queueList(peer?: string): JournalDelivery[] {
+  queueList(peer?: string, unresolvedOnly = false): JournalDelivery[] {
     if (this.journal) {
-      const rows = this.journal.list(peer).filter((row) => !row.reason?.startsWith("grouped into delivery "));
-      const revision = this.journal.snapshot().revision;
+      const rows = (unresolvedOnly ? this.journal.unresolved(peer) : this.journal.list(peer)).filter((row) => !row.reason?.startsWith("grouped into delivery "));
+      const revision = this.journal.revision();
       const recorded = new Set(rows.filter((r) => ["queued", "dispatching", "accepted", "needs_review"].includes(r.state)).flatMap((r) => (r.originals as Envelope[]).map((e) => `${r.peer}:${e.id}`)));
       const ids = peer ? [peer] : [...this.queues.keys()];
       for (const p of ids) for (const e of this.queues.get(p) ?? []) if (!recorded.has(`${p}:${e.id}`)) rows.push({ id: `q:${p}:${e.id}`, peer: p, state: "queued", revision, createdAt: e.ts, updatedAt: e.ts, originals: [e], out: [e] });
@@ -525,7 +525,7 @@ export class Bus {
   }
 
   queueSummary(peer: string): { needsReview: number; heldBy?: string; liveAccepted?: string[]; oldestQueuedAt?: number } {
-    const rows = this.storageError ? [] : this.queueList(peer);
+    const rows = this.storageError ? [] : this.queueList(peer, true);
     const queued = this.queues.get(peer) ?? [];
     const review = rows.filter((r) => r.state === "needs_review");
     const needsReview = review.length;

package/src/hub/claude-launch-proof.ts

@@ -0,0 +1,33 @@
+import { closeSync, fstatSync, openSync, readSync, constants } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { claudeStateFile } from "./claude-state.ts";
+
+export interface ClaudeLaunchProof {
+  launchId: string;
+  executionCwd?: string;
+  privateRecord: boolean;
+  permissionHook: boolean;
+  unattended: boolean;
+  hookPurpose?: string;
+}
+
+/** One bounded reader for current managed launch metadata; no native identity or payload escapes. */
+export function readClaudeLaunchProof(stateDir: string, peer: string, instanceId: string): ClaudeLaunchProof | undefined {
+  let fd: number | undefined;
+  try {
+    fd = openSync(join(stateDir, claudeStateFile("claude-launch", peer)), constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    // ponytail: launch metadata is capped at 16 KiB; add a versioned projection if it ever grows.
+    if (!stat.isFile() || stat.size > 16 * 1024) return;
+    const bytes = Buffer.alloc(16 * 1024 + 1);
+    const count = readSync(fd, bytes, 0, bytes.length, 0);
+    if (count > 16 * 1024) return;
+    const row = JSON.parse(bytes.subarray(0, count).toString("utf8"));
+    if (row?.instanceId !== instanceId || typeof row.launchId !== "string" || !row.launchId || row.launchId.length > 128) return;
+    return { launchId: row.launchId, privateRecord: stat.nlink === 1 && (stat.mode & 0o777) === 0o600 && !!process.getuid && stat.uid === process.getuid(),
+      ...(typeof row.executionCwd === "string" && row.executionCwd.length <= 4096 && isAbsolute(row.executionCwd) ? { executionCwd: row.executionCwd } : {}),
+      permissionHook: row.permissionHook === true, unattended: row.unattended === true,
+      ...(typeof row.hookPurpose === "string" ? { hookPurpose: row.hookPurpose } : {}) };
+  } catch { return; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}

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