@staix/agent-hub 0.23.1 → 0.25.0

package/src/hub/action-enforce.ts

@@ -1,4 +1,4 @@
-import { ACTION_CLASSES, classifyAction, type ActionClass } from "./action-class.ts";
+import { ACTION_CLASSES, classifyAction, type ActionClass, type FloorFacts } from "./action-class.ts";
 import { actionApprovalView, actionPolicyConfig, type ActionBudgets, type ActionPolicyConfig } from "./action-policy.ts";
 import type { ActionGateVerdict } from "../adapters/acp.ts";
 
@@ -12,11 +12,11 @@ import type { ActionGateVerdict } from "../adapters/acp.ts";
 export interface ActionCall { names: readonly string[]; kind?: string; input: unknown }
 
 /** The classes of one call. ACP names a shell call `execute` by kind whatever its tool is called, so that kind is also read as a shell. */
-export function classifyCall(call: ActionCall, root: string): ActionClass[] {
+export function classifyCall(call: ActionCall, root: string, floor?: FloorFacts): ActionClass[] {
   const names = new Set(call.names.filter(name => typeof name === "string" && name.length > 0));
   if (call.kind === "execute") names.add("bash");
   const found = new Set<ActionClass>();
-  for (const name of names) for (const key of classifyAction(name, call.input, root)) found.add(key);
+  for (const name of names) for (const key of classifyAction(name, call.input, root, floor)) found.add(key);
   return ACTION_CLASSES.filter(key => found.has(key));
 }
 
@@ -25,8 +25,8 @@ export function classifyCall(call: ActionCall, root: string): ActionClass[] {
  * cannot carry a class-budget choice, so every classed Claude call asks (a count of zero approved calls, always). A handle-less request
  * selects the classes without touching any session ledger.
  */
-export function claudeActionClasses(budgets: ActionBudgets, tool: string, input: unknown, root: string): ActionClass[] {
-  const classes = classifyAction(tool, input, root);
+export function claudeActionClasses(budgets: ActionBudgets, tool: string, input: unknown, root: string, floor?: FloorFacts): ActionClass[] {
+  const classes = classifyAction(tool, input, root, budgets.floorOn() ? floor : undefined);
   if (!classes.length) return [];
   const decision = budgets.request(undefined, classes);
   return decision.kind === "ask" ? decision.classes : [];
@@ -51,6 +51,8 @@ export interface ActionGatePorts<T> {
   policy(): ActionPolicyConfig | undefined;
   /** The peer's execution root: a delete outside it is classed. */
   root(peer: string): string;
+  /** The floor's facts (#999 T3), read per call. Absent or undefined means the floor is off or its facts are unknown, and every class asks as before. */
+  floor?(peer: string): FloorFacts | undefined;
   /** The task the peer is working on, for the approval line. */
   task(peer: string): T | undefined;
   /** The task's public view (`Tasks.publicView`): the only way a task title reaches an approval. */
@@ -68,7 +70,7 @@ export interface ActionGatePorts<T> {
  */
 export function actionGate<T>(ports: ActionGatePorts<T>, peer: string): (call: ActionCall, session: string, onPremToolTitle?: string) => ActionGateVerdict | undefined {
   return (call, session, onPremToolTitle) => {
-    const classes = classifyCall(call, ports.root(peer));
+    const classes = classifyCall(call, ports.root(peer), ports.budgets.floorOn() ? ports.floor?.(peer) : undefined);
     if (!classes.length) return undefined;
     const decision = ports.budgets.request(ports.budgets.bindSession(peer, session), classes);
     if (decision.kind !== "ask") return undefined; // native, or within an approved class budget

package/src/hub/action-policy.ts

@@ -1,19 +1,21 @@
 import { ACTION_CLASSES, type ActionClass } from "./action-class.ts";
 import { sanitize } from "./envelope.ts";
 
-export interface ActionPolicyConfig { enabled: boolean; always_ask: ActionClass[]; budgets: Record<ActionClass, number> }
+/** `floor` (#999 T3) lets ordinary branch pushes and own-repository pull requests run without asking. It is kept when present, true or false, so a recovery can tell that the project's file names the key at all. */
+export interface ActionPolicyConfig { enabled: boolean; always_ask: ActionClass[]; budgets: Record<ActionClass, number>; floor?: boolean }
 const DEFAULT_BUDGETS: Record<ActionClass, number> = { publish: 1, destroy: 3, "external-write": 5, install: 2 };
 /** Defaults are host policy; overrides belong only in untracked config.local.json.
  * ponytail: startup adopts that local policy without a retained person confirmation.
  * Status surfaces every weakening as attention; upgrade: retain a person-bound startup confirmation.
  */
 export function actionPolicyConfig(value?: unknown): ActionPolicyConfig {
-  const fail = (): never => { throw new Error("action_policy: expected enabled, always_ask and class budgets (integers 0..1000)"); };
+  const fail = (): never => { throw new Error("action_policy: expected enabled, always_ask, floor and class budgets (integers 0..1000)"); };
   if (value === undefined) return { enabled: true, always_ask: [...ACTION_CLASSES], budgets: { ...DEFAULT_BUDGETS } };
   if (!value || typeof value !== "object" || Array.isArray(value)) return fail();
   const raw = value as Record<string, unknown>;
-  if (Object.keys(raw).some(key => !["enabled", "always_ask", "budgets"].includes(key))) return fail();
+  if (Object.keys(raw).some(key => !["enabled", "always_ask", "budgets", "floor"].includes(key))) return fail();
   if (raw.enabled !== undefined && typeof raw.enabled !== "boolean") return fail();
+  if (raw.floor !== undefined && typeof raw.floor !== "boolean") return fail();
   const classes = raw.always_ask === undefined ? ACTION_CLASSES : raw.always_ask;
   if (!Array.isArray(classes) || classes.length > ACTION_CLASSES.length || new Set(classes).size !== classes.length || classes.some(key => !ACTION_CLASSES.includes(key))) return fail();
   const budgets = { ...DEFAULT_BUDGETS };
@@ -24,7 +26,82 @@ export function actionPolicyConfig(value?: unknown): ActionPolicyConfig {
       budgets[key as ActionClass] = amount;
     }
   }
-  return { enabled: raw.enabled ?? true, always_ask: [...classes], budgets } as ActionPolicyConfig;
+  return { enabled: raw.enabled ?? true, always_ask: [...classes], budgets, ...(raw.floor !== undefined ? { floor: raw.floor } : {}) } as ActionPolicyConfig;
+}
+
+/** The classes the floor never lets always_ask drop: with the floor on, release-grade, destructive and foreign-write calls ask whatever the coarse selector says. */
+export const FLOOR_ASKED: readonly ActionClass[] = Object.freeze(["publish", "external-write", "destroy"] as const);
+/** The classes that ask under this policy: always_ask, plus every floor class while the floor is on. A disabled policy asks none. */
+export function askedClasses(config: ActionPolicyConfig): ActionClass[] {
+  if (!config.enabled) return [];
+  return ACTION_CLASSES.filter(key => config.always_ask.includes(key) || config.floor === true && FLOOR_ASKED.includes(key));
+}
+
+/**
+ * The structural guards the floor rests on where the hub cannot see a call first (Codex in never-ask, Kimi in auto, Jcode: #999 T3). The hub names
+ * them and cannot verify them from here, so a status row says "not verified", never that they hold. A guard that is missing is the person's to report.
+ */
+export const FLOOR_GUARDS: readonly { readonly asks: string; readonly guard: string }[] = Object.freeze([
+  { asks: "force push, a push to the default branch or of tags", guard: "GitHub branch protection on the default branch" },
+  { asks: "gh release and a release tag", guard: "release only through ahub sdlc authorize-release and the OIDC tag workflow" },
+  { asks: "deletion outside the project, a write to another repository", guard: "the peer's native sandbox" },
+]);
+export const floorGuardText = (): string => FLOOR_GUARDS.map(entry => `${entry.asks}: ${entry.guard}`).join("; ");
+
+/**
+ * One classification's budget for host reads (#999 T3). Every authority read the floor makes goes through `read`: an identical key is answered once from the memo, at most `calls`
+ * distinct reads run, and none is answered after `ms` has passed, so a valid-sized command that holds hundreds of pushes cannot hold the synchronous gate. Past the bound a fact is
+ * unknown (undefined), and an unknown fact keeps the call asking. `now` is injectable so a test proves the bound with a counter and a clock, never a subprocess storm.
+ * ponytail: the bound is per classification, not per daemon; a shared async fact cache would lift the ceiling without blocking the loop.
+ */
+export function floorReads(calls: number, ms: number, now: () => number = Date.now): { read: <T>(key: string, run: () => T) => T | undefined; readonly distinct: number } {
+  const started = now(), memo = new Map<string, unknown>();
+  return {
+    read: <T>(key: string, run: () => T): T | undefined => {
+      if (now() - started > ms) return undefined;
+      if (memo.has(key)) return memo.get(key) as T;
+      if (memo.size >= calls) return undefined;
+      const found = run();
+      memo.set(key, found);
+      return found;
+    },
+    get distinct() { return memo.size; },
+  };
+}
+
+/**
+ * The eight floor classes of #999 (one list with `templates/presets/autonomous.json` `floorClasses`; a test holds them equal): each maps to the action class
+ * that asks for it and to the structural guard it rests on where the hub cannot see the call first. `guard` null means none is named: the class is then
+ * unprotected there, and status says so.
+ */
+export const FLOOR_CLASS_TABLE: Readonly<Record<string, { readonly action: ActionClass; readonly asks: string; readonly guard: string | null }>> = Object.freeze({
+  "force-push": { action: "publish", asks: "a force or delete push", guard: "GitHub branch protection on the default branch" },
+  "default-branch-push": { action: "publish", asks: "a push to the default branch", guard: "GitHub branch protection on the default branch" },
+  "tag-push": { action: "publish", asks: "a push of a tag", guard: "release only through ahub sdlc authorize-release and the OIDC tag workflow" },
+  "release-publish": { action: "publish", asks: "gh release", guard: "release only through ahub sdlc authorize-release and the OIDC tag workflow" },
+  "package-publish": { action: "publish", asks: "npm, bun, pnpm, yarn or cargo publish", guard: null },
+  "destroy-outside-root": { action: "destroy", asks: "deletion outside the execution root", guard: "the peer's native sandbox" },
+  "foreign-repo-write": { action: "external-write", asks: "a write to another repository", guard: "the peer's native sandbox" },
+  "external-send": { action: "external-write", asks: "mail and posting", guard: null },
+});
+export const FLOOR_CLASSES: readonly string[] = Object.freeze(Object.keys(FLOOR_CLASS_TABLE));
+export interface FloorEnforcementRow { readonly class: string; readonly status: "hub-enforced" | "not-enforced"; readonly reason: string }
+/**
+ * What the hub can say about each floor class for one peer, from the running policy and where the hub sees that peer's calls (`enforcement`, as `actionEnforcement`
+ * in the daemon reports it). `hub-enforced`: the hub sees the call first and the class asks under this policy, with the floor on or off. `not-enforced`: it does not,
+ * or the policy does not ask for the class; the reason names the guard the class rests on and that the hub has not verified it, never that it holds. The hub verifies
+ * no structural guard, so no row is `structural-guard` here: that status needs evidence a person or a check supplies (`AutonomyPeer.structuralGuards`).
+ */
+export function floorEnforcement(policy: ActionPolicyConfig | undefined, enforcement: { readonly enforced: boolean; readonly reason?: string }): Record<string, FloorEnforcementRow> {
+  const config = actionPolicyConfig(policy), asked = askedClasses(config), rows: Record<string, FloorEnforcementRow> = {};
+  for (const [name, entry] of Object.entries(FLOOR_CLASS_TABLE)) {
+    const guard = entry.guard === null ? "no structural guard is named for it" : `it rests on ${entry.guard}, which the hub has not verified`;
+    if (!config.enabled) rows[name] = { class: name, status: "not-enforced", reason: `action_policy is disabled, so ${entry.asks} does not ask; ${guard}` };
+    else if (!asked.includes(entry.action)) rows[name] = { class: name, status: "not-enforced", reason: `action_policy always_ask omits ${entry.action}, so ${entry.asks} does not ask; ${guard}` };
+    else if (!enforcement.enforced) rows[name] = { class: name, status: "not-enforced", reason: `the hub does not see this peer's calls first${enforcement.reason ? ` (${enforcement.reason})` : ""}; ${guard}` };
+    else rows[name] = { class: name, status: "hub-enforced", reason: `${entry.asks} asks (class ${entry.action}${config.floor === true ? ", floor on" : ""})` };
+  }
+  return rows;
 }
 
 export interface ActionSessionBudget { readonly peer: string; readonly session: string }
@@ -59,9 +136,14 @@ export class ActionBudgets {
     if (state.policy !== policy) { state.policy = policy; state.remaining = empty(); state.grants = empty(); }
     return state;
   }
-  private selected(actions: readonly ActionClass[]): ActionClass[] {
+  /** Whether the floor (#999 T3) is on: the policy is enabled and says `floor`. Callers read floor facts only through this, so facts alone never widen a policy that did not ask for them. */
+  floorOn(): boolean {
     const config = actionPolicyConfig(this.config());
-    return config.enabled ? ACTION_CLASSES.filter(key => actions.includes(key) && config.always_ask.includes(key)) : [];
+    return config.enabled && config.floor === true;
+  }
+  private selected(actions: readonly ActionClass[]): ActionClass[] {
+    const asked = askedClasses(actionPolicyConfig(this.config()));
+    return ACTION_CLASSES.filter(key => actions.includes(key) && asked.includes(key));
   }
   /** A budget decision consumes every selected class atomically; native never grants permission. */
   request(handle: ActionSessionBudget | undefined, actions: readonly ActionClass[]): ActionDecision {
@@ -101,10 +183,14 @@ export class ActionBudgets {
   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);
-    const weakened = !config.enabled || ACTION_CLASSES.some(key => !config.always_ask.includes(key) || config.budgets[key] > DEFAULT_BUDGETS[key]);
+    const weakened = !config.enabled || config.floor === true || ACTION_CLASSES.some(key => !config.always_ask.includes(key) || config.budgets[key] > DEFAULT_BUDGETS[key]);
     const attention = weakened ? "; attention: machine-local policy weakens defaults; no retained startup confirmation" : "";
-    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: ${reason}${config.enabled ? "" : "; policy disabled"}` : config.enabled ? "always-ask active" : "always-ask disabled") + attention };
+    const floor = config.enabled && config.floor === true;
+    // Where the hub cannot see a call first, the floor rests on guards outside it: say which, and that the hub has not verified them.
+    const rests = floor && !enforced ? `; floor on: ${floorGuardText()} rest on structural guards the hub has not verified` : floor ? "; floor on: ordinary branch pushes and own-repository pull requests do not ask" : "";
+    return { enabled: config.enabled, alwaysAsk: askedClasses({ ...config, enabled: true }), limits: { ...config.budgets }, remaining: bound ? { ...state.remaining } : empty(), sessionBound: bound,
+      ...(config.floor === true ? { floor: true, ...(floor && !enforced ? { floorGuards: FLOOR_GUARDS.map(entry => ({ ...entry })) } : {}) } : {}),
+      enforceable: enforced, note: (!enforced ? `always-ask not enforceable: ${reason}${config.enabled ? "" : "; policy disabled"}` : config.enabled ? "always-ask active" : "always-ask disabled") + rests + attention };
   }
 }
 

package/src/hub/autonomy-consent.ts

@@ -0,0 +1,173 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeSync, type Stats } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { types } from "node:util";
+
+export type AutonomyConsentPurpose = "permission" | "ownership" | "undo";
+export type AutonomyConsentValue = string;
+export type AutonomyConsentValues = Record<string, Record<string, AutonomyConsentValue>>;
+export interface AutonomyConsent {
+  confirmed(current: AutonomyConsentValues, trusted: boolean): Set<string>;
+  /** Host console-confirmation capability. Never exposed as a caller-selected operation. */
+  confirm(values: AutonomyConsentValues): void;
+  clear(): void;
+}
+export const AUTONOMY_CONSENT_DIR = "autonomy";
+export const AUTONOMY_CONSENT_FILE = "autonomy-consent.json";
+export const AUTONOMY_CONSENT_KEY_FILE = "autonomy-consent.key";
+export const autonomyConsentStateDir = (home: string, projectId: string): string => join(home, AUTONOMY_CONSENT_DIR, createHash("sha256").update(projectId).digest("hex"));
+const MAX_PEERS = 128, MAX_RECORD = 64 * 1024, KEY_BYTES = 32;
+const HEX = /^[a-f0-9]{64}$/, PEER = /^[a-z][a-z0-9-]{0,63}$/;
+const unavailable = (): Error => new Error("autonomy consent is unavailable");
+interface SignedPeer { peer: string; digest: string; mac: string }
+interface Document { version: 1; project: string; purpose: AutonomyConsentPurpose; peers: SignedPeer[] }
+interface PrivateRead { bytes: Buffer; stat: Stats }
+const plain = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value) && !types.isProxy(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value)) && Object.getOwnPropertySymbols(value).length === 0
+  && Object.values(Object.getOwnPropertyDescriptors(value)).every(descriptor => Object.hasOwn(descriptor, "value"));
+const sameFile = (left: Stats, right: Stats): boolean => left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+
+/** Digests bind exact mode keys or the purpose-specific witness digest, independent of insertion order. No values are retained in the receipt. */
+function digests(value: AutonomyConsentValues, purpose: AutonomyConsentPurpose): Map<string, string> {
+  if (!plain(value) || Object.keys(value).length > MAX_PEERS) throw unavailable();
+  if (purpose !== "permission" && (Object.keys(value).length !== 1 || !Object.hasOwn(value, purpose))) throw unavailable();
+  const result = new Map<string, string>();
+  for (const peer of Object.keys(value).sort()) {
+    const values = value[peer];
+    if (!PEER.test(peer) || !plain(values)) throw unavailable();
+    const keys = Object.keys(values).sort();
+    if (purpose === "permission") {
+      if (!keys.length || keys.length > 2 || keys.some(key => key !== `permission_modes.${peer}` && key !== `permission.${peer}`)) throw unavailable();
+    } else if (keys.length !== 1 || keys[0] !== "digest" || typeof values.digest !== "string" || !HEX.test(values.digest)) throw unavailable();
+    const pairs = keys.map(key => {
+      const item = values[key];
+      if (typeof item !== "string" || !item || Buffer.byteLength(item) > 4096) throw unavailable();
+      return [key, item];
+    });
+    result.set(peer, createHash("sha256").update(JSON.stringify(pairs)).digest("hex"));
+  }
+  return result;
+}
+
+/** State is a host capability: filesystem guards and its HMAC key are outside writable project configuration. */
+export function createAutonomyConsent(stateDir: string, projectId: string, purpose: AutonomyConsentPurpose = "permission"): AutonomyConsent {
+  if (typeof stateDir !== "string" || !isAbsolute(stateDir) || Buffer.byteLength(stateDir) > 4096 || typeof projectId !== "string" || !projectId || Buffer.byteLength(projectId) > 1024 || !["permission", "ownership", "undo"].includes(purpose)) throw unavailable();
+  const privateDir = join(stateDir, AUTONOMY_CONSENT_DIR);
+  const state = join(privateDir, AUTONOMY_CONSENT_FILE), keyFile = join(privateDir, AUTONOMY_CONSENT_KEY_FILE);
+  const owner = process.getuid?.();
+  const directory = (create = false): boolean => {
+    if (owner === undefined || typeof constants.O_NOFOLLOW !== "number") throw unavailable();
+    let stat = lstatSync(stateDir, { throwIfNoEntry: false });
+    if (!stat && create) { mkdirSync(stateDir, { recursive: true, mode: 0o700 }); stat = lstatSync(stateDir); }
+    if (!stat) return false;
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== owner || (stat.mode & 0o022) !== 0) throw unavailable();
+    let child = lstatSync(privateDir, { throwIfNoEntry: false });
+    if (!child && create) { mkdirSync(privateDir, { mode: 0o700 }); child = lstatSync(privateDir); }
+    if (!child) return false;
+    if (!child.isDirectory() || child.isSymbolicLink() || child.uid !== owner || (child.mode & 0o077) !== 0) throw unavailable();
+    return true;
+  };
+  const safe = (stat: Stats, max: number) => stat.isFile() && stat.uid === owner && stat.nlink === 1 && (stat.mode & 0o777) === 0o600 && stat.size > 0 && stat.size <= max;
+  const read = (file: string, max: number): PrivateRead | undefined => {
+    let fd: number;
+    try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw unavailable(); }
+    try {
+      const before = fstatSync(fd);
+      if (!safe(before, max)) throw unavailable();
+      const bytes = Buffer.alloc(before.size); let offset = 0;
+      while (offset < bytes.length) { const size = readSync(fd, bytes, offset, bytes.length - offset, offset); if (!size) throw unavailable(); offset += size; }
+      const after = fstatSync(fd), current = lstatSync(file, { throwIfNoEntry: false });
+      if (!safe(after, max) || !sameFile(before, after) || !current || !safe(current, max) || !sameFile(after, current)) throw unavailable();
+      return { bytes, stat: after };
+    } finally { closeSync(fd); }
+  };
+  const mac = (key: Buffer, peer: string, digest: string): string => createHmac("sha256", key).update(JSON.stringify(["agent-hub.autonomy-consent/v1", purpose, projectId, peer, digest])).digest("hex");
+  const temporary = (bytes: Buffer): string => {
+    const file = join(privateDir, `.autonomy-consent-${randomBytes(16).toString("hex")}.tmp`);
+    const fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try { let offset = 0; while (offset < bytes.length) offset += writeSync(fd, bytes, offset); fsyncSync(fd); }
+    catch (error) { try { unlinkSync(file); } catch { /* Only this exclusive temporary file is ours. */ } throw error; }
+    finally { closeSync(fd); }
+    return file;
+  };
+  const write = (peers: SignedPeer[]): void => {
+    if (!directory()) throw unavailable();
+    read(state, MAX_RECORD); // Refuse unsafe existing paths; rename never follows a link.
+    const bytes = Buffer.from(`${JSON.stringify({ version: 1, project: projectId, purpose, peers } satisfies Document)}\n`);
+    if (bytes.length > MAX_RECORD) throw unavailable();
+    const temp = temporary(bytes);
+    try { renameSync(temp, state); } finally { if (existsSync(temp)) unlinkSync(temp); }
+  };
+  const key = (issue: boolean): Buffer | undefined => {
+    const present = read(keyFile, KEY_BYTES);
+    if (present) { if (present.bytes.length !== KEY_BYTES) throw unavailable(); return present.bytes; }
+    if (!issue) return undefined;
+    const generated = randomBytes(KEY_BYTES), temp = temporary(generated);
+    try {
+      try { linkSync(temp, keyFile); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    } finally { unlinkSync(temp); }
+    const published = read(keyFile, KEY_BYTES);
+    if (!published || published.bytes.length !== KEY_BYTES) throw unavailable();
+    return published.bytes;
+  };
+  const authenticated = (bytes: Buffer, secret: Buffer): { peers: SignedPeer[]; count: number } | undefined => {
+    const raw: unknown = JSON.parse(bytes.toString("utf8"));
+    if (!plain(raw) || raw.version !== 1 || Object.keys(raw).some(name => !["version", "project", "purpose", "peers"].includes(name)) || typeof raw.project !== "string" || typeof raw.purpose !== "string" || !Array.isArray(raw.peers) || raw.peers.length > MAX_PEERS) throw unavailable();
+    if (raw.project !== projectId || raw.purpose !== purpose) return undefined;
+    const peers: SignedPeer[] = [], seen = new Set<string>();
+    for (const value of raw.peers) {
+      if (!plain(value) || Object.keys(value).some(name => !["peer", "digest", "mac"].includes(name)) || typeof value.peer !== "string" || !PEER.test(value.peer) || typeof value.digest !== "string" || !HEX.test(value.digest) || typeof value.mac !== "string" || !HEX.test(value.mac) || seen.has(value.peer)) throw unavailable();
+      seen.add(value.peer);
+      if (timingSafeEqual(Buffer.from(value.mac, "hex"), Buffer.from(mac(secret, value.peer, value.digest), "hex"))) peers.push({ peer: value.peer, digest: value.digest, mac: value.mac });
+    }
+    return { peers, count: raw.peers.length };
+  };
+  const clear = (): void => {
+    try {
+      if (!directory()) return;
+      let failure = false;
+      // Retire the key first, including when a receipt is missing. Unlink never follows
+      // an owned alias or reads unsafe data; an old signed receipt cannot revive consent.
+      for (const file of [keyFile, state]) {
+        try {
+          const stat = lstatSync(file, { throwIfNoEntry: false });
+          if (!stat) continue;
+          if (stat.uid !== owner || !stat.isFile() && !stat.isSymbolicLink()) throw unavailable();
+          unlinkSync(file);
+        } catch { failure = true; }
+      }
+      if (failure) throw unavailable();
+    } catch { throw unavailable(); }
+  };
+  return {
+    confirmed(current, trusted) {
+      if (trusted !== true) { try { clear(); } catch { /* Unsafe state never proves consent. */ } return new Set(); }
+      try {
+        const expected = digests(current, purpose);
+        if (!directory()) return new Set();
+        const secret = key(false), receipt = read(state, MAX_RECORD);
+        if (!secret || !receipt) return new Set();
+        const stored = authenticated(receipt.bytes, secret);
+        if (!stored) return new Set();
+        const retained = stored.peers.filter(row => expected.get(row.peer) === row.digest);
+        const stillCurrent = read(state, MAX_RECORD);
+        if (!stillCurrent || !sameFile(receipt.stat, stillCurrent.stat)) return new Set();
+        // Copy only already authenticated approvals; an observation can revoke but never mint consent.
+        if (retained.length !== stored.count) write(retained);
+        return new Set(retained.map(row => row.peer));
+      } catch { return new Set(); }
+    },
+    confirm(values) {
+      try {
+        const requested = digests(values, purpose);
+        directory(true); read(state, MAX_RECORD);
+        const secret = key(true);
+        if (!secret) throw unavailable();
+        write([...requested].map(([peer, digest]) => ({ peer, digest, mac: mac(secret, peer, digest) })));
+      } catch { throw unavailable(); }
+    },
+    clear,
+  };
+}

package/src/hub/autonomy-defaults.ts

@@ -0,0 +1,58 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, type Stats } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { canonicalPath } from "./project.ts";
+import { insideRoot } from "./path-policy.ts";
+
+export interface AutonomyDefaultsRead { enabled: boolean; fingerprint: string; notice?: string }
+const MAX_BYTES = 4096;
+const same = (a: Stats, b: Stats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+const refusal = () => new Error("machine autonomy defaults are unsafe or changed; nothing was written");
+const safeFile = (stat: Stats) => stat.isFile() && stat.nlink === 1 && stat.uid === process.getuid?.() && (stat.mode & 0o777) === 0o600 && stat.size <= MAX_BYTES;
+function location(home: string, roots: readonly string[], create: boolean): Stats | undefined {
+  if (!isAbsolute(home) || roots.some(root => insideRoot(relative(canonicalPath(root), canonicalPath(home))))) throw refusal();
+  let parent = lstatSync(home, { throwIfNoEntry: false });
+  if (!parent && create) { mkdirSync(home, { recursive: true, mode: 0o700 }); parent = lstatSync(home); }
+  if (parent && (!parent.isDirectory() || parent.isSymbolicLink() || parent.uid !== process.getuid?.() || (parent.mode & 0o022) !== 0)) throw refusal();
+  return parent;
+}
+function capture(home: string, roots: readonly string[]): { stat?: Stats; text?: string; fingerprint: string } {
+  if (!location(home, roots, false)) return { fingerprint: "absent" };
+  const file = join(home, "defaults.json");
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { fingerprint: "absent" }; throw refusal(); }
+  try {
+    const before = fstatSync(fd);
+    if (!safeFile(before)) throw refusal();
+    const text = readFileSync(fd, "utf8"), after = fstatSync(fd), named = lstatSync(file);
+    if (Buffer.byteLength(text) > MAX_BYTES || !same(before, after) || !same(after, named)) throw refusal();
+    return { stat: after, text, fingerprint: createHash("sha256").update(`${after.dev}:${after.ino}:${after.ctimeMs}:`).update(text).digest("hex") };
+  } finally { closeSync(fd); }
+}
+/** Missing or untrusted machine files never change the shipped ask default. */
+export function readAutonomyDefaults(home: string, roots: readonly string[] = []): AutonomyDefaultsRead {
+  try {
+    const held = capture(home, roots);
+    if (held.text === undefined) return { enabled: false, fingerprint: held.fingerprint };
+    const raw: unknown = JSON.parse(held.text);
+    const document = raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : undefined;
+    if (!document || Object.keys(document).some(key => !["schema", "autonomy"].includes(key)) || document.schema !== 1 || typeof document.autonomy !== "boolean") throw refusal();
+    return { enabled: document.autonomy, fingerprint: held.fingerprint };
+  } catch { return { enabled: false, fingerprint: "untrusted", notice: "Machine autonomy defaults ignored: defaults.json must be an owner-only regular file with a valid schema, outside project roots." }; }
+}
+/** Person CLI only. Exact prior evidence is rechecked after confirmation and before replacement. */
+export function writeAutonomyDefaults(home: string, enabled: boolean, expected: string, roots: readonly string[] = []): void {
+  const before = capture(home, roots);
+  if (before.fingerprint !== expected) throw refusal();
+  const parent = location(home, roots, true)!;
+  const file = join(home, "defaults.json"), temporary = join(home, `.defaults.${randomUUID()}.tmp`);
+  try {
+    const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try { writeFileSync(fd, `${JSON.stringify({ schema: 1, autonomy: enabled }, null, 2)}\n`); fsyncSync(fd); }
+    finally { closeSync(fd); }
+    const current = lstatSync(home);
+    if (current.dev !== parent.dev || current.ino !== parent.ino || capture(home, roots).fingerprint !== expected) throw refusal();
+    renameSync(temporary, file);
+  } finally { try { unlinkSync(temporary); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } }
+}