@agfpd/iapeer 0.4.68 → 0.4.70

package/src/daemon/approvals.ts

@@ -0,0 +1,202 @@
+// Approval broker — the in-daemon queue that is the SINGLE SOURCE OF TRUTH for
+// human-approval requests (docs/17). Every channel (the runtime hook that ASKS, and
+// the CLI / tray / telegram faces that ANSWER) is an interface to THIS one queue: a
+// decision from any face resolves the request everywhere (the owner's invariant).
+//
+// Flow: a gated peer's PreToolUse hook blocks and POSTs /fleet/v1/approvals → the fleet
+// handler calls broker.request(...) and awaits the returned promise (long-poll) → the
+// broker enqueues, emits `approval-request` (approvals.log → SSE), and holds the promise
+// → a face calls broker.resolve(id, …) (via POST /fleet/v1/approvals/<id>/approve|deny)
+// → the promise resolves, the fleet handler writes the runtime hook JSON back, the tool
+// proceeds or is blocked with the reason. A per-request timeout resolves default-DENY so
+// a peer never hangs. Every failure direction is deny (fail-safe): timeout, requester
+// disconnect, unknown id.
+//
+// In-memory + ephemeral: pending requests do NOT survive a daemon restart (the blocking
+// hook connection breaks on restart → the hook fails safe to deny). The durable
+// approvals.log is the audit/observability trace, not a recovery store.
+
+import { appendApprovalEvent } from './approvalslog.ts'
+
+/** v1 taxonomy of intercepted blocking requests (docs/17 §2). Free-form-tolerant. */
+export type ApprovalKind = 'tool' | 'plan' | 'question' | 'circuit-breaker'
+
+export interface ApprovalRequestInput {
+  personality: string
+  runtime: string
+  /** Taxonomy tag (tool | plan | question | circuit-breaker | …). */
+  kind: ApprovalKind | string
+  /** The specific tool / breaker name, e.g. `Bash`, `Edit`, `dangerous-rm`. */
+  tool: string
+  /** FULL human-readable content of the action — the command, the diff, the plan text,
+   *  the circuit-breaker prompt. Shown to the human in every channel (criterion #7). */
+  content: string
+  /** One-line summary for the SSE event / badge (default: the first line of content). */
+  summary?: string
+  /** Short title, e.g. "boris · Bash" (default: "<personality> · <tool>"). */
+  title?: string
+  /** nature-peers who may answer (informational in v1 — same-uid faces are trusted). */
+  approvers?: string[]
+}
+
+export interface PendingApproval extends ApprovalRequestInput {
+  id: string
+  summary: string
+  title: string
+  approvers: string[]
+  createdMs: number
+  expiresMs: number
+}
+
+export interface ApprovalDecision {
+  decision: 'allow' | 'deny'
+  reason?: string
+}
+
+export interface ResolveMeta {
+  /** The approver who answered (a nature-peer personality). */
+  by?: string
+  /** The channel that answered: cli | tray | telegram | timeout | disconnect. */
+  via?: string
+}
+
+interface Entry {
+  item: PendingApproval
+  resolve: (d: ApprovalDecision) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+export interface ApprovalBrokerOptions {
+  /** cfg.eventLogDir — approvals.log lives here (falsy → no durable log, hermetic). */
+  logDir?: string
+  env?: NodeJS.ProcessEnv
+  /** Per-request default-deny timeout. Default IAPEER_APPROVAL_TIMEOUT_MS or 300 s.
+   *  MUST stay below the runtime hook's own timeout (claude/codex default 600 s) so the
+   *  broker's default-deny wins before the runtime kills the hook (fail-safe ordering). */
+  timeoutMs?: number
+  /** Injectable clock (tests). Default Date.now. */
+  now?: () => number
+}
+
+const DEFAULT_TIMEOUT_MS = 300_000
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+function firstLine(s: string): string {
+  const nl = s.indexOf('\n')
+  return (nl >= 0 ? s.slice(0, nl) : s).trim()
+}
+
+export class ApprovalBroker {
+  private readonly pending = new Map<string, Entry>()
+  private counter = 0
+  private readonly logDir?: string
+  private readonly env: NodeJS.ProcessEnv
+  private readonly timeoutMs: number
+  private readonly now: () => number
+
+  constructor(opts: ApprovalBrokerOptions = {}) {
+    this.logDir = opts.logDir
+    this.env = opts.env ?? process.env
+    this.timeoutMs = opts.timeoutMs ?? envPosInt(this.env.IAPEER_APPROVAL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS)
+    this.now = opts.now ?? Date.now
+  }
+
+  /** Enqueue a request and return its id + a promise that resolves when a face answers
+   *  or the timeout fires (default-deny). The caller (fleet handler) awaits `decision`
+   *  and MUST call `cancel(id)` if its transport dies before the promise settles. */
+  request(input: ApprovalRequestInput): { id: string; decision: Promise<ApprovalDecision> } {
+    const id = `a${++this.counter}`
+    const createdMs = this.now()
+    const expiresMs = createdMs + this.timeoutMs
+    const summary = (input.summary?.trim() || firstLine(input.content) || input.tool).slice(0, 240)
+    const title = input.title?.trim() || `${input.personality} · ${input.tool}`
+    const approvers = input.approvers ?? []
+    const item: PendingApproval = { ...input, id, summary, title, approvers, createdMs, expiresMs }
+    let resolve!: (d: ApprovalDecision) => void
+    const decision = new Promise<ApprovalDecision>(res => {
+      resolve = res
+    })
+    const timer = setTimeout(
+      () => this.settle(id, { decision: 'deny', reason: 'approval timed out (default-deny)' }, { via: 'timeout' }),
+      this.timeoutMs,
+    )
+    ;(timer as { unref?: () => void }).unref?.()
+    this.pending.set(id, { item, resolve, timer })
+    appendApprovalEvent(
+      this.logDir,
+      {
+        ev: 'approval-request',
+        id,
+        personality: input.personality,
+        runtime: input.runtime,
+        kind: input.kind,
+        tool: input.tool,
+        summary,
+        created: createdMs,
+        expires: expiresMs,
+        approvers: approvers.join(',') || undefined,
+      },
+      { env: this.env, nowMs: createdMs },
+    )
+    return { id, decision }
+  }
+
+  /** All pending requests, oldest first (GET /fleet/v1/approvals + `iapeer approvals`). */
+  list(): PendingApproval[] {
+    return [...this.pending.values()].map(e => e.item).sort((a, b) => a.createdMs - b.createdMs)
+  }
+
+  /** One pending request by id (GET /fleet/v1/approvals/<id> — full content). */
+  get(id: string): PendingApproval | undefined {
+    return this.pending.get(id)?.item
+  }
+
+  /** Answer a request from a face. Returns false iff the id is unknown (already resolved,
+   *  expired, or never existed) — the caller reports 404. */
+  resolve(id: string, decision: ApprovalDecision, meta: ResolveMeta = {}): boolean {
+    if (!this.pending.has(id)) return false
+    this.settle(id, decision, meta)
+    return true
+  }
+
+  /** Requester transport died before an answer — settle default-deny + drop from the
+   *  queue so it does not linger (the asking hook is gone; the tool call is aborted). */
+  cancel(id: string, reason = 'requester disconnected'): boolean {
+    if (!this.pending.has(id)) return false
+    this.settle(id, { decision: 'deny', reason }, { via: 'disconnect' })
+    return true
+  }
+
+  /** Pending count (badge/metrics). */
+  size(): number {
+    return this.pending.size
+  }
+
+  private settle(id: string, decision: ApprovalDecision, meta: ResolveMeta): void {
+    const entry = this.pending.get(id)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    this.pending.delete(id)
+    const nowMs = this.now()
+    appendApprovalEvent(
+      this.logDir,
+      {
+        ev: 'approval-resolved',
+        id,
+        personality: entry.item.personality,
+        runtime: entry.item.runtime,
+        decision: decision.decision,
+        reason: decision.reason,
+        by: meta.by,
+        via: meta.via,
+        latencyMs: nowMs - entry.item.createdMs,
+      },
+      { env: this.env, nowMs },
+    )
+    entry.resolve(decision)
+  }
+}

package/src/daemon/approvalslog.ts

@@ -0,0 +1,54 @@
+// Approval-broker durable log — the daemon's DURABLE trace of every human-approval
+// request it brokers (docs/17). Sibling to lifecycle.log / delivery.log / exits.log
+// under cfg.eventLogDir; tailed by the fleet-API SSE stream (fleetEventFiles), so the
+// `approval-request` / `approval-resolved` events reach every operator client (CLI,
+// tray, telegram) with at-least-once semantics — and a postmortem can reconstruct who
+// asked, what, and how it resolved after the in-memory queue is gone.
+//
+// What is logged: approval METADATA + a one-line `summary` of the action — NOT the full
+// multi-line content (a Write's whole body / a long diff would bloat the log). The full
+// human-readable content lives in the in-memory queue and is served by GET
+// /fleet/v1/approvals/<id>; the log carries enough to correlate + render a badge/line.
+//
+// Same rotation class as its siblings: written by OUR code → self-rotates via the shared
+// storage/rotatelog primitive. The dir is passed IN by the composition point, never
+// re-resolved from env — a falsy dir → no-op (library/test daemons stay hermetic).
+
+import { join } from 'path'
+import { DEFAULT_LOG_KEEP, DEFAULT_LOG_MAX_BYTES, appendRotatedEvent } from '../storage/rotatelog.ts'
+
+/** The approval-broker log inside `logDir` (sibling to lifecycle.log). */
+export function approvalsLogPath(logDir: string): string {
+  return join(logDir, 'approvals.log')
+}
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+export interface AppendApprovalOptions {
+  /** Reads the rotation knobs IAPEER_APPROVALS_LOG_MAX_BYTES / _KEEP. */
+  env?: NodeJS.ProcessEnv
+  /** Stamp the line with this epoch-ms. Default Date.now(). */
+  nowMs?: number
+}
+
+/**
+ * Append one approval event line into `logDir`/approvals.log. A falsy `logDir` is a
+ * no-op (the default for library/test daemons). Fully best-effort — never throws;
+ * logging must never fail an approval round-trip.
+ */
+export function appendApprovalEvent(
+  logDir: string | undefined,
+  fields: Record<string, string | number | undefined>,
+  opts: AppendApprovalOptions = {},
+): void {
+  if (!logDir) return
+  const env = opts.env ?? process.env
+  appendRotatedEvent(approvalsLogPath(logDir), fields, {
+    nowMs: opts.nowMs,
+    maxBytes: envPosInt(env.IAPEER_APPROVALS_LOG_MAX_BYTES, DEFAULT_LOG_MAX_BYTES),
+    keep: envPosInt(env.IAPEER_APPROVALS_LOG_KEEP, DEFAULT_LOG_KEEP),
+  })
+}

package/src/daemon/fleet.ts

@@ -42,6 +42,7 @@ import {
   isEphemeralPeer,
   isLaunchdManaged,
   loadLifecycleConfig,
+  peerApprovalMode,
   wakeOrSpawn,
   type LifecycleConfig,
 } from '../lifecycle/index.ts'
@@ -59,6 +60,8 @@ import {
 } from '../storage/rotatelog.ts'
 import { heartbeatAgeSecs, probeFullDiskAccess, readMemoryProvider, readVoiceProvider } from '../status/index.ts'
 import { deliveryLogPath } from './deliverylog.ts'
+import { approvalsLogPath } from './approvalslog.ts'
+import { ApprovalBroker } from './approvals.ts'
 import { callTool, type CallToolDeps } from './index.ts'
 
 /** The API generation baked into every snapshot (additive evolution within v1 —
@@ -93,6 +96,9 @@ export interface FleetPeer {
   wake_policy: 'warm' | 'ephemeral'
   /** Ephemeral peers only: pending serial-queue tasks across declared runtimes. */
   queue_depth?: number
+  /** Human-approval mode (docs/17-approval): `yolo` (default — bypass + auto-confirm
+   *  circuit-breakers) or `gated` (blocking runtime approvals routed to a human). */
+  approval_mode: 'yolo' | 'gated'
 }
 
 export interface FleetHost {
@@ -105,12 +111,32 @@ export interface FleetHost {
   fda: boolean | null
 }
 
+/** A pending human-approval request as the snapshot exposes it (docs/17). The SAME items
+ *  `GET /fleet/v1/approvals` returns (broker.list()) — carried in the snapshot so a client
+ *  that already fetches `/snapshot` on every event renders the queue with no extra call. The
+ *  compact `summary` fuels a badge/one-liner; the verbatim `content` (criterion #7 — the full
+ *  command / diff / plan) rides along for inline display, capped by the client if it wishes. */
+export interface FleetApproval {
+  id: string
+  personality: string
+  runtime: string
+  kind: string
+  tool: string
+  summary: string
+  content: string
+  createdMs: number
+  expiresMs: number
+}
+
 export interface FleetSnapshot {
   api: typeof FLEET_API_VERSION
   version: string
   ts: string
   host: FleetHost
   peers: FleetPeer[]
+  /** Pending human-approval requests (docs/17). ADDITIVE + omitted when the queue is empty —
+   *  a client MUST treat its absence as an empty queue (same rule as `approval_mode`). */
+  approvals?: FleetApproval[]
 }
 
 // The CLI op functions, injectable for tests. Defaults LAZY-load cli/index.ts at
@@ -146,6 +172,7 @@ export function buildFleetSnapshot(
   ops: Pick<FleetOps, 'listPeers'>,
   startedAtMs: number,
   nowMs: number = Date.now(),
+  approvals: FleetApproval[] = [],
 ): FleetSnapshot {
   const peers: FleetPeer[] = ops.listPeers({ env }).map(r => {
     const runtimes: FleetRuntimeStatus[] = r.runtimes.map(s => {
@@ -163,6 +190,9 @@ export function buildFleetSnapshot(
     if (ephemeral) {
       for (const s of r.runtimes) queueDepth += ephemeralQueueDepth(cfg, buildProcessAddress(s.runtime, r.personality))
     }
+    // Approval mode from the LOCAL profile (same source as ephemeral); a read hiccup →
+    // the safe `yolo` default (peerApprovalMode swallows it).
+    const approvalMode = peerApprovalMode(r.cwd)
     return {
       personality: r.personality,
       description: r.description,
@@ -176,6 +206,7 @@ export function buildFleetSnapshot(
       launchd_managed: isLaunchdManaged(r.personality, env),
       wake_policy: ephemeral ? ('ephemeral' as const) : ('warm' as const),
       ...(ephemeral ? { queue_depth: queueDepth } : {}),
+      approval_mode: approvalMode,
     }
   })
   const mem = readMemoryProvider(env)
@@ -198,6 +229,10 @@ export function buildFleetSnapshot(
       fda: probeFullDiskAccess(env),
     },
     peers,
+    // ADDITIVE + omitted when empty (absence ⇒ empty queue, docs/15). broker.list() is a
+    // superset of FleetApproval — the named fields are the contract; extras ride along and
+    // clients ignore them (obligation 2).
+    ...(approvals.length ? { approvals } : {}),
   }
 }
 
@@ -217,6 +252,9 @@ export function fleetEventFiles(cfg: LifecycleConfig): Array<{ path: string; src
     { path: lifecycleLogPath(cfg.eventLogDir), src: 'lifecycle' },
     { path: deliveryLogPath(cfg.eventLogDir), src: 'delivery' },
     { path: exitLogPath(cfg.eventLogDir), src: 'exits' },
+    // Human-approval broker events (docs/17): approval-request / approval-resolved.
+    // A pre-approval daemon simply never writes this file (readLogTail tolerates absence).
+    { path: approvalsLogPath(cfg.eventLogDir), src: 'approvals' },
   ]
 }
 
@@ -432,6 +470,8 @@ export interface FleetHandlerOptions {
   ops?: FleetOps
   /** Injectable tailer poll interval (tests). */
   pollMs?: number
+  /** Injectable approval broker (tests — e.g. a short timeout). Default: a fresh one. */
+  broker?: ApprovalBroker
 }
 
 export type FleetHandler = (
@@ -451,6 +491,9 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
   const startedAtMs = Date.now()
   const files = fleetEventFiles(cfg)
   const tailer = new FleetEventTailer(files, opts.pollMs)
+  // The approval broker — one per daemon; the ASK side (POST /approvals long-poll) and
+  // the ANSWER side (GET/POST /approvals/*) are all interfaces to this one queue.
+  const broker = opts.broker ?? new ApprovalBroker({ logDir: cfg.eventLogDir, env })
   let opsPromise: Promise<FleetOps> | undefined
   const getOps = (): Promise<FleetOps> => {
     if (opts.ops) return Promise.resolve(opts.ops)
@@ -466,7 +509,9 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
       // ── reads ────────────────────────────────────────────────────────────
       if (path === '/fleet/v1/snapshot') {
         if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/snapshot' })
-        return sendJson(res, 200, buildFleetSnapshot(env, cfg, await getOps(), startedAtMs))
+        // broker.list() is PendingApproval[] — structurally a superset of FleetApproval, so it
+        // satisfies the snapshot contract (extra fields serialize + are ignored by clients).
+        return sendJson(res, 200, buildFleetSnapshot(env, cfg, await getOps(), startedAtMs, undefined, broker.list()))
       }
       if (path === '/fleet/v1/events') {
         if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/events' })
@@ -533,6 +578,72 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
         if (result.isError) return sendJson(res, 502, { error: text })
         return sendJson(res, 200, { from: caller.address, result: safeParse(text) })
       }
+      // ── approvals — the human-approval broker surface (docs/17) ────────────
+      if (path === '/fleet/v1/approvals') {
+        if (method === 'GET') {
+          return sendJson(res, 200, { api: FLEET_API_VERSION, version: IAPEER_VERSION, ts: new Date().toISOString(), approvals: broker.list() })
+        }
+        if (method === 'POST') {
+          // The gated peer's hook BLOCKS here (long-poll): enqueue + await a decision.
+          let body: Record<string, unknown>
+          try {
+            body = await readBody(req)
+          } catch (e) {
+            return sendJson(res, 400, { error: e instanceof Error ? e.message : String(e) })
+          }
+          if (typeof body.personality !== 'string' || !body.personality || typeof body.tool !== 'string' || typeof body.content !== 'string') {
+            return sendJson(res, 400, { error: 'approval request needs {personality, runtime, tool, content} (+ optional kind/summary/title/approvers)' })
+          }
+          const { id, decision } = broker.request({
+            personality: body.personality,
+            runtime: typeof body.runtime === 'string' ? body.runtime : 'claude',
+            kind: typeof body.kind === 'string' ? body.kind : 'tool',
+            tool: body.tool,
+            content: body.content,
+            summary: typeof body.summary === 'string' ? body.summary : undefined,
+            title: typeof body.title === 'string' ? body.title : undefined,
+            approvers: Array.isArray(body.approvers) ? body.approvers.filter((a): a is string => typeof a === 'string') : undefined,
+          })
+          // No idle-socket kill during the (≤ broker-timeout) hold; cancel default-deny
+          // if the asking hook's transport dies before an answer (drop it from the queue).
+          res.setTimeout?.(0)
+          let settled = false
+          const onClose = (): void => {
+            if (!settled) broker.cancel(id)
+          }
+          req.on('close', onClose)
+          const d = await decision
+          settled = true
+          return sendJson(res, 200, { id, ...d })
+        }
+        return sendJson(res, 405, { error: 'method not allowed — GET|POST /fleet/v1/approvals' })
+      }
+      const apMatch = /^\/fleet\/v1\/approvals\/([^/]+)(?:\/(approve|deny))?$/.exec(path)
+      if (apMatch) {
+        const id = decodeURIComponent(apMatch[1]!)
+        const action = apMatch[2]
+        if (!action) {
+          if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/approvals/<id>' })
+          const item = broker.get(id)
+          if (!item) return sendJson(res, 404, { error: `no pending approval "${id}"` })
+          return sendJson(res, 200, { api: FLEET_API_VERSION, version: IAPEER_VERSION, ts: new Date().toISOString(), approval: item })
+        }
+        if (method !== 'POST') return sendJson(res, 405, { error: 'method not allowed — POST /fleet/v1/approvals/<id>/(approve|deny)' })
+        let body: Record<string, unknown> = {}
+        try {
+          body = await readBody(req)
+        } catch {
+          /* empty/invalid body is fine — approve/deny carry only optional fields */
+        }
+        const by = typeof body.approver === 'string' ? body.approver : undefined
+        const via = typeof body.via === 'string' ? body.via : 'cli'
+        const ok =
+          action === 'approve'
+            ? broker.resolve(id, { decision: 'allow', reason: typeof body.reason === 'string' ? body.reason : undefined }, { by, via })
+            : broker.resolve(id, { decision: 'deny', reason: typeof body.reason === 'string' ? body.reason : 'denied by human' }, { by, via })
+        if (!ok) return sendJson(res, 404, { error: `no pending approval "${id}" (already resolved, expired, or unknown)` })
+        return sendJson(res, 200, { id, action, ok: true })
+      }
       return sendJson(res, 404, {
         error: `unknown fleet endpoint ${method} ${path}`,
         endpoints: [
@@ -541,6 +652,10 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
           'GET /fleet/v1/events?replay=N',
           'POST /fleet/v1/peers/<peer>/(wake|stop|start|new|refresh|interrupt|compact)',
           'POST /fleet/v1/send',
+          'GET /fleet/v1/approvals',
+          'POST /fleet/v1/approvals (hook long-poll)',
+          'GET /fleet/v1/approvals/<id>',
+          'POST /fleet/v1/approvals/<id>/(approve|deny)',
         ],
       })
     } catch (e) {

package/src/identity/index.ts

@@ -56,6 +56,14 @@ import {
  *  Enum (not bool) to leave room for future policies. */
 export type WakePolicy = 'ephemeral'
 
+/** Per-peer human-approval mode (foundation lifecycle-owned; docs/17-approval).
+ *  `yolo` (default, absent) = current fleet behavior — runtime bypass flag + the
+ *  supervisor auto-confirms circuit-breakers. `gated` = launch WITHOUT bypass, the
+ *  runtime's blocking approval requests are routed to a human through the daemon
+ *  approval broker. Only `gated` is persisted (yolo = field absent, byte-identical to
+ *  a never-toggled profile — mirrors wake_policy). */
+export type ApprovalMode = 'yolo' | 'gated'
+
 export interface PeerProfile {
   personality: string
   runtime: Runtime
@@ -69,6 +77,9 @@ export interface PeerProfile {
   interfaces?: PeerInterfaces
   /** Per-peer wake policy (lifecycle-owned). Absent = normal warm-on-demand. */
   wake_policy?: WakePolicy
+  /** Per-peer human-approval mode (lifecycle-owned). Absent = `yolo` (default). Only
+   *  `gated` is persisted; see ApprovalMode. */
+  approval_mode?: ApprovalMode
 }
 
 // Write shape: intelligence/description optional so a caller can write a profile
@@ -241,9 +252,19 @@ export function readPeerProfile(cwd: string = process.cwd()): PeerProfile | null
     // Wake policy — only the known enum value is honored; anything else → omitted
     // (treated as normal warm-on-demand, never throws on an unknown future value).
     ...(obj.wake_policy === 'ephemeral' ? { wake_policy: 'ephemeral' as const } : {}),
+    // Approval mode — only `gated` is persisted/honored; absent / `yolo` / unknown →
+    // omitted (treated as the default `yolo`, never throws on an unknown future value).
+    ...(obj.approval_mode === 'gated' ? { approval_mode: 'gated' as const } : {}),
   }
 }
 
+/** The effective approval mode of a profile: `gated` iff persisted, else the default
+ *  `yolo`. The ONE place the "absent ⇒ yolo" default lives — every reader (launch,
+ *  supervisor, fleet snapshot, CLI) resolves the mode through this, never re-derives it. */
+export function approvalModeOf(profile: PeerProfile | null | undefined): ApprovalMode {
+  return profile?.approval_mode === 'gated' ? 'gated' : 'yolo'
+}
+
 /**
  * Atomically write peer-profile.json, preserving fields the foundation does not
  * own (e.g. persistent-peer's initial_prompt/aliases section) via a raw read-
@@ -375,6 +396,13 @@ function writePeerProfileMerged(path: string, profile: PeerProfileWrite): void {
   if (typeof profile.initial_prompt === 'string' && profile.initial_prompt) {
     merged.initial_prompt = profile.initial_prompt
   }
+  // Approval mode (lifecycle-owned toggle). `gated` persists the field; `yolo` REMOVES
+  // it (default = absence, so a gated→yolo flip restores a byte-identical pristine
+  // profile — the toggle idempotency invariant). An ABSENT approval_mode in the write
+  // (any non-toggle writer: verify --fix, rename, re-provision) preserves the existing
+  // value verbatim via `...existing` — a caller that does not own the toggle never flips it.
+  if (profile.approval_mode === 'gated') merged.approval_mode = 'gated'
+  else if (profile.approval_mode === 'yolo') delete merged.approval_mode
   writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}\n`)
 }
 

package/src/identity/profileStandard.ts

@@ -115,6 +115,9 @@ export function validateProfileStandard(raw: unknown, cwd: string): ProfileIssue
   if (obj.wake_policy !== undefined && obj.wake_policy !== 'ephemeral') {
     issues.push({ severity: 'warn', field: 'wake_policy', message: `unknown value "${String(obj.wake_policy)}" — only 'ephemeral' is honored` })
   }
+  if (obj.approval_mode !== undefined && obj.approval_mode !== 'gated' && obj.approval_mode !== 'yolo') {
+    issues.push({ severity: 'warn', field: 'approval_mode', message: `unknown value "${String(obj.approval_mode)}" — only 'gated'|'yolo' honored (absent = yolo default)` })
+  }
 
   // Owner sections — well-typed only; foundation never restructures them.
   if (obj.interfaces !== undefined && (typeof obj.interfaces !== 'object' || obj.interfaces === null || Array.isArray(obj.interfaces))) {