@evoclock/pi-agentic-driver 1.1.2 → 2.0.0

package/scripts/enforcement/recovery_evidence_review_pi.js

@@ -208,9 +208,9 @@ export async function createEvidenceOverlay({ done, lines, tui }) {
 }
 
 /**
- * Registers ONLY the owner-initiated slash command. No model-callable tool is
- * registered here, and no raw-evidence tool may be added later: the full
- * evidence travels exclusively through the native TUI overlay. The trusted
+ * Registers the owner-initiated full-evidence command and a model-callable
+ * metadata-only summary. No raw-evidence tool is registered: full evidence
+ * travels exclusively through the native TUI overlay. The trusted
  * root is snapshotted once at registration so a later in-process environment
  * mutation cannot redirect review to a different store mid-session; the
  * snapshot still honors the trusted host context that existed at load time.
@@ -219,6 +219,34 @@ export async function registerRecoveryEvidenceReview(pi, _options = {}) {
   if (typeof pi?.registerCommand !== "function" || REGISTRATIONS.has(pi)) return;
   REGISTRATIONS.add(pi);
   const registeredRoot = resolveReviewEvidenceRoot();
+  if (typeof pi.registerTool === "function") pi.registerTool({
+    name: "agentic_recovery_evidence_summary",
+    label: "Recovery Evidence Summary",
+    description: "Read-only counts of up to 50 recent recovery records. No evidence content, identifiers, references, or authorization is returned.",
+    parameters: { type: "object", additionalProperties: false, properties: {} },
+    async execute(_toolCallId, params) {
+      const shape = (value) => ({ schema: "agentic-driver.recovery-evidence-summary.v1", nonAuthorizing: true, ...value });
+      let summary;
+      if (!params || typeof params !== "object" || Array.isArray(params) || Object.keys(params).length !== 0) {
+        summary = shape({ status: "invalid-arguments" });
+      } else {
+        let listing;
+        try { listing = listReviewableReferences({ root: registeredRoot, limit: REVIEW_LIST_LIMIT }); }
+        catch { listing = { ok: false }; }
+        if (!listing.ok || !Array.isArray(listing.references)
+          || listing.references.some((ref) => !["requested", "terminal"].includes(ref.phase))) {
+          summary = shape({ status: listing.code === "evidence-store-missing" ? "store-missing" : "unavailable" });
+        } else {
+          summary = shape({ status: "available", observed: listing.references.length,
+            requested: listing.references.filter((ref) => ref.phase === "requested").length,
+            terminal: listing.references.filter((ref) => ref.phase === "terminal").length,
+            limit: REVIEW_LIST_LIMIT, possiblyMore: listing.references.length === REVIEW_LIST_LIMIT,
+            verification: "metadata-only" });
+        }
+      }
+      return { content: [{ type: "text", text: JSON.stringify(summary) }], details: summary };
+    },
+  });
   const notify = (context, message, type) => {
     if (typeof context?.ui?.notify === "function") context.ui.notify(message, type);
   };

package/scripts/enforcement/storage_owner_lock_pi.js

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
+function processStart(pid) {
+  return execFileSync("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf8", timeout: 2000 }).trim();
+}
+
+export function claimSeamLock(directory) {
+  const lock = join(directory, "owner.lock");
+  const gate = join(directory, "owner-reclaim.lock");
+  const owner = { pid: process.pid, hostname: hostname(), start: processStart(process.pid), token: randomUUID() };
+  if (!owner.start || existsSync(gate)) throw new Error("storage ownership or reclamation unknown; reconcile manually");
+  let heldGate = false;
+  let stale;
+  try {
+    try { mkdirSync(lock, { mode: 0o700 }); }
+    catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try { mkdirSync(gate, { mode: 0o700 }); }
+      catch { throw new Error("storage reclamation in progress or uncertain; reconcile manually"); }
+      heldGate = true;
+      let previous;
+      try { previous = JSON.parse(readFileSync(join(lock, "owner.json"), "utf8")); }
+      catch { throw new Error("storage owner unknown; reconcile lock manually"); }
+      if (previous.hostname !== owner.hostname || !Number.isSafeInteger(previous.pid) || previous.pid < 1 ||
+          typeof previous.start !== "string" || !previous.start) throw new Error("storage owner unverified");
+      let dead = false;
+      try { process.kill(previous.pid, 0); }
+      catch (failure) {
+        if (failure.code !== "ESRCH") throw new Error("storage owner liveness unknown");
+        dead = true;
+      }
+      if (!dead) {
+        let observed;
+        try { observed = processStart(previous.pid); }
+        catch { throw new Error("storage owner start time unknown"); }
+        if (!observed || observed === previous.start) throw new Error("storage owner is still active");
+      }
+      stale = join(directory, `owner-stale-${randomUUID()}`);
+      try { renameSync(lock, stale); }
+      catch { throw new Error("storage owner changed during reclamation; reconcile manually"); }
+      mkdirSync(lock, { mode: 0o700 });
+    }
+    if (!heldGate && existsSync(gate)) throw new Error("storage reclamation raced admission; reconcile manually");
+    writeFileSync(join(lock, "owner.json"), JSON.stringify(owner), { flag: "wx", mode: 0o600 });
+    if (stale) {
+      unlinkSync(join(stale, "owner.json"));
+      rmdirSync(stale);
+    }
+    return { path: lock, token: owner.token };
+  } finally {
+    if (heldGate) rmdirSync(gate);
+  }
+}
+
+export function releaseSeamLock(lease) {
+  const owner = JSON.parse(readFileSync(join(lease.path, "owner.json"), "utf8"));
+  if (owner.token !== lease.token) throw new Error("storage owner changed; refusing to release another owner");
+  unlinkSync(join(lease.path, "owner.json"));
+  rmdirSync(lease.path);
+}

package/scripts/enforcement/task_board_core_pi.js

@@ -11,7 +11,7 @@
 // hashes; presentation is excluded from the hash; every disagreement between
 // surfaces fails closed.
 
-import { createHash, createHmac, randomBytes } from "node:crypto";
+import { createHmac, randomBytes } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, openSync, closeSync, unlinkSync, chmodSync, statSync as fsStatSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { dirname, join } from "node:path";
@@ -20,6 +20,14 @@ import { dirname, join } from "node:path";
 // are the pure router libraries; the board writer never mutates them.
 import { isDeadRoute } from "./router_replacement_pi.js";
 import { getRouteDecisionIdByDigest } from "./router_store_pi.js";
+import {
+  nfc, canonicalJson, canonicalJsonString, sha256Hex, sanitizeFreeText,
+  encodeFieldText, decodeFieldText, hashPayload, computeCardHash, computeSpecHash,
+} from "./task_board_hash_pi.js";
+export {
+  canonicalJson, canonicalJsonString, sha256Hex, sanitizeFreeText,
+  encodeFieldText, decodeFieldText, hashPayload, computeCardHash, computeSpecHash,
+};
 
 // ---------------------------------------------------------------------------
 // Closed vocabularies (§1)
@@ -68,103 +76,8 @@ const HTML_ID_MARKER_RE = /<!--\s*id:\s*([^>]*?)\s*-->/g;
 const EMOJI_RE = /[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{FE0F}\u{2194}-\u{21AA}]/gu;
 const EMOJI_DATE_RE = /📅\s*(\d{4}-\d{2}-\d{2})/u;
 
-function nfc(value) {
-  return typeof value === "string" ? value.normalize("NFC") : value;
-}
-
-// ---------------------------------------------------------------------------
-// Hash canonicalization (§1): SHA-256 over canonical JSON of the
-// authority-bearing fields only. Keys recursively sorted; absent optional
-// fields omitted (never null); strings NFC-normalized; presentation excluded.
-// ---------------------------------------------------------------------------
-
-export function canonicalJson(value) {
-  if (value === null || value === undefined) return undefined;
-  if (typeof value === "string") return nfc(value);
-  if (typeof value === "number" || typeof value === "boolean") return value;
-  if (Array.isArray(value)) return value.map((entry) => canonicalJson(entry));
-  if (typeof value === "object") {
-    const out = {};
-    for (const key of Object.keys(value).sort()) {
-      const normalized = canonicalJson(value[key]);
-      if (normalized !== undefined) out[key] = normalized;
-    }
-    return out;
-  }
-  return undefined;
-}
-
-export function canonicalJsonString(value) {
-  return JSON.stringify(canonicalJson(value));
-}
-
-export function sha256Hex(text) {
-  return createHash("sha256").update(text, "utf8").digest("hex");
-}
-
-// Free-text (titles, quoted instructions) is sanitized before it is ever
-// serialized into a card line: [key:: value] field syntax, stray "]", and
-// HTML-comment syntax are stripped so a hostile string cannot alter parsing
-// (§6 gate 3). Sanitization is lossy by design — it fails closed.
-export function sanitizeFreeText(text) {
-  return String(text ?? "").normalize("NFC")
-    .replace(/<!--[\s\S]*?-->/g, " ")
-    .replace(/<!--|-->/g, " ")
-    .replace(/\[[A-Za-z][A-Za-z0-9_-]*::[^\]]*\]?/g, " ")
-    .replace(/\]/g, ")")
-    .replace(/\s+/g, " ").trim();
-}
-
-// Spec/DoD text travels base64url-encoded inside a [key:: value] field: the
-// encoding round-trips byte-for-byte (so the dispatch gate can recompute the
-// hash) and cannot inject field or HTML-comment syntax.
-export function encodeFieldText(text) {
-  return Buffer.from(String(text ?? ""), "utf8").toString("base64url");
-}
-
-// F2: only the canonical base64url encoding is accepted. The decoded bytes
-// are re-encoded and compared to the original string exactly, so a permissive
-// decoder cannot smuggle non-canonical input ('***' and friends decode to
-// nothing usable and are rejected).
-export function decodeFieldText(encoded) {
-  if (typeof encoded !== "string" || encoded === "") return null;
-  try {
-    const decoded = Buffer.from(encoded, "base64url").toString("utf8");
-    if (Buffer.from(decoded, "utf8").toString("base64url") !== encoded) return null;
-    return decoded;
-  } catch {
-    return null;
-  }
-}
-
-// The authority-bearing field set. The authority-source reference is NOT
-// hash-bearing: it is recorded alongside the card, outside this payload.
-// §1 scope = paths + capability classes + explicitly unchanged paths +
-// repository identity (for user-level cards) — all hash-bearing.
-const AUTHORITY_FIELDS = Object.freeze([
-  "cardId", "lane", "flags", "priority", "dependencies", "base",
-  "specHash", "dodHash", "stoppingPoint", "scope", "unchangedPaths",
-  "capabilities", "repositories",
-]);
-
-export function hashPayload(card) {
-  const payload = {};
-  for (const field of AUTHORITY_FIELDS) {
-    const value = card[field];
-    if (value === undefined || value === null) continue;
-    if (Array.isArray(value) && value.length === 0) continue;
-    payload[field] = value;
-  }
-  return payload;
-}
-
-export function computeCardHash(card) {
-  return sha256Hex(canonicalJsonString(hashPayload(card)));
-}
-
-export function computeSpecHash(specText) {
-  return sha256Hex(nfc(String(specText)));
-}
+// Hash/text primitives live in task_board_hash_pi.js; the public board-core
+// exports above preserve every caller's existing API.
 
 // ---------------------------------------------------------------------------
 // Title stripping / normalization (§2): fields, emoji, and the ID marker are
@@ -182,7 +95,7 @@ export function stripTitle(rawTitle) {
 
 // ---------------------------------------------------------------------------
 // Parsers (§2). One tokenizer handles both surface shapes: Obsidian Kanban
-// Markdown ([id:: ...] Dataview marker) and vogelkop TASKS.md
+// Markdown ([id:: ...] Dataview marker) and external TASKS.md
 // (<!-- id: ... --> HTML-comment marker). Unknown ## headings are rejected;
 // [-] cancelled checkboxes map to #cancelled; indented continuation lines are
 // description text.
@@ -379,7 +292,7 @@ function safeJsonParse(text) {
   }
 }
 
-const CAPABILITY_REGISTRY_PATH = ".vogelkop/capabilities.json";
+const CAPABILITY_REGISTRY_PATH = ".agentic-driver/capabilities.json";
 
 function capabilityRegistryError(registryPath, reason) {
   return Object.assign(new Error(`capability registry is invalid at ${registryPath}: ${reason}`), {

package/scripts/enforcement/task_board_hash_pi.js

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 evoclock
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Canonical, authority-bearing board payload and free-text encodings.
+// Both surface parsers and the trusted writer use the same pure primitives.
+import { createHash } from "node:crypto";
+
+export function nfc(value) {
+  return typeof value === "string" ? value.normalize("NFC") : value;
+}
+
+// Keys recursively sorted; absent optional fields omitted; strings normalized.
+export function canonicalJson(value) {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value === "string") return nfc(value);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) return value.map((entry) => canonicalJson(entry));
+  if (typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const normalized = canonicalJson(value[key]);
+      if (normalized !== undefined) out[key] = normalized;
+    }
+    return out;
+  }
+  return undefined;
+}
+
+export function canonicalJsonString(value) {
+  return JSON.stringify(canonicalJson(value));
+}
+
+export function sha256Hex(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+// Sanitize field and HTML-comment syntax before serializing free text.
+export function sanitizeFreeText(text) {
+  return String(text ?? "").normalize("NFC")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<!--|-->/g, " ")
+    .replace(/\[[A-Za-z][A-Za-z0-9_-]*::[^\]]*\]?/g, " ")
+    .replace(/\]/g, ")")
+    .replace(/\s+/g, " ").trim();
+}
+
+export function encodeFieldText(text) {
+  return Buffer.from(String(text ?? ""), "utf8").toString("base64url");
+}
+
+export function decodeFieldText(encoded) {
+  if (typeof encoded !== "string" || encoded === "") return null;
+  try {
+    const decoded = Buffer.from(encoded, "base64url").toString("utf8");
+    if (Buffer.from(decoded, "utf8").toString("base64url") !== encoded) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+// Authority-source reference and presentation fields are outside this hash.
+const AUTHORITY_FIELDS = Object.freeze([
+  "cardId", "lane", "flags", "priority", "dependencies", "base",
+  "specHash", "dodHash", "stoppingPoint", "scope", "unchangedPaths",
+  "capabilities", "repositories",
+]);
+
+export function hashPayload(card) {
+  const payload = {};
+  for (const field of AUTHORITY_FIELDS) {
+    const value = card[field];
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    payload[field] = value;
+  }
+  return payload;
+}
+
+export function computeCardHash(card) {
+  return sha256Hex(canonicalJsonString(hashPayload(card)));
+}
+
+export function computeSpecHash(specText) {
+  return sha256Hex(nfc(String(specText)));
+}

package/scripts/enforcement/treehouse_recycle_pi.js

@@ -0,0 +1,145 @@
+// Treehouse owns the pool. This scanner only returns settled, clean, pushed
+// leases; it never removes worktrees or checks out branches itself.
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+const TREEHOUSE_CONFIG = JSON.parse(readFileSync(new URL("../../config/treehouse.v1.json", import.meta.url), "utf8"));
+export const TREEHOUSE_VERSION = TREEHOUSE_CONFIG.version;
+export const TREEHOUSE_ROOT = TREEHOUSE_CONFIG.root ?? join(homedir(), ".treehouse");
+const execFileAsync = promisify(execFile);
+
+export async function commandRunner(file, args, cwd) {
+  const { stdout } = await execFileAsync(file, args, { cwd, encoding: "utf8", timeout: 15000, maxBuffer: 2 * 1024 * 1024 });
+  return stdout.trim();
+}
+
+function git(run, cwd, ...args) { return run("git", args, cwd); }
+
+/** Runs only from the main repository checkout; never scans another pool. */
+export async function recycleTreehouse({ root, run = commandRunner, current = process.cwd(), shouldContinue = () => true }) {
+  const report = [];
+  const repo = realpathSync(root);
+  if (realpathSync(await git(run, repo, "rev-parse", "--show-toplevel")) !== repo) throw new Error("Treehouse scan requires the repository root");
+  const versions = [...(await run("treehouse", ["--version"], repo)).matchAll(/(?:^|\s)(v\d+\.\d+\.\d+)(?=\s|$)/g)];
+  if (versions.length !== 1 || versions[0][1] !== TREEHOUSE_VERSION) throw new Error("Treehouse version does not match the pinned version");
+  const remote = await git(run, repo, "remote", "get-url", "origin");
+  const match = remote.match(/^(?:https:\/\/github\.com\/|git@github\.com:)([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/);
+  if (!match) throw new Error("unrecognized GitHub origin; refusing Treehouse recycling");
+  const repository = match[1];
+  const slots = JSON.parse(await run("treehouse", ["status", "--json"], repo));
+  if (!Array.isArray(slots)) throw new Error("invalid Treehouse status");
+  const here = realpathSync(current);
+  for (const slot of slots) {
+    if (!shouldContinue()) break;
+    if (slot?.status !== "leased" || !slot.lease_id || !slot.lease_holder ||
+        !slot.branch || !Array.isArray(slot.processes) || slot.processes.length || !slot.path) continue;
+    // Never return the checkout containing this process, even if a process probe misses it.
+    let path;
+    try { path = realpathSync(slot.path); } catch { continue; }
+    if (here === path || here.startsWith(path + "/") || path === repo) continue;
+    try {
+      if (realpathSync(await git(run, path, "rev-parse", "--show-toplevel")) !== path ||
+          await git(run, path, "branch", "--show-current") !== slot.branch ||
+          await git(run, path, "status", "--porcelain", "--untracked-files=all", "--ignored=matching")) continue;
+      const head = await git(run, path, "rev-parse", "HEAD");
+      // A merged PR with the exact head proves this checkout was integrated.
+      // A closed but unmerged PR never authorizes a return. Pagination keeps
+      // older merged heads from being hidden by a result cap.
+      const pages = await run("gh", ["api", "--method", "GET", `repos/${repository}/pulls`,
+        "-f", "state=closed", "-f", `head=${repository.split("/")[0]}:${slot.branch}`,
+        "-f", "per_page=100", "--paginate", "--jq",
+        '[.[] | {headRefName:.head.ref,headRefOid:.head.sha,owner:.head.repo.owner.login,mergedAt:.merged_at}]'], repo);
+      const prs = pages.split("\n").filter(Boolean).flatMap(page => {
+        const entries = JSON.parse(page);
+        if (!Array.isArray(entries)) throw new Error("invalid paginated PR response");
+        return entries;
+      });
+      if (!prs.some(pr => pr.headRefName === slot.branch &&
+          pr.headRefOid === head && pr.owner === repository.split("/")[0] &&
+          typeof pr.mergedAt === "string" && Number.isFinite(Date.parse(pr.mergedAt)))) continue;
+      // A concurrent new commit, dirty write, or lease change is caught again by
+      // Treehouse's conditional return. Never use --force or --all.
+      if (await git(run, path, "rev-parse", "HEAD") !== head ||
+          await git(run, path, "status", "--porcelain", "--untracked-files=all", "--ignored=matching") ||
+          !shouldContinue()) continue;
+      await run("treehouse", ["return", path, "--if-lease-id", slot.lease_id,
+        "--if-lease-holder", slot.lease_holder], repo);
+      report.push({ branch: slot.branch, status: "returned" });
+    } catch (error) {
+      report.push({ branch: slot.branch, status: "held", reason: String(error.message) });
+    }
+  }
+  return report;
+}
+
+const defaultReadDir = (path) => readdirSync(path, { withFileTypes: true });
+
+function containsGitWorktree(dir, readDir, depth = 2) {
+  if (depth < 0) return false;
+  if (existsSync(join(dir, ".git"))) return true;
+  let entries;
+  try { entries = readDir(dir); } catch { return false; }
+  return entries.some(entry => entry.isDirectory() && containsGitWorktree(join(dir, entry.name), readDir, depth - 1));
+}
+
+/** Finds the main checkout owning one slot worktree via its git common dir. */
+async function repoForPool(pool, run, readDir) {
+  let slots;
+  try { slots = readDir(pool); } catch { return undefined; }
+  for (const slot of slots) {
+    if (!slot.isDirectory()) continue;
+    let children;
+    try { children = readDir(join(pool, slot.name)); } catch { continue; }
+    for (const child of children) {
+      if (!child.isDirectory() || !existsSync(join(pool, slot.name, child.name, ".git"))) continue;
+      const worktree = join(pool, slot.name, child.name);
+      const common = await git(run, worktree, "rev-parse", "--path-format=absolute", "--git-common-dir");
+      return dirname(realpathSync(common));
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Sweeps every Treehouse pool under the treehouse root: managed pools are
+ * recycled per owning repository; directories holding plain git worktrees
+ * outside any pool are flagged as strays and never touched.
+ */
+export async function recycleAllPools({ treehouseRoot = TREEHOUSE_ROOT, run = commandRunner, current = process.cwd(), shouldContinue = () => true, readDir = defaultReadDir }) {
+  const report = [];
+  let entries;
+  try { entries = readDir(treehouseRoot); } catch (error) {
+    return [{ pool: treehouseRoot, status: "held", reason: String(error.message) }];
+  }
+  const repos = new Map();
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !shouldContinue()) continue;
+    const pool = join(treehouseRoot, entry.name);
+    if (existsSync(join(pool, "treehouse-state.json"))) {
+      try {
+        const repo = await repoForPool(pool, run, readDir);
+        if (repo && !repos.has(repo)) repos.set(repo, pool);
+      } catch (error) {
+        report.push({ pool, status: "held", reason: String(error.message) });
+      }
+    } else if (containsGitWorktree(pool, readDir)) {
+      // A plain git worktree under the Treehouse root is invisible to every
+      // pool command; flag it so a human can salvage and remove it by hand.
+      report.push({ pool, status: "stray", reason: "git worktree outside any Treehouse pool" });
+    }
+  }
+  for (const [repo, pool] of repos) {
+    if (!shouldContinue()) break;
+    try {
+      for (const item of await recycleTreehouse({ root: repo, run, current, shouldContinue })) {
+        report.push({ pool, ...item });
+      }
+    } catch (error) {
+      report.push({ pool, status: "held", reason: String(error.message) });
+    }
+  }
+  return report;
+}