@evoclock/pi-agentic-driver 0.10.0 → 1.0.0

package/scripts/enforcement/recovery_evidence_store_pi.js

@@ -0,0 +1,170 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Owner-local, non-authorizing recovery evidence. Nothing in the journey calls
+// this module yet. The host chooses a private root; the store never chooses an
+// implicit repository or app-data path and never evicts evidence on its own.
+import { DatabaseSync } from "node:sqlite";
+import { createHash } from "node:crypto";
+import { constants, closeSync, existsSync, lstatSync, mkdirSync, openSync, realpathSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { appendTerminalResult, nudgeCanonicalJsonString, validateLedgerEntry } from "./nudge_ledger_pi.js";
+
+export const RECOVERY_EVIDENCE_SCHEMA = "agentic-driver.recovery-evidence.v1";
+const FILE = "recovery-evidence.v1.sqlite";
+const SHA256 = /^[a-f0-9]{64}$/;
+
+function refuse(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function positiveBound(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1) throw refuse("invalid-bound", `${name} must be a positive safe integer`);
+  return value;
+}
+
+function privateRoot(root, create) {
+  if (typeof root !== "string" || !isAbsolute(root) || resolve(root) !== root) {
+    throw refuse("invalid-root", "a canonical absolute owner-provided root is required");
+  }
+  if (create && !existsSync(root)) mkdirSync(root, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(root);
+  if (!stat.isDirectory() || (stat.mode & 0o077) !== 0 || realpathSync(root) !== root) {
+    throw refuse("untrusted-root", "evidence root must be a private, non-symlink directory");
+  }
+  return root;
+}
+
+function evidenceFile(root, create) {
+  const path = join(root, FILE);
+  if (create && !existsSync(path)) {
+    try {
+      const fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+      closeSync(fd);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+  }
+  const stat = lstatSync(path);
+  if (!stat.isFile() || (stat.mode & 0o077) !== 0 || realpathSync(path) !== path) {
+    throw refuse("untrusted-file", "evidence file must be private and not a symlink");
+  }
+  return path;
+}
+
+/** Explicit host root; readOnly observation never creates a directory or file. */
+export function openRecoveryEvidenceStore({ root, readOnly = false, maxRecordBytes = 128 * 1024, maxTotalBytes = 16 * 1024 * 1024, maxRecords = 1000 } = {}) {
+  positiveBound(maxRecordBytes, "maxRecordBytes");
+  positiveBound(maxTotalBytes, "maxTotalBytes");
+  positiveBound(maxRecords, "maxRecords");
+  const path = evidenceFile(privateRoot(root, !readOnly), !readOnly);
+  const db = new DatabaseSync(path, { readOnly });
+  try {
+    db.exec("PRAGMA busy_timeout = 5000;");
+    if (!readOnly) db.exec(`
+      CREATE TABLE IF NOT EXISTS evidence (
+        journey_id TEXT NOT NULL, entry_id TEXT NOT NULL,
+        phase TEXT NOT NULL CHECK(phase IN ('requested','terminal')),
+        body TEXT NOT NULL, digest TEXT NOT NULL, previous_digest TEXT,
+        bytes INTEGER NOT NULL, created_at TEXT NOT NULL,
+        PRIMARY KEY (journey_id, entry_id, phase)
+      );
+    `);
+  } catch (error) { db.close(); throw error; }
+  return { db, path, readOnly, maxRecordBytes, maxTotalBytes, maxRecords };
+}
+
+export function closeRecoveryEvidenceStore(store) {
+  store.db.close();
+}
+
+function digest(text) { return createHash("sha256").update(text, "utf8").digest("hex"); }
+
+function reference(row) {
+  return Object.freeze({ schema: RECOVERY_EVIDENCE_SCHEMA, journeyId: row.journey_id,
+    entryId: row.entry_id, phase: row.phase, sha256: row.digest, bytes: row.bytes });
+}
+
+function fetchRow(store, { journeyId, entryId, phase }) {
+  return store.db.prepare("SELECT * FROM evidence WHERE journey_id=? AND entry_id=? AND phase=?")
+    .get(journeyId, entryId, phase);
+}
+
+/** Bounded, read-only listing of closed retrieval references; never bodies. */
+export function listRecoveryEvidenceReferences(store, { limit = 50 } = {}) {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw refuse("invalid-bound", "limit must be a positive safe integer");
+  return store.db.prepare(
+    "SELECT journey_id, entry_id, phase, digest, bytes FROM evidence ORDER BY created_at DESC, journey_id, entry_id, phase LIMIT ?",
+  ).all(limit).map((row) => reference(row));
+}
+
+/** Returns exact bytes only when the caller's reference and its predecessor verify. */
+export function readRecoveryEvidence(store, ref) {
+  if (!ref || ref.schema !== RECOVERY_EVIDENCE_SCHEMA || !["requested", "terminal"].includes(ref.phase)
+    || typeof ref.journeyId !== "string" || !ref.journeyId || typeof ref.entryId !== "string" || !ref.entryId
+    || !SHA256.test(ref.sha256 ?? "") || !Number.isSafeInteger(ref.bytes) || ref.bytes < 1) {
+    throw refuse("invalid-reference", "a complete evidence reference is required");
+  }
+  const row = fetchRow(store, ref);
+  if (!row) throw refuse("evidence-missing", "referenced recovery evidence is unavailable");
+  if (row.digest !== ref.sha256 || row.bytes !== ref.bytes || digest(row.body) !== row.digest
+    || Buffer.byteLength(row.body, "utf8") !== row.bytes) {
+    throw refuse("evidence-corrupt", "recovery evidence digest or size mismatch");
+  }
+  let entry;
+  try { entry = JSON.parse(row.body); } catch { throw refuse("evidence-corrupt", "recovery evidence is not valid JSON"); }
+  if (entry.journeyId !== ref.journeyId || entry.entryId !== ref.entryId || !validateLedgerEntry(entry).ok
+    || (ref.phase === "requested" && entry.result !== "requested")
+    || (ref.phase === "terminal" && entry.result === "requested")) {
+    throw refuse("evidence-corrupt", "recovery evidence does not match its identity and phase");
+  }
+  if (ref.phase === "terminal") {
+    const parent = fetchRow(store, { ...ref, phase: "requested" });
+    if (!parent || row.previous_digest !== parent.digest || digest(parent.body) !== parent.digest) {
+      throw refuse("evidence-corrupt", "terminal evidence has no intact requested predecessor");
+    }
+  }
+  return { reference: reference(row), entry };
+}
+
+function append(store, entry, phase, previousDigest = null) {
+  if (store.readOnly) throw refuse("read-only", "evidence store is read-only");
+  const body = nudgeCanonicalJsonString(entry);
+  const bytes = Buffer.byteLength(body, "utf8");
+  if (bytes > store.maxRecordBytes) throw refuse("evidence-too-large", "recovery record exceeds per-record bound");
+  store.db.exec("BEGIN IMMEDIATE;");
+  try {
+    const usage = store.db.prepare("SELECT COUNT(*) AS count, COALESCE(SUM(bytes),0) AS bytes FROM evidence").get();
+    if (usage.count >= store.maxRecords || usage.bytes + bytes > store.maxTotalBytes) {
+      throw refuse("evidence-capacity", "owner review or increased capacity is required; unreviewed evidence is never evicted");
+    }
+    store.db.prepare("INSERT INTO evidence VALUES (?,?,?,?,?,?,?,?)").run(
+      entry.journeyId, entry.entryId, phase, body, digest(body), previousDigest, bytes, new Date().toISOString());
+    store.db.exec("COMMIT;");
+  } catch (error) {
+    store.db.exec("ROLLBACK;");
+    if (String(error.message).startsWith("UNIQUE constraint failed: evidence.")) {
+      throw refuse("evidence-duplicate", "recovery phase already recorded");
+    }
+    throw error;
+  }
+  return reference({ journey_id: entry.journeyId, entry_id: entry.entryId, phase, digest: digest(body), bytes });
+}
+
+/** Must succeed before the caller attempts any nudge or replacement. */
+export function recordRecoveryRequest(store, entry) {
+  const valid = validateLedgerEntry(entry);
+  if (!valid.ok || entry.result !== "requested") throw refuse("invalid-entry", "a valid requested ledger entry is required");
+  return append(store, entry, "requested");
+}
+
+/** A failed post-action write is ambiguous; callers must retain their identity lock. */
+export function recordRecoveryResult(store, requestedRef, terminal) {
+  if (!requestedRef || requestedRef.phase !== "requested") throw refuse("invalid-reference", "requested evidence reference required");
+  const requested = readRecoveryEvidence(store, requestedRef);
+  if (fetchRow(store, { ...requestedRef, phase: "terminal" })) {
+    throw refuse("evidence-duplicate", "terminal evidence already recorded; never replay an action");
+  }
+  const [entry] = appendTerminalResult([requested.entry], requested.entry.entryId, terminal);
+  return append(store, entry, "terminal", requestedRef.sha256);
+}

package/scripts/enforcement/session_tasks_core_pi.js

@@ -36,6 +36,7 @@ export const TASK_PROMOTION_SCHEMA = "agentic-driver.task-promotion.v1";
 export const TASK_STATE_ENTRY = "picc-tasks-state";
 export const SESSION_TASK_STATUSES = Object.freeze(["pending", "in_progress", "completed"]);
 export const TASK_LIST_STATUSES = Object.freeze(["pending", "in_progress", "completed"]);
+export const SESSION_TASK_PRIORITIES = Object.freeze(["P0", "P1", "P2", "P3"]);
 export const ORIGIN_VALUES = Object.freeze(["coordinator", "worker"]);
 export const LEGACY_UNKNOWN_ORIGIN = "legacy-unknown";
 export const PROMOTED_TASK_STATUSES = Object.freeze(["pending", "in_progress"]);
@@ -43,14 +44,27 @@ export const PROMOTION_LANES = Object.freeze(["backlog", "in-progress"]);
 export const COMPLETED_TASK_POLICY = Object.freeze(["skip", "promote-as-done"]);
 export const BATCH_END_POLICY = Object.freeze(["offered", "off"]);
 export const TRUSTED_HERDR_EXECUTABLE = "/opt/homebrew/bin/herdr";
+export const PROVENANCE_CAPTURE_STATUSES = Object.freeze([
+  "captured", "host-session-unavailable", "task-list-mismatch", "source-unavailable",
+]);
 export const DEFAULT_PROMOTION_LANE = "backlog";
 
+// Deterministic opaque display token for model-visible evidence. Session task
+// IDs are unbounded caller-controlled strings that can carry secret-like text;
+// only this full 64-hex SHA-256 token (no lossy truncation, no fabricated
+// identity) is ever displayed. The raw ID stays inside the task store for
+// selection, dispatch, and provenance lookups.
+export function sessionTaskDisplayId(id) {
+  return createHash("sha256").update(`agentic-driver.session-task-display.v1:${String(id ?? "")}`, "utf8").digest("hex");
+}
+
 /** picc-tasks task shape: the closed snapshot shape replay and migration read. */
 export function validateSessionTask(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
   if (typeof value.id !== "string" || value.id === "") return false;
   if (!SESSION_TASK_STATUSES.includes(value.status)) return false;
   if (typeof value.subject !== "string" || typeof value.description !== "string") return false;
+  if (value.priority !== undefined && !SESSION_TASK_PRIORITIES.includes(value.priority)) return false;
   for (const field of ["blocks", "blockedBy"]) {
     if (!Array.isArray(value[field]) || value[field].some((entry) => typeof entry !== "string")) return false;
   }

package/scripts/enforcement/task_board_core_pi.js

@@ -379,6 +379,75 @@ function safeJsonParse(text) {
   }
 }
 
+const CAPABILITY_REGISTRY_PATH = ".vogelkop/capabilities.json";
+
+function capabilityRegistryError(registryPath, reason) {
+  return Object.assign(new Error(`capability registry is invalid at ${registryPath}: ${reason}`), {
+    code: "capability-registry-invalid",
+  });
+}
+
+// The workspace registry is deliberately loaded at tool-call time. A missing
+// registry is an empty declaration; an unreadable or malformed present file is
+// not silently downgraded to empty. Capability-less boards are independent of
+// the registry, so they retain the writer's existing behavior even while an
+// unused registry file is malformed.
+function loadWorkspaceCapabilityNames(boardPath) {
+  const registryPath = join(dirname(boardPath), CAPABILITY_REGISTRY_PATH);
+  let text;
+  try {
+    text = readFileSync(registryPath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw capabilityRegistryError(registryPath, String(error?.message || error).slice(0, 256));
+  }
+  let entries;
+  try {
+    entries = JSON.parse(text);
+  } catch (error) {
+    throw capabilityRegistryError(registryPath, `invalid JSON: ${String(error?.message || error).slice(0, 256)}`);
+  }
+  if (!Array.isArray(entries)) {
+    throw capabilityRegistryError(registryPath, "expected a JSON array");
+  }
+  const names = [];
+  for (const [index, entry] of entries.entries()) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)
+      || typeof entry.name !== "string" || entry.name.trim() === ""
+      || (entry.description !== undefined && typeof entry.description !== "string")) {
+      throw capabilityRegistryError(registryPath, `entry ${index} must contain a non-empty string name and an optional string description`);
+    }
+    names.push(entry.name);
+  }
+  return names;
+}
+
+function boardHasCapabilities(boardPath) {
+  if (!existsSync(boardPath)) return false;
+  try {
+    const parsed = parseBoard(readFileSync(boardPath, "utf8"));
+    return parsed.cards.some((card) => Array.isArray(card.capabilities) && card.capabilities.length > 0);
+  } catch {
+    // Let the writer report the board error; do not use an unreadable board to
+    // justify ignoring a malformed capability registry.
+    return true;
+  }
+}
+
+export function workspaceRegistriesFor(boardPath, requestedCapabilities) {
+  try {
+    return { capabilities: loadWorkspaceCapabilityNames(boardPath) };
+  } catch (error) {
+    const capabilityRequested = requestedCapabilities !== undefined
+      && requestedCapabilities !== null
+      && (!Array.isArray(requestedCapabilities) || requestedCapabilities.length > 0);
+    if (error?.code === "capability-registry-invalid" && !capabilityRequested && !boardHasCapabilities(boardPath)) {
+      return { capabilities: [] };
+    }
+    throw error;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Closed validator (§1, §6 gate 2). Validate before persist; decline on
 // violation; duplicate cardId is a validation error; decorative use of the
@@ -1708,7 +1777,11 @@ const PULSE_FIELDS = Object.freeze([
 ]);
 const PULSE_ROUTE_FIELDS = Object.freeze(["model", "maxConcurrent"]);
 const PULSE_MODES = Object.freeze(["interactive", "automated"]);
-const PULSE_MODEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// Pi model IDs are provider/model-id. The provider is one bounded segment;
+// model-id may contain bounded nested segments and Pi's documented colon
+// punctuation. The separate total-length check keeps the complete ID bounded.
+const PULSE_MODEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?:\/[A-Za-z0-9][A-Za-z0-9._:-]{0,127})+$/;
+const PULSE_MODEL_MAX_LENGTH = 192;
 
 function pulseCapacityOk(value) {
   return Number.isInteger(value) && value >= 1 && value <= 32;
@@ -1719,8 +1792,9 @@ function checkPulseRouteEntry(entry, { seen }) {
     || !exactKeys(entry, PULSE_ROUTE_FIELDS)) {
     return "each routing entry must have exactly {model, maxConcurrent}";
   }
-  if (typeof entry.model !== "string" || !PULSE_MODEL_RE.test(entry.model)) {
-    return `route model "${entry.model}" is not an exact provider/model identifier`;
+  if (typeof entry.model !== "string" || entry.model.length > PULSE_MODEL_MAX_LENGTH
+    || !PULSE_MODEL_RE.test(entry.model)) {
+    return `route model "${entry.model}" is not an exact bounded provider/model identifier`;
   }
   if (seen.has(entry.model)) {
     return `model "${entry.model}" appears more than once for this role`;
@@ -2169,7 +2243,20 @@ function claimCardLocked({ boardPath, cardId, role, policy, configPath, now, rep
   if (activeClaims.length >= concurrency) {
     return { ok: false, code: "policy-concurrency-refused", reason: `the automation policy allows at most ${concurrency} concurrent claim(s); ${activeClaims.length} are active` };
   }
-  const validatedBoard = validateBoard(readFileSync(boardPath, "utf8"), {});
+  // Pulse policies also carry a role-wide ceiling. Enforce it here, under the
+  // writer lock and after expired claims are released, so concurrent claimers
+  // cannot race past the route's pre-scan capacity check.
+  const roleConcurrency = policyCheck.policy.pulse?.routing?.[role]?.maxConcurrent;
+  if (Number.isInteger(roleConcurrency)) {
+    const activeForRole = activeClaims.filter((claim) => claim.role === role).length;
+    if (activeForRole >= roleConcurrency) {
+      return { ok: false, code: "policy-role-concurrency-refused", reason: `the automation policy allows role "${role}" at most ${roleConcurrency} concurrent claim(s); ${activeForRole} are active` };
+    }
+  }
+  let registries;
+  try { registries = workspaceRegistriesFor(boardPath); }
+  catch (error) { return { ok: false, code: error?.code ?? "capability-registry-invalid", reason: error?.message ?? String(error) }; }
+  const validatedBoard = validateBoard(readFileSync(boardPath, "utf8"), registries);
   if (!validatedBoard.ok) {
     return { ok: false, code: "board-invalid", errors: validatedBoard.errors };
   }
@@ -2898,11 +2985,12 @@ export function registerKanbanBoardTools(pi, { boardPath = null, resolveBoardPat
         // reason), never raw throws — the model sees the governance reason.
         let result;
         try {
+          const registries = workspaceRegistriesFor(activeBoardPath, input?.capabilities);
           result = writeCard({
             boardPath: activeBoardPath,
             input: writerInput,
             authority: input?.authority,
-            registries: {},
+            registries,
             surface: "tasks",
             // No requireExistingBoard: the write tool bootstraps a fresh
             // board when none exists. Recreation is safe — fresh content only,
@@ -3028,9 +3116,10 @@ export function registerKanbanBoardTools(pi, { boardPath = null, resolveBoardPat
         }
         let result;
         try {
+          const registries = workspaceRegistriesFor(activeBoardPath, operation === "update" ? input?.capabilities : undefined);
           result = operation === "update"
-            ? updateCard({ boardPath: activeBoardPath, cardId: input.cardId, changes, authority: input?.authority, registries: {}, surface: "tasks" })
-            : deleteCard({ boardPath: activeBoardPath, cardId: input.cardId, authority: input?.authority, registries: {}, surface: "tasks" });
+            ? updateCard({ boardPath: activeBoardPath, cardId: input.cardId, changes, authority: input?.authority, registries, surface: "tasks" })
+            : deleteCard({ boardPath: activeBoardPath, cardId: input.cardId, authority: input?.authority, registries, surface: "tasks" });
         } catch (error) {
           const code = typeof error?.code === "string" ? error.code : "writer-error";
           const value = { ok: false, persisted: false, code, reason: String(error?.message || error).slice(0, 512), errors: [String(error?.message || error).slice(0, 512)] };