@evoclock/pi-agentic-driver 1.1.2 → 2.0.0

package/docs/relay-authority.md

@@ -0,0 +1,9 @@
+# Relayed authority
+
+A relayed approval records the owner's exact answer, the question it answered, channel, source message and time. A record attests that a configured relayer recorded those words; the hash chain does **not** prove the speaker's identity. The coordinator can check `[relay:v1 ledger=<id> relayer=<name>]` with the read-only `agentic_relay_check_request` tool against the profile ledger, never against claims in prompt prose. A covered result is only a preflight; each effect still checks its own approval at its action boundary. Without a valid record, the native confirmation path remains in force.
+
+The active profile holds `config/relay-authority.v1.json` and `approvals/{approvals.v1.jsonl,head.v1.json,uses.v1.jsonl}`. The committed `config/relay-authority.v1.example.json` is a template, not a trusted live list. Only the owner edits trusted relayers, channels and `githubOwner`. The example leaves `githubOwner` unset; registration refuses to proceed until the owner configures the real value in the local active profile. The relay CLI takes a JSON input file and profile path; it validates a relayer against the active config before appending. The relaying bot runs the writer CLI outside a guarded Pi session: the Pi shell guard blocks direct approval-ledger access, including this CLI. The writer lock uses exclusive creation and reclaims a lock only after its age exceeds one minute and its PID is demonstrably gone. The head file records count and last hash; a missing final line is detected. A malicious writer able to replace both ledger and head can still rewrite history: no signing key is used.
+
+Tier 0 covers reads and drafts. Tier 1 permits approved private review-branch work, registered-repo spawns and tracked-file removals in reviewable feature-branch commits within approved paths. Tier 2 permits registry additions only after automatic clone, origin and private-visibility verification. Tier 3 remains owner-direct for merges unless separately allowed by merge policy, public publication, force-push, credentials, unrecoverable deletion, registry removals and edits to trusted authority files. Standing approvals expire after seven days by default. A covered spawn skips the native dialog even if the owner is present. Tier 1 tracked-file removal is a documented scope rule, not a mechanical `git rm` path check: the current shell guard permits `git rm` without checking the approved paths. The coordinator continues loading the published npm driver, not this checkout; deployment is a separate owner action.
+
+An authority failure should include `status: needs-owner`, the tier, missing scope, a relayable phrase and next step. A use reservation precedes the spawn mutation and counts toward `maxUses`; a partial attempt is not automatically retried. The write guard rejects direct agent-shell access to approvals paths (including reads) and invocation of the relay writer CLI; use `agentic_relay_check_request` for read-only authority checks. It is not filesystem isolation: an arbitrary program with profile write access can bypass it. Live headless acceptance remains separate from fixture tests.

package/extensions/aidr.ts

@@ -1,3 +1,6 @@
+// SPDX-FileCopyrightText: 2026 evoclock
+// SPDX-License-Identifier: AGPL-3.0-only
+
 import { registerAidrInterface } from "../scripts/aidr_writing_review.js";
 
 export default function registerAidr(pi: any) {

package/extensions/harvest-lessons.ts

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: 2026 evoclock
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { registerHarvestLessons } from "../scripts/harvest_lessons.js";
+
+export default function registerHarvestLessonsExtension(pi: any) {
+  return registerHarvestLessons(pi);
+}

package/extensions/herdr-dispatch.ts

@@ -1,9 +1,36 @@
 // SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
 // SPDX-License-Identifier: AGPL-3.0-only
 
-import { createTaskStore } from "./task-store-adapter.ts";
+import { createTaskStore } from "../lib/task-store-adapter.ts";
+import { mkdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 async function herdrDispatchCore(pi) {
+  const stores = new Map();
+  const getJourneyStore = (context) => {
+    const sessionId = context?.sessionManager?.getSessionId?.();
+    if (typeof sessionId !== "string" || !/^[a-zA-Z0-9_-]{1,128}$/.test(sessionId)) {
+      throw new Error("stable Pi session ID required for durable dispatch");
+    }
+    if (!stores.has(sessionId)) {
+      const pending = (async () => {
+        const directory = join(realpathSync(homedir()), ".pi", "agentic-driver-dispatch", "sessions", sessionId);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        if (realpathSync(directory) !== directory) throw new Error("canonical dispatch store required");
+        const { openDurableSeamStore } = await import(new URL("../scripts/enforcement/durable_assignment_pi.js", import.meta.url).href);
+        return openDurableSeamStore({ directory });
+      })();
+      stores.set(sessionId, pending);
+      pending.catch(() => { if (stores.get(sessionId) === pending) stores.delete(sessionId); });
+    }
+    return stores.get(sessionId);
+  };
+  pi.on?.("session_shutdown", async () => {
+    const opened = [...stores.values()];
+    stores.clear();
+    await Promise.all(opened.map(async (pending) => { try { await (await pending).close(); } catch { /* Open may already have failed. */ } }));
+  });
   const dispatch = await import(new URL("../scripts/enforcement/herdr_async_dispatch_pi.js", import.meta.url).href);
   const lifecycle = await import(new URL("../scripts/enforcement/herdr_lifecycle_pi.js", import.meta.url).href);
 
@@ -27,10 +54,12 @@ async function herdrDispatchCore(pi) {
 
   // A fresh read-only session view per journey; registration remains keyed
   // on the real Pi API identity for the enforcement module's dedupe guard.
-  return dispatch.registerWorkerDispatchInterface(pi, { spawnReplacement, taskStoreFactory: createTaskStore });
+  const outward = await import(new URL("../scripts/enforcement/outward_effect_pi.js", import.meta.url).href);
+  outward.registerOutwardEffectInterface(pi, { getJourneyStore });
+  return dispatch.registerWorkerDispatchInterface(pi, { spawnReplacement, taskStoreFactory: createTaskStore, getJourneyStore });
 }
 
-// Async transport seam (vogelkop phase #47): submit returns a versioned,
+// Async transport seam: submit returns a versioned,
 // non-authorizing receipt immediately; poll/observe/read are separate
 // single-attempt operations. No retries, no resends, no authority.
 export default async function herdrDispatchPi(pi) {

package/extensions/loop-until-done.ts

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export default async function loopUntilDonePi(pi) {
+  const module = await import(new URL("../scripts/enforcement/loop_until_done_pi.js", import.meta.url).href);
+  return module.registerLoopUntilDone(pi);
+}

package/extensions/recovery-evidence.ts

@@ -1,9 +1,9 @@
 // SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
 // SPDX-License-Identifier: AGPL-3.0-only
 
-// Thin extension wrapper for the owner-only recovery-evidence review command.
-// Deliberately registers no model-callable tool: the full evidence surface is
-// the interactive native TUI overlay only. The registration is async (the
+// Thin extension wrapper for owner-only full-evidence review and a bounded,
+// metadata-only summary tool. Full evidence remains in the native TUI overlay;
+// the model never receives entries, identifiers or retrieval references. The registration is async (the
 // trusted root is resolved and snapshotted); Pi awaits an asynchronous
 // default factory before startup continues (extensions.md), so no return
 // value or extra await is needed here.

package/extensions/treehouse-recycle.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { recycleAllPools, TREEHOUSE_ROOT } from "../scripts/enforcement/treehouse_recycle_pi.js";
+
+// Scans every pool under the Treehouse root after session start and
+// periodically, so PR closure/merge is detected without touching the dispatch
+// path. No activity occurs at extension load.
+export function createTreehouseRecycleExtension(
+  recycle = recycleAllPools,
+  rootForSession = async () => TREEHOUSE_ROOT,
+  schedule = setInterval,
+  cancel = clearInterval,
+) {
+  return function (pi: ExtensionAPI) {
+    let timer: ReturnType<typeof setInterval> | undefined;
+    let busy = false;
+    let active = false;
+    let generation = 0;
+    const check = async () => {
+      if (busy || !active) return;
+      busy = true;
+      const started = generation;
+      try {
+        const root = await rootForSession();
+        if (active && started === generation && root) await recycle({ treehouseRoot: root, shouldContinue: () => active && started === generation });
+      } catch (error) {
+        console.error("Treehouse recycling held:", error);
+      } finally { busy = false; }
+    };
+    pi.on("session_start", () => {
+      if (active) return;
+      active = true;
+      void check();
+      const { pollIntervalMs } = JSON.parse(readFileSync(new URL("../config/treehouse.v1.json", import.meta.url), "utf8"));
+      timer = schedule(() => { void check(); }, pollIntervalMs);
+      timer.unref?.();
+    });
+    pi.on("session_shutdown", () => {
+      active = false;
+      generation++;
+      if (timer) cancel(timer);
+      timer = undefined;
+    });
+  };
+}
+
+export default createTreehouseRecycleExtension();

package/janus/README.md

@@ -1,9 +1,7 @@
 # janus — Jev evaluation wrapper service
 
 janus is the local wrapper service for the Jev decision layer. It wraps the
-official `@typesafe-ai/sdk` (TypeSafe Direct — the sole
-provider; the Vercel AI Gateway and merge gateway were dropped by owner
-decision) and exposes one evaluation endpoint plus health/readiness/version
+official `@typesafe-ai/sdk` (the sole configured direct provider) and exposes one evaluation endpoint plus health/readiness/version
 probes on loopback.
 
 ## What janus does
@@ -63,7 +61,7 @@ Dev (from `janus/`):
 npx tsx janus/server.ts          # listens on 127.0.0.1:8787
 ```
 
-Config is read from `~/.config/typesafe-ai/jev/janus-config.json`
+Config is read from the application config directory
 (override with `JANUS_CONFIG_PATH`). Defaults work with no file:
 
 ```json

package/janus/janus/config.ts

@@ -10,8 +10,8 @@
 //
 // Provider architecture (authoritative owner decision): direct TypeSafe
 // (`@typesafe-ai/sdk`, official SDK) is the SOLE provider. The Vercel AI
-// Gateway and the merge gateway are DROPPED — they are not valid config and
-// there is no fallback transport. When TypeSafe Direct is unconfigured the
+// No alternative gateway is valid config and there is no fallback transport.
+// When the configured direct provider is unconfigured the
 // service fails closed (model_unauthorized), with no silent degradation.
 
 import { existsSync, readFileSync } from "node:fs";

package/janus/janus/providers.ts

@@ -6,10 +6,8 @@
 //   1. typesafe-direct    — THE SOLE PROVIDER (owner decision): the official
 //                           @typesafe-ai/sdk (`TypeSafeClient.systemOne`)
 //                           with the owner's direct API key from the macOS
-//                           Keychain (account `typesafe-ai`, service
-//                           `Typesafe AI`). The Vercel AI Gateway and the
-//                           merge gateway are DROPPED — there is no fallback
-//                           transport, and an unconfigured TypeSafe Direct
+//                           Keychain. No alternative gateway or fallback
+//                           transport is configured; an unconfigured direct provider
 //                           fails closed with the existing error taxonomy.
 //
 // Invariants enforced here:

package/janus/tests/providers.test.ts

@@ -4,8 +4,8 @@
 // Adapter mapping tests (review fix #2): the transport contract maps onto the
 // sole provider adapter (typesafe-direct) with mocked clients and NO network,
 // NO live credentials. Question composition (review fix #1), the single-retry
-// policy, and failed-attempt usage accumulation are verified here. The Vercel
-// AI Gateway and the merge gateway are DROPPED — no test references them.
+// policy, and failed-attempt usage accumulation are verified here. No
+// alternative gateway is configured or tested.
 
 import test from "node:test";
 import assert from "node:assert/strict";

package/{extensions → lib}/task-store-adapter.ts

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-FileCopyrightText: 2026 evoclock
 // SPDX-License-Identifier: AGPL-3.0-only
 
 import {
@@ -7,10 +7,6 @@ import {
 } from "../scripts/enforcement/session_tasks_core_pi.js";
 import { createHash } from "node:crypto";
 
-// Pi discovers every packaged extensions/*.ts file. This helper also needs a
-// harmless default factory so discovery can load it without registering tools.
-export default function taskStoreAdapter() {}
-
 // Match TaskList's branch-first/high-water-mark observation in tasks.ts.
 // The session mirror is a fallback; neither reader changes either source.
 function observeSessionTasks(ctx) {

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
+  "scripts": {
+    "test": "node --test tests/test_*.mjs",
+    "test:ci": "node --test tests/test_durable_driver.mjs tests/test_durable_assignment.mjs tests/test_outward_effect.mjs tests/test_herdr_async_dispatch.mjs tests/test_herdr_async_seam.mjs tests/test_herdr_communication.mjs tests/test_fresh_pack_install.mjs tests/test_task_board_dispatch.mjs tests/test_task_store_adapter.mjs tests/test_public_extension_set.mjs"
+  },
   "license": "AGPL-3.0-only",
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.19.0"
   },
   "keywords": [
     "pi-package",
@@ -39,10 +43,19 @@
   "files": [
     "extensions/attended-authority-guard.ts",
     "scripts/enforcement/attended_authority_guard.js",
+    "scripts/enforcement/approval_ledger_pi.js",
+    "scripts/relay/record_approval.mjs",
+    "scripts/relay/send_request.mjs",
+    "config/relay-authority.v1.example.json",
+    "docs/relay-authority.md",
+    "scripts/enforcement/merge_policy.js",
+    "config/merge-policy.v1.example.json",
+    "docs/merge-policy.md",
     "extensions/code-phage.js",
     "extensions/herdr-communication.ts",
     "extensions/herdr-dispatch.ts",
-    "extensions/task-store-adapter.ts",
+    "extensions/loop-until-done.ts",
+    "lib/task-store-adapter.ts",
     "extensions/task-board.ts",
     "extensions/pulse.ts",
     "lib/adapters/diff-scope.mjs",
@@ -56,6 +69,15 @@
     "scripts/enforcement/herdr_communication_pi.js",
     "scripts/enforcement/herdr_async_dispatch_pi.js",
     "scripts/enforcement/herdr_async_seam_pi.js",
+    "scripts/enforcement/loop_until_done_pi.js",
+    "scripts/enforcement/loop_until_done_guide.md",
+    "scripts/enforcement/durable_assignment_pi.js",
+    "scripts/enforcement/storage_owner_lock_pi.js",
+    "scripts/enforcement/durable_driver_pi.js",
+    "scripts/enforcement/durable_driver_pi.d.ts",
+    "docs/durable-driver-api.md",
+    "scripts/enforcement/outward_effect_pi.js",
+    "docs/durable-persistence.md",
     "scripts/enforcement/board_claim_bridge_pi.js",
     "scripts/enforcement/nudge_classifier_pi.js",
     "scripts/enforcement/nudge_config_pi.js",
@@ -66,9 +88,13 @@
     "scripts/enforcement/nudge_reason_state_pi.js",
     "scripts/enforcement/nudge_validate_pi.js",
     ".agentic-driver/nudge.defaults.json",
+    ".agentic-driver/loop-until-done.defaults.json",
     "README.md",
     "LICENSE",
     "extensions/herdr-lifecycle.ts",
+    "extensions/treehouse-recycle.ts",
+    "scripts/enforcement/treehouse_recycle_pi.js",
+    "config/treehouse.v1.json",
     "scripts/enforcement/herdr_lifecycle_pi.js",
     "config/microvm-target.v1.example.json",
     "config/microvm-target.v1.json",
@@ -85,6 +111,7 @@
     ".githooks/pre-commit",
     "templates/AGENTS.md",
     "scripts/enforcement/task_board_core_pi.js",
+    "scripts/enforcement/task_board_hash_pi.js",
     "scripts/enforcement/pulse_core_pi.js",
     "scripts/enforcement/pulse_scheduler_pi.js",
     "scripts/enforcement/router_engine_pi.js",
@@ -97,6 +124,69 @@
     "skills/pulse/SKILL.md",
     "skills/tasks/SKILL.md",
     "skills/decision-to-spec/SKILL.md",
+    "extensions/harvest-lessons.ts",
+    "scripts/harvest_lessons.js",
+    "skills/harvest-lessons",
+    "skills/public-pr-wording/SKILL.md",
+    "skills/public-pr-wording/pr_wording_lint.py",
+    "skills/public-pr-wording/pr_wording_rules.json",
+    "skills/public-pr-wording/pr_wording_config.example.json",
+    "skills/how/LICENSE",
+    "skills/how/WORKFLOW_BOUNDARIES.md",
+    "skills/architect-pi",
+    "skills/arena-pi",
+    "skills/automate-me-pi",
+    "skills/benchmark-checklist-pi",
+    "skills/blast-radius-pi",
+    "skills/bro-pi",
+    "skills/correct-pi",
+    "skills/create-verification-skill-pi",
+    "skills/figure-it-out-pi",
+    "skills/how-pi",
+    "skills/in-your-own-words-pi",
+    "skills/interrogate-pi",
+    "skills/ketchup-pi",
+    "skills/maintain-verification-skill-pi",
+    "skills/make-bot-ui-pi",
+    "skills/no-comments-pi",
+    "skills/poteto-help-pi",
+    "skills/poteto-mode-pi",
+    "skills/principle-attack-the-premise-pi",
+    "skills/principle-boundary-discipline-pi",
+    "skills/principle-build-the-lever-pi",
+    "skills/principle-encode-lessons-in-structure-pi",
+    "skills/principle-exhaust-the-design-space-pi",
+    "skills/principle-experience-first-pi",
+    "skills/principle-explain-the-number-pi",
+    "skills/principle-fix-root-causes-pi",
+    "skills/principle-foundational-thinking-pi",
+    "skills/principle-guard-the-context-window-pi",
+    "skills/principle-laziness-protocol-pi",
+    "skills/principle-make-operations-idempotent-pi",
+    "skills/principle-migrate-callers-then-delete-legacy-apis-pi",
+    "skills/principle-minimize-reader-load-pi",
+    "skills/principle-model-the-domain-pi",
+    "skills/principle-never-block-on-the-human-pi",
+    "skills/principle-outcome-oriented-execution-pi",
+    "skills/principle-prove-it-works-pi",
+    "skills/principle-redesign-from-first-principles-pi",
+    "skills/principle-separate-before-serializing-shared-state-pi",
+    "skills/principle-sequence-verifiable-units-pi",
+    "skills/principle-subtract-before-you-add-pi",
+    "skills/principle-test-behavior-not-implementation-pi",
+    "skills/principle-type-system-discipline-pi",
+    "skills/recall-pi",
+    "skills/reflect-pi",
+    "skills/setup-pstack-pi",
+    "skills/sharpen-pi",
+    "skills/show-me-your-work-pi",
+    "skills/swarm-pi",
+    "skills/tdd-pi",
+    "skills/teach-pi",
+    "skills/technical-writing-pi",
+    "skills/typescript-best-practices-pi",
+    "skills/unslop-pi",
+    "skills/why-pi",
     "extensions/tasks.ts",
     "scripts/enforcement/session_tasks_core_pi.js",
     "scripts/enforcement/session_tasks_validate_pi.js",
@@ -107,14 +197,78 @@
       "./extensions"
     ],
     "skills": [
-      "./skills/decision-to-spec"
+      "./skills/decision-to-spec",
+      "./skills/pulse",
+      "./skills/tasks",
+      "./skills/harvest-lessons",
+      "./skills/public-pr-wording",
+      "./skills/architect-pi",
+      "./skills/arena-pi",
+      "./skills/automate-me-pi",
+      "./skills/benchmark-checklist-pi",
+      "./skills/blast-radius-pi",
+      "./skills/bro-pi",
+      "./skills/correct-pi",
+      "./skills/create-verification-skill-pi",
+      "./skills/figure-it-out-pi",
+      "./skills/how-pi",
+      "./skills/in-your-own-words-pi",
+      "./skills/interrogate-pi",
+      "./skills/ketchup-pi",
+      "./skills/maintain-verification-skill-pi",
+      "./skills/make-bot-ui-pi",
+      "./skills/no-comments-pi",
+      "./skills/poteto-help-pi",
+      "./skills/poteto-mode-pi",
+      "./skills/principle-attack-the-premise-pi",
+      "./skills/principle-boundary-discipline-pi",
+      "./skills/principle-build-the-lever-pi",
+      "./skills/principle-encode-lessons-in-structure-pi",
+      "./skills/principle-exhaust-the-design-space-pi",
+      "./skills/principle-experience-first-pi",
+      "./skills/principle-explain-the-number-pi",
+      "./skills/principle-fix-root-causes-pi",
+      "./skills/principle-foundational-thinking-pi",
+      "./skills/principle-guard-the-context-window-pi",
+      "./skills/principle-laziness-protocol-pi",
+      "./skills/principle-make-operations-idempotent-pi",
+      "./skills/principle-migrate-callers-then-delete-legacy-apis-pi",
+      "./skills/principle-minimize-reader-load-pi",
+      "./skills/principle-model-the-domain-pi",
+      "./skills/principle-never-block-on-the-human-pi",
+      "./skills/principle-outcome-oriented-execution-pi",
+      "./skills/principle-prove-it-works-pi",
+      "./skills/principle-redesign-from-first-principles-pi",
+      "./skills/principle-separate-before-serializing-shared-state-pi",
+      "./skills/principle-sequence-verifiable-units-pi",
+      "./skills/principle-subtract-before-you-add-pi",
+      "./skills/principle-test-behavior-not-implementation-pi",
+      "./skills/principle-type-system-discipline-pi",
+      "./skills/recall-pi",
+      "./skills/reflect-pi",
+      "./skills/setup-pstack-pi",
+      "./skills/sharpen-pi",
+      "./skills/show-me-your-work-pi",
+      "./skills/swarm-pi",
+      "./skills/tdd-pi",
+      "./skills/teach-pi",
+      "./skills/technical-writing-pi",
+      "./skills/typescript-best-practices-pi",
+      "./skills/unslop-pi",
+      "./skills/why-pi"
     ]
   },
   "dependencies": {
+    "@earendil-works/chord": "1.0.4",
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-durable": "1.0.4",
     "typescript": "5.9.2"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/evoclock/pi-agentic-driver.git"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.2.0"
   }
 }

package/scripts/enforcement/approval_ledger_pi.js

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Relayed approval records are attestations by configured relayers, not proof of owner identity.
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, readFileSync, writeFileSync, openSync, closeSync, mkdirSync, statSync, lstatSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const validDate = (value) => typeof value === "string" && /(?:Z|[+-]\d\d:\d\d)$/.test(value) && Number.isFinite(Date.parse(value));
+export function approvalPaths(profile) {
+  if (!profile) throw new Error("profile directory required");
+  return { ledger: join(profile, "approvals/approvals.v1.jsonl"), head: join(profile, "approvals/head.v1.json"), lock: join(profile, "approvals/writer.lock"), uses: join(profile, "approvals/uses.v1.jsonl"), relayers: join(profile, "config/relay-authority.v1.json") };
+}
+export function verifyApprovals(file, headFile = join(file, "../head.v1.json")) {
+  for (const candidate of [file, headFile]) {
+    try { if (!lstatSync(candidate).isFile()) throw new Error("approval file must be regular"); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  let raw;
+  try { raw = readFileSync(file, "utf8"); } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    try { readFileSync(headFile, "utf8"); } catch (headError) { if (headError.code === "ENOENT") return []; throw headError; }
+    throw new Error("approval ledger missing but head exists");
+  }
+  if (raw && !raw.endsWith("\n")) throw new Error("incomplete approval ledger");
+  const entries = [];
+  let previous = null;
+  const ids = new Set();
+  for (const line of raw.split("\n").filter(Boolean)) {
+    const entry = JSON.parse(line);
+    const { hash, ...body } = entry;
+    if (entry.schema !== "relay-approval.v1" || entry.prevHash !== previous || hash !== digest(JSON.stringify(body)) || ids.has(entry.id)) throw new Error("approval chain invalid");
+    ids.add(entry.id);
+    previous = hash;
+    entries.push(entry);
+  }
+  let head;
+  try { head = JSON.parse(readFileSync(headFile, "utf8")); } catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (head ? head.count !== entries.length || head.lastHash !== previous : entries.length !== 0) throw new Error("approval head mismatch");
+  return entries;
+}
+// O_EXCL prevents competing writers. A lock is stale only when both aged and
+// its PID is demonstrably gone; uncertainty fails closed.
+export async function withApprovalLock(profile, operation) {
+  const { lock } = approvalPaths(profile);
+  mkdirSync(join(profile, "approvals"), { recursive: true });
+  for (let attempt = 0; attempt < 50; attempt++) {
+    let fd;
+    try { fd = openSync(lock, "wx", 0o600); }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const snapshot = statSync(lock);
+      if (Date.now() - snapshot.mtimeMs > 60000) {
+        let owner;
+        try { owner = JSON.parse(readFileSync(lock, "utf8")); } catch { /* incomplete lock: fail closed */ }
+        if (Number.isSafeInteger(owner?.pid) && owner.pid > 0) {
+          try { process.kill(owner.pid, 0); } catch (probe) {
+            if (probe.code === "ESRCH" && statSync(lock).ino === snapshot.ino) { unlinkSync(lock); continue; }
+          }
+        }
+      }
+      await sleep(100);
+      continue;
+    }
+    try {
+      writeFileSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+      return await operation();
+    } finally { closeSync(fd); unlinkSync(lock); }
+  }
+  throw new Error("approval writer lock unavailable");
+}
+export async function recordApproval(profile, input) {
+  const paths = approvalPaths(profile);
+  const config = JSON.parse(readFileSync(paths.relayers, "utf8"));
+  const allowed = new Set(["kind", "relayer", "channel", "sourceMessageId", "quote", "quotedQuestion", "givenAt", "scope", "tier", "expiresAt", "maxUses"]);
+  if (!input || Object.keys(input).some((key) => !allowed.has(key))) throw new Error("unexpected approval field");
+  if (!Number.isInteger(input.tier) || input.tier < 1 || input.tier > 2 || !config.relayers?.some((r) => r.relayer === input.relayer && r.channel === input.channel && r.maxTier >= input.tier)) throw new Error("untrusted relayer or tier");
+  if (!["relay", "direct", "standing"].includes(input.kind) || !input.quote?.trim() || !input.quotedQuestion?.trim() || !input.sourceMessageId?.trim() || !validDate(input.givenAt) || !input.scope?.repo || !Array.isArray(input.scope.actions)) throw new Error("incomplete approval");
+  const scope = input.scope;
+  if (typeof scope.repo !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(scope.repo)
+      || Object.keys(scope).some((key) => !["repo", "actions", "paths", "prs", "branches", "models", "roles"].includes(key))
+      || ["actions", "paths", "prs", "branches", "models", "roles"].some((key) => scope[key] !== undefined && (!Array.isArray(scope[key]) || scope[key].some((value) => typeof value !== "string" || !value.trim())))) throw new Error("invalid approval scope");
+  const now = new Date();
+  if (Date.parse(input.givenAt) > now.getTime() || (input.expiresAt && (!validDate(input.expiresAt) || Date.parse(input.expiresAt) <= now.getTime()))) throw new Error("invalid approval time");
+  const expiresAt = input.expiresAt ?? (input.kind === "standing" ? new Date(now.getTime() + 7 * 86400000).toISOString() : null);
+  if (input.maxUses != null && (!Number.isSafeInteger(input.maxUses) || input.maxUses < 1)) throw new Error("invalid use limit");
+  return withApprovalLock(profile, () => {
+    const entries = verifyApprovals(paths.ledger, paths.head);
+    const body = { ...input, scope: { paths: [], prs: [], branches: [], models: [], roles: [], ...input.scope }, schema: "relay-approval.v1", id: randomUUID(), prevHash: entries.at(-1)?.hash ?? null, recordedAt: now.toISOString(), expiresAt };
+    const entry = { ...body, hash: digest(JSON.stringify(body)) };
+    appendFileSync(paths.ledger, JSON.stringify(entry) + "\n", { flag: "a", mode: 0o600 });
+    writeFileSync(paths.head, JSON.stringify({ count: entries.length + 1, lastHash: entry.hash }) + "\n", { mode: 0o600 });
+    return entry;
+  });
+}
+export function authorizeApproval(profile, id, { tier, repository, action, model, role, path, pr, branch }, now = new Date()) {
+  const paths = approvalPaths(profile);
+  const entries = verifyApprovals(paths.ledger);
+  const entry = entries.find((item) => item.id === id);
+  const config = JSON.parse(readFileSync(paths.relayers, "utf8"));
+  const trusted = config.relayers?.some((r) => r.relayer === entry?.relayer && r.channel === entry?.channel && r.maxTier >= tier);
+  const scope = entry?.scope;
+  const used = (() => { try { return readFileSync(paths.uses, "utf8").split("\n").filter(Boolean).map(JSON.parse).filter((use) => use.ledgerId === id && use.result === "reserved").length; } catch (error) { if (error.code === "ENOENT") return 0; throw error; } })();
+  if (!entry || config.revokedIds?.includes(id) || tier > 2 || entry.tier < tier || !trusted || !scope || scope.repo !== repository || (tier === 2 && !entry.quote.includes(repository)) || !scope.actions?.includes(action) || (model && !scope.models?.includes(model)) || (role && !scope.roles?.includes(role)) || (path && !scope.paths?.includes(path)) || (pr && !scope.prs?.includes(pr)) || (branch && !scope.branches?.includes(branch)) || (entry.expiresAt && Date.parse(entry.expiresAt) <= now.getTime()) || (entry.maxUses != null && used >= entry.maxUses)) throw new Error("approval does not cover action");
+  return entry;
+}
+// The header names candidate records only. Each requested action is checked
+// against stored scope; prose in the request does not add permissions.
+export function checkRelayRequests(profile, header, requests) {
+  const match = /^\[relay:v1 ledger=([a-f0-9-]{36}(?:,[a-f0-9-]{36})*) relayer=([a-z][a-z0-9-]*)\]$/.exec(header ?? "");
+  return requests.map((request) => {
+    if (match && request.tier < 3) {
+      for (const id of match[1].split(",")) {
+        try {
+          const entry = authorizeApproval(profile, id, request);
+          if (entry.relayer === match[2]) return { status: "covered", ledgerId: id, tier: request.tier };
+        } catch { /* No record covers this particular action. */ }
+      }
+    }
+    return { status: "needs-owner", tier: request.tier, missing: [request.action], relayablePhrase: `Approve ${request.action} for ${request.repository}`, nextStep: request.tier === 3 ? "Request direct owner approval at the action boundary." : "Relay the scoped approval with its source and record it." };
+  });
+}
+export async function reserveApprovalUse(profile, ledgerId, request, operation) {
+  return withApprovalLock(profile, async () => {
+    const entry = authorizeApproval(profile, ledgerId, request);
+    appendFileSync(approvalPaths(profile).uses, JSON.stringify({ use: randomUUID(), ledgerId, action: request.action, target: request.repository, result: "reserved", at: new Date().toISOString() }) + "\n", { mode: 0o600 });
+    return operation ? operation(entry) : entry;
+  });
+}
+export async function recordApprovalUse(profile, ledgerId, action, target, result) {
+  return withApprovalLock(profile, () => {
+    const path = approvalPaths(profile).uses;
+    appendFileSync(path, JSON.stringify({ use: randomUUID(), ledgerId, action, target, result, at: new Date().toISOString() }) + "\n", { mode: 0o600 });
+  });
+}