@evoclock/pi-agentic-driver 1.1.1 → 2.0.0

package/scripts/enforcement/linux_microvm_cutover_pi.js

@@ -27,7 +27,7 @@ const REMOTE_FIXTURE = join(SCRIPT_DIR, "linux_microvm_remote_fixture.sh");
 const TARGET_EXAMPLE = join(SCRIPT_DIR, "..", "..", "config", "microvm-target.v1.example.json");
 const TARGET_PACKAGE_CONFIG = join(SCRIPT_DIR, "..", "..", "config", "microvm-target.v1.json");
 // The saved target config lives in the Pi coding-agent config directory
-// (PI_CODING_AGENT_DIR when set, otherwise ~/.pi/agent), matching how Pi
+// (PI_CODING_AGENT_DIR when set, otherwise the installed agent profile), matching how Pi
 // resolves its own config.
 function resolveTargetUserConfigPath(env = process.env) {
   const agentDir = env.PI_CODING_AGENT_DIR?.trim()
@@ -105,7 +105,7 @@ function fixtureDomainForId(fixtureId) {
 // user-supplied: arch, libvirt URI, and kernel are auto-discovered from the
 // target at probe time (informational, not configured). The model cannot
 // choose or change the target. Read order: the user's own config
-// (~/.pi/pi/config/microvm-target.v1.json) first, then the package-local
+// (the installed Pi configuration directory) first, then the package-local
 // config/microvm-target.v1.json (shipped as a REPLACE-WITH template).
 const TARGET_FIELDS = new Set(["schema", "sshTarget", "local", "vcpu", "memoryMiB", "jobPayload", "_comment"]);
 // Elastic resource allocation bounds (design section 6.1). User-configured
@@ -197,7 +197,7 @@ export function targetArgumentError(value) {
 
 function targetNotConfigured() {
   return denied("blocked", reason("policy", "target-not-configured",
-    "No trusted microVM target is configured. Copy config/microvm-target.v1.example.json to ~/.pi/pi/config/microvm-target.v1.json and set either sshTarget (user@host or ip of the machine that runs the microVM) or local:true (this session runs on a Linux machine). The model cannot choose the target."));
+    "No trusted microVM target is configured. Copy config/microvm-target.v1.example.json to the installed Pi config directory as microvm-target.v1.json and set either sshTarget (user@host or ip of the machine that runs the microVM) or local:true (this session runs on a Linux machine). The model cannot choose the target."));
 }
 
 function parseFacts(stdout, fixtureId, target) {

package/scripts/enforcement/linux_microvm_remote_fixture.sh

@@ -2,8 +2,6 @@
 set -euo pipefail
 
 # --- guest containment core (taxonomy, structured log, killswitch decision) ---
-# Design: /Users/julen/pi-dev-env/evidence/GUEST_CONTAINMENT_DESIGN.md sections
-# 2 (taxonomy), 2.0 (severity tiers), 4 (log format), 5 (killswitch semantics).
 # Watchers and shims arrive in a later step; this core is callable and testable
 # through the --gc-decide / --gc-log / --gc-taxonomy-sha hooks below.
 GC_TAXONOMY_VERSION="guest-containment-taxonomy.v1"
@@ -666,8 +664,6 @@ if [ "${1:-}" = "--gc-core-embed" ]; then
   # is "bash" and there is no script file to read back.
   cat >"$1" <<'GC_CORE_EOF'
 # --- guest containment core (taxonomy, structured log, killswitch decision) ---
-# Design: /Users/julen/pi-dev-env/evidence/GUEST_CONTAINMENT_DESIGN.md sections
-# 2 (taxonomy), 2.0 (severity tiers), 4 (log format), 5 (killswitch semantics).
 # Watchers and shims arrive in a later step; this core is callable and testable
 # through the --gc-decide / --gc-log / --gc-taxonomy-sha hooks below.
 GC_TAXONOMY_VERSION="guest-containment-taxonomy.v1"
@@ -1715,8 +1711,6 @@ if ! mkdir -p "$root/gc" "$root/shims" "$root/tmp" "$root/var/cache" "$root/root
 # two can never drift. The initramfsSha256 covers the embedded result.
 if ! cat >"$root/gc/core.sh" <<'GC_CORE_EOF'
 # --- guest containment core (taxonomy, structured log, killswitch decision) ---
-# Design: /Users/julen/pi-dev-env/evidence/GUEST_CONTAINMENT_DESIGN.md sections
-# 2 (taxonomy), 2.0 (severity tiers), 4 (log format), 5 (killswitch semantics).
 # Watchers and shims arrive in a later step; this core is callable and testable
 # through the --gc-decide / --gc-log / --gc-taxonomy-sha hooks below.
 GC_TAXONOMY_VERSION="guest-containment-taxonomy.v1"

package/scripts/enforcement/loop_until_done_guide.md

@@ -0,0 +1,13 @@
+# Bounded loop guidance
+
+Only the Pi extension command may load this guide; it is not a standalone slash-command template. The validated request and step budget are: $ARGUMENTS
+
+This guide is a request to plan and check a limited journey, not permission to execute new effects. Read `skills/how/WORKFLOW_BOUNDARIES.md`. Before any work, identify the direct owner-approved session task, repository, allowed effects, an observable exit predicate, its real verification seam, and a positive integer step limit. The command validates the goal, exit check and finite step budget. The extension reads `.agentic-driver/loop-until-done.defaults.json` when registering. The default is `maxSteps: 200`, `maxDurationMs: 1800000` (30 minutes), and `wake: { "mode": "until-done" }`. To wake periodically instead, set `wake: { "mode": "interval", "periodMs": 60000 }` (this example wakes after 60 seconds). Limits and period must be positive safe integers; the period must also fit a JavaScript timer. Unknown keys, missing keys and invalid JSON prevent registration. A changed configuration cannot reopen a recorded run on reload. Neither limit can be extended during a run. If task authority or a real verification seam is missing, ask for that specific missing term and stop. Do not derive authority from the template text, a worker report, a task priority, or a model role.
+
+Read the project role map created by `/skill:setup-pstack-pi`. Resolve `development` for the developer and `independent-review` for the reviewer. If the map or either needed role is missing or invalid, name the role and stop with `pstack role <role> is not configured at .pi/pstack-model-roles.v1.json; run /skill:setup-pstack-pi`. Confirm the actual author and reviewer are distinct and both routes are installed, approved and available. Do not invent a model, switch the session's model or fall back to another provider.
+
+For coordinator **session** tasks only, use the existing `agentic_worker_dispatch` journey when its worker role, cast, model route and scope are already authorized. Never route a `TASKS.md` board card through this tool: Board Pulse and the board dispatcher own those claims. This template does not create a worker, grant autonomy, authorize a reviewer, or change the assignment. The active extension blocks dispatch after the 30-minute deadline, blocks an uncounted dispatch and consumes one step **before** each permitted attempt. For each iteration request exactly **one** exchange (`maxSteps: 1`, `mode: "turn-by-turn"`, `autonomy: "confirmed-default"`); observe the result before considering the next. One Pi session gets only one allowance, retained across turns, extension reloads and tree navigation. `/loop-until-done stop` closes it; it cannot be restarted in that session. A new session needs a new approved task request. Treat a journey's `completed` status at its step limit as a bounded tool result, **not** proof the user's exit predicate passed.
+
+After an admitted dispatch attempt settles, `until-done` schedules the next check immediately; `interval` schedules it after the configured period. A wake asks for verification first, not permission for another dispatch. Stop, session navigation and shutdown cancel pending wakes. A wake does not bypass the deadline or replenish steps.\n\nAfter each exchange, check the original predicate against the real approved entry point and independently observable evidence. If it passed, report that evidence and stop. If it did not pass, record what changed, what failed and the remaining step budget before another permitted exchange. Do not silently retry, resend, reset, discard work, run a new harness, install packages, publish, create a PR or merge. A request for independent review goes to the configured reviewer only if that handoff is separately authorized; it is not automatic completion.
+
+Stop and report `passed`, `failed`, `blocked` or `limit reached` with the exact observed result. Stop immediately on a failed or unattributed exchange, denied confirmation, unresolved effect, missing authority, unavailable reviewer, or exhausted budget. No completion claim follows from source inspection, a worker's self-report, the tool's terminal state or reaching the iteration limit. The owner alone decides canonical task completion and merges.

package/scripts/enforcement/loop_until_done_pi.js

@@ -0,0 +1,214 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { readFileSync } from "node:fs";
+
+export const LOOP_COMMAND = "loop-until-done";
+const CONFIG = new URL("../../.agentic-driver/loop-until-done.defaults.json", import.meta.url);
+
+export function loadLoopConfig(read = (url) => readFileSync(url, "utf8")) {
+  let config;
+  try { config = JSON.parse(read(CONFIG)); } catch { throw new Error("Invalid loop configuration: expected readable JSON."); }
+  if (!config || Array.isArray(config) || typeof config !== "object"
+    || Object.keys(config).sort().join(",") !== "maxDurationMs,maxSteps,wake"
+    || !Number.isSafeInteger(config.maxSteps) || config.maxSteps < 1
+    || !Number.isSafeInteger(config.maxDurationMs) || config.maxDurationMs < 1
+    || !config.wake || Array.isArray(config.wake) || typeof config.wake !== "object"
+    || !["interval", "until-done"].includes(config.wake.mode)
+    || (config.wake.mode === "interval"
+      ? Object.keys(config.wake).sort().join(",") !== "mode,periodMs"
+        || !Number.isSafeInteger(config.wake.periodMs) || config.wake.periodMs < 1 || config.wake.periodMs > 2147483647
+      : Object.keys(config.wake).join(",") !== "mode")) {
+    throw new Error("Invalid loop configuration: positive safe integer limits and a valid wake mode are required.");
+  }
+  return config;
+}
+const ENTRY_TYPE = "loop-until-done-budget.v1";
+const GUIDE = new URL("./loop_until_done_guide.md", import.meta.url);
+const WORKER_ROUTES = new Set([
+  "agentic_worker_dispatch_async",
+  "agentic_herdr_communication",
+  "agentic_herdr_spawn_worker",
+  "agentic_kanban_board_dispatch",
+  "agentic_kanban_pulse",
+]);
+const REGISTERED = new WeakSet();
+
+export function parseLoopRequest(args, config = loadLoopConfig()) {
+  const text = typeof args === "string" ? args.trim() : "";
+  const separator = text.indexOf("::");
+  const prefix = separator < 0 ? "" : text.slice(0, separator).trim();
+  const exit = separator < 0 ? "" : text.slice(separator + 2).trim();
+  const match = /^(\d+)\s+(.+)$/s.exec(prefix);
+  const steps = match ? Number(match[1]) : NaN;
+  const goal = match?.[2]?.trim() ?? "";
+  if (!Number.isSafeInteger(steps) || steps < 1 || steps > config.maxSteps || !goal || !exit
+    || goal.length > 2000 || exit.length > 1000) {
+    throw new Error(`Use /${LOOP_COMMAND} <1-${config.maxSteps} steps> <approved goal> :: <observable exit check>`);
+  }
+  return { steps, goal, exit };
+}
+
+// One admitted dispatch attempt consumes one step, even if the worker fails or
+// native confirmation is refused. Consuming before execution prevents parallel
+// tool calls and retries from overspending the session's allowance.
+export function createLoopBudget(record, now = () => Date.now(), config = loadLoopConfig()) {
+  if (typeof record !== "function" || typeof now !== "function") throw new Error("A Pi session entry writer and clock are required for a durable loop budget.");
+  let active = null;
+  let used = false;
+  return {
+    restore(entries) {
+      // Count the entire append-only session, not just the current branch: tree
+      // navigation must not restore spent steps or reopen a finished run.
+      const records = entries.filter((entry) => entry.type === "custom" && entry.customType === ENTRY_TYPE)
+        .map((entry) => entry.data);
+      const starts = records.filter((data) => data?.event === "start");
+      used = starts.length > 0;
+      const steps = starts[0]?.steps;
+      const startedAt = starts[0]?.startedAt;
+      const valid = starts.length === 1 && starts[0]?.maxSteps === config.maxSteps && starts[0]?.maxDurationMs === config.maxDurationMs
+        && JSON.stringify(starts[0]?.wake) === JSON.stringify(config.wake)
+        && Number.isSafeInteger(steps) && steps >= 1 && steps <= config.maxSteps
+        && Number.isSafeInteger(startedAt) && startedAt >= 0
+        && records.every((data) => ["start", "attempt", "expire", "stop"].includes(data?.event));
+      if (!used) active = records.length ? { steps: 0, remaining: 0 } : null;
+      else if (!valid) active = { steps: 0, remaining: 0 };
+      else if (records.some((data) => data.event === "stop")) active = null;
+      else {
+        const recordedExpiry = records.some((data) => data.event === "expire");
+        const sameRun = active?.startedAt === startedAt;
+        active = { steps, startedAt, expired: recordedExpiry || (sameRun && active.expired),
+          expiryRecorded: recordedExpiry || (sameRun && active.expiryRecorded),
+          remaining: Math.max(0, steps - records.filter((data) => data.event === "attempt").length) };
+      }
+    },
+    start(request) {
+      if (used || active) throw new Error("A loop has already started in this session; it cannot be restarted or reset.");
+      const startedAt = now();
+      if (!Number.isSafeInteger(startedAt) || startedAt < 0) throw new Error("A valid clock is required to open a bounded loop.");
+      record({ event: "start", steps: request.steps, startedAt, maxSteps: config.maxSteps, maxDurationMs: config.maxDurationMs, wake: config.wake });
+      used = true;
+      active = { ...request, startedAt, remaining: request.steps };
+    },
+    stop() {
+      if (!active) return;
+      record({ event: "stop" });
+      active = null;
+    },
+    snapshot() { return active && { ...active }; },
+    hasStarted() { return used; },
+    guard(event) {
+      if (!active) return undefined;
+      const tool = event?.toolName;
+      const input = event?.input ?? {};
+      if (tool === "agentic_worker_dispatch") {
+        if (input.action === "pulse") return undefined;
+        if (input.action !== "dispatch" || input.maxSteps !== 1
+          || input.mode !== "turn-by-turn" || input.autonomy !== "confirmed-default"
+          || !["developer", "reviewer"].includes(input.role)
+          || input.model !== undefined || input.cast !== undefined) {
+          return { block: true, reason: "Loop dispatch requires one confirmed step for an authorized developer or reviewer, without a model override." };
+        }
+        const current = now();
+        if (active.expired || !Number.isSafeInteger(current) || current < active.startedAt
+          || current - active.startedAt >= config.maxDurationMs) {
+          active.expired = true;
+          // Persist expiry before refusing so extension reload or clock rollback
+          // cannot reopen the run. A failed write throws and blocks this call;
+          // the next call retries persistence before it can return a refusal.
+          if (!active.expiryRecorded) {
+            record({ event: "expire" });
+            active.expiryRecorded = true;
+          }
+          return { block: true, reason: "Loop time limit reached; no further worker dispatch is permitted in this session run." };
+        }
+        if (active.remaining === 0) {
+          return { block: true, reason: "Loop step limit reached; no further worker dispatch is permitted in this session run." };
+        }
+        // If persistence fails, Pi blocks the tool_call. Never admit an
+        // exchange whose attempt was not recorded first.
+        record({ event: "attempt" });
+        active.remaining -= 1;
+        return undefined;
+      }
+      if (WORKER_ROUTES.has(tool)) {
+        const readOnly = (tool === "agentic_worker_dispatch_async" && ["poll", "observe", "read"].includes(input.action))
+          || (tool === "agentic_herdr_communication" && ["list", "get", "delivery", "wait", "read"].includes(input.action))
+          || (tool === "agentic_kanban_pulse" && input.action === "check");
+        if (!readOnly) return { block: true, reason: "This worker route bypasses the active loop's step counter." };
+      }
+      return undefined;
+    },
+  };
+}
+
+export function registerLoopUntilDone(pi, now = () => Date.now(), config = loadLoopConfig()) {
+  if (REGISTERED.has(pi)) return undefined;
+  if (typeof pi?.registerCommand !== "function" || typeof pi?.on !== "function" || typeof pi?.appendEntry !== "function") {
+    throw new Error("Pi session entry, command and tool-call APIs are required for /loop-until-done.");
+  }
+  // Validate injected configuration as well as the on-disk default before registration.
+  config = loadLoopConfig(() => JSON.stringify(config));
+  REGISTERED.add(pi);
+  const budget = createLoopBudget((data) => pi.appendEntry(ENTRY_TYPE, data), now, config);
+  let pendingWake = null;
+  let admitted = false;
+  let successful = false;
+  const cancelWake = () => { if (pendingWake !== null) clearTimeout(pendingWake); pendingWake = null; };
+  pi.on("tool_call", (event) => {
+    const result = budget.guard(event);
+    if (event?.toolName === "agentic_worker_dispatch" && event?.input?.action === "dispatch" && !result && budget.snapshot()) admitted = true;
+    return result;
+  });
+  pi.on("tool_result", (event) => {
+    if (admitted && event?.toolName === "agentic_worker_dispatch" && !event?.isError) successful = true;
+  });
+  pi.on("agent_settled", () => {
+    if (!admitted) return;
+    admitted = false;
+    if (!successful) return;
+    successful = false;
+    const state = budget.snapshot();
+    if (!state || state.remaining < 1 || state.expired || pendingWake !== null) return;
+    const delay = config.wake.mode === "interval" ? config.wake.periodMs : 0;
+    pendingWake = setTimeout(() => {
+      pendingWake = null;
+      const current = budget.snapshot();
+      if (!current || current.remaining < 1 || current.expired) return;
+      if (now() < current.startedAt || now() - current.startedAt >= config.maxDurationMs) return;
+      pi.sendUserMessage(`Continue the approved loop goal. Verify the exit check first; stop if passed, blocked, or failed. Remaining dispatch attempts: ${current.remaining}.`);
+    }, delay);
+  });
+  for (const event of ["session_start", "session_tree"]) {
+    pi.on(event, (_event, ctx) => { cancelWake(); admitted = false; successful = false; budget.restore(ctx.sessionManager.getEntries()); });
+  }
+  pi.on("session_shutdown", () => { cancelWake(); admitted = false; successful = false; budget.restore([]); });
+  pi.registerCommand(LOOP_COMMAND, {
+    description: `Work toward a checkable goal with up to ${config.maxSteps} dispatch attempts and a ${config.maxDurationMs} ms time ceiling`,
+    argumentHint: `<1-${config.maxSteps} steps> <approved goal> :: <observable exit check> | stop`,
+    handler: async (args, ctx) => {
+      if (args?.trim() === "stop") {
+        cancelWake();
+        budget.stop();
+        ctx?.ui?.notify?.("Loop stopped. No remaining step allowance.", "info");
+        return;
+      }
+      // A session gets one allowance, even after stop, settle or branch navigation.
+      if (budget.hasStarted()) throw new Error("A loop has already started in this session; it cannot be restarted or reset.");
+      const request = parseLoopRequest(args, config);
+      if (typeof pi.sendUserMessage !== "function") throw new Error("Pi cannot send the loop request; no budget was opened.");
+      const guide = readFileSync(GUIDE, "utf8").replace("$ARGUMENTS", () => JSON.stringify(request));
+      budget.start(request);
+      try {
+        pi.sendUserMessage(`${guide}\n\nEnforced worker-dispatch allowance: ${request.steps} attempts and a ${config.maxDurationMs} ms time ceiling. A refusal or failure consumes an attempt. To close the run, use /${LOOP_COMMAND} stop; it cannot restart in this session. No tool or model can increase this allowance.`);
+      } catch (error) {
+        cancelWake();
+        budget.stop();
+        throw error;
+      }
+    },
+  });
+  return budget;
+}
+
+export default registerLoopUntilDone;

package/scripts/enforcement/merge_policy.js

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Merge policy for the driver. One owner-set value in the driver's own
+// profile config decides whether an agent may ever run a pull-request merge:
+//
+//   human-merges-only (default)  The owner merges on GitHub. Agent merge
+//                                commands are always refused.
+//   agents-after-checks-and-review
+//                                An agent may run `gh pr merge <ref>` only when
+//                                every check on the PR head has passed and a
+//                                Standards PASS and a Spec PASS are recorded
+//                                for that exact head.
+//
+// The file lives at {PI_CODING_AGENT_DIR}/config/merge-policy.v1.json
+// (fallback to the installed agent config directory). It is never read from the working tree, so
+// a repository or a model cannot widen the policy. A missing file means the
+// default; an unreadable or unknown value fails closed to the default.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const MERGE_POLICY_SCHEMA = "pi-agentic-driver.merge-policy.v1";
+export const HUMAN_MERGES_ONLY = "human-merges-only";
+export const AGENTS_AFTER_CHECKS_AND_REVIEW = "agents-after-checks-and-review";
+export const DEFAULT_MERGE_POLICY = HUMAN_MERGES_ONLY;
+const POLICIES = new Set([HUMAN_MERGES_ONLY, AGENTS_AFTER_CHECKS_AND_REVIEW]);
+const SHA = /^[0-9a-f]{40}$/;
+
+export function profileDir(env = process.env) {
+  const dir = typeof env.PI_CODING_AGENT_DIR === "string" ? env.PI_CODING_AGENT_DIR.trim() : "";
+  return dir ? resolve(dir) : resolve(homedir(), ".pi", "agent");
+}
+
+export function mergePolicyPath(env = process.env) {
+  return join(profileDir(env), "config", "merge-policy.v1.json");
+}
+
+export function sessionIdOf(ctx) {
+  try { return String(ctx?.sessionManager?.getSessionId?.() ?? ctx?.sessionId ?? "").trim(); } catch { return ""; }
+}
+
+export function reviewRecordPath(headSha, env = process.env) {
+  if (!SHA.test(String(headSha))) throw new Error("review record needs a full commit SHA");
+  return join(profileDir(env), "merge-reviews", `${headSha}.json`);
+}
+
+// Returns { policy, source }. source is "default", "config" or "invalid".
+export function loadMergePolicy({ env = process.env, read = (p) => readFileSync(p, "utf8") } = {}) {
+  let text;
+  try { text = read(mergePolicyPath(env)); } catch (error) {
+    return { policy: DEFAULT_MERGE_POLICY, source: error?.code === "ENOENT" ? "default" : "invalid" };
+  }
+  try {
+    const data = JSON.parse(text);
+    if (data?.schema === MERGE_POLICY_SCHEMA && POLICIES.has(data.policy)) return { policy: data.policy, source: "config" };
+  } catch { /* fall through */ }
+  return { policy: DEFAULT_MERGE_POLICY, source: "invalid" };
+}
+
+const MERGE_FORMS = [
+  { pattern: /\bgh\s+pr\s+merge\b/, form: "gh" },
+  { pattern: /\/pulls\/[^\s/]+\/merge\b/, form: "api" },
+  { pattern: /\bmergePullRequest\b/, form: "graphql" },
+];
+
+function normalize(text) {
+  return String(text ?? "").split(/\s+/)
+    .map((t) => t.replace(/["'\\]/g, "").replace(/^.*\/gh$/, "gh"))
+    .join(" ");
+}
+
+// Detects a pull-request merge in a shell command. ref is the PR argument of
+// a simple `gh pr merge <ref>` call, or "" when none can be read safely.
+// Forms that skip checks or branch protection. Refused under every policy.
+const BYPASS_FORMS = [
+  { pattern: /\bgh pr merge\b[^;&|\n]*\s--admin\b/, why: "--admin skips branch protection" },
+  { pattern: /\bgh pr merge\b[^;&|\n]*\s--auto\b/, why: "--auto merges later, after the evidence was checked" },
+  { pattern: /\/branches\/[^\s]+\/protection\b/, why: "changes branch protection", write: true },
+  { pattern: /\/rulesets\b/, why: "changes repository rulesets", write: true },
+  { pattern: /\b(?:enablePullRequestAutoMerge|mergeBranch|updateBranchProtectionRule|deleteBranchProtectionRule)\b/, why: "GraphQL merge or protection change" },
+  { pattern: /\bbypass[_-]?(?:pull[_-]?request[_-]?)?(?:allowances|actors)\b/i, why: "edits protection bypass lists" },
+];
+
+export function detectBypass(command) {
+  const text = normalize(command);
+  // Reading protection or rulesets is fine; only writes are a bypass.
+  const writes = /(?:^|\s)(?:-X|--method)(?:\s+|=)?(?:PUT|POST|PATCH|DELETE)\b|(?:^|\s)(?:-f|-F|--field|--raw-field|--input)\b/i.test(text);
+  const hit = BYPASS_FORMS.find(({ pattern, write }) => pattern.test(text) && (!write || writes));
+  return hit ? { bypass: true, why: hit.why } : { bypass: false };
+}
+
+export function detectMerge(command) {
+  const raw = String(command ?? "");
+  const text = normalize(raw);
+  const bypass = detectBypass(raw);
+  if (bypass.bypass) return { merge: true, form: "bypass", ref: "", why: bypass.why };
+  const hit = MERGE_FORMS.find(({ pattern }) => pattern.test(text));
+  if (!hit) return { merge: false };
+  let ref = "";
+  const compound = /[;&|>`\n]|\$\(/.test(raw);
+  if (hit.form === "gh" && !compound) {
+    const args = text.split(/\bgh pr merge\b/)[1].trim().split(" ").filter(Boolean);
+    // A repository flag could point the merge at a different repository from
+    // the one the evidence is read from, so it is never checkable.
+    const repoFlag = args.some((a) => a === "-R" || a === "--repo" || a.startsWith("--repo=") || /^-R./.test(a));
+    const positional = args.filter((a) => !a.startsWith("-"));
+    if (!repoFlag && positional.length === 1 && /^(?:\d+|https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+)$/.test(positional[0])) ref = positional[0];
+  }
+  return { merge: true, form: hit.form, ref };
+}
+
+const PASSING = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
+
+// Pure decision. evidence: { headSha, author, mergerSession,
+//   checks: [{ state }],
+//   review: { headSha, standards, spec, standardsReviewer, specReviewer, recordedBySession } }.
+// A PASS counts only when its reviewer differs from the PR author and from the
+// merging session, and the record was not written by the merging session.
+export function evaluateMerge(policy, detection, evidence) {
+  if (detection.form === "bypass") return { allow: false, reason: `refused under every merge policy: ${detection.why}` };
+  if (policy !== AGENTS_AFTER_CHECKS_AND_REVIEW) {
+    return { allow: false, reason: "merge policy is human-merges-only: the owner merges on GitHub" };
+  }
+  if (detection.form !== "gh" || !detection.ref) {
+    return { allow: false, reason: "only a simple `gh pr merge <number|url>` can be checked against the merge policy" };
+  }
+  if (!evidence || evidence.error) return { allow: false, reason: `merge evidence unavailable: ${evidence?.error ?? "none"}` };
+  const checks = Array.isArray(evidence.checks) ? evidence.checks : [];
+  if (!checks.length) return { allow: false, reason: "no checks reported on the PR head; a required check (for example PR wording) must pass first" };
+  const failing = checks.filter((c) => !PASSING.has(String(c.state ?? "").toUpperCase()));
+  if (failing.length) return { allow: false, reason: `${failing.length} check(s) on the PR head have not passed` };
+  const review = evidence.review;
+  if (!review || review.headSha !== evidence.headSha) return { allow: false, reason: "no independent review recorded for the current PR head" };
+  if (review.standards !== "PASS" || review.spec !== "PASS") return { allow: false, reason: "the recorded review for this head is not Standards PASS and Spec PASS" };
+  const merger = String(evidence.mergerSession ?? "").trim();
+  if (!merger) return { allow: false, reason: "the merging session has no id, so reviewer independence cannot be checked" };
+  const author = String(evidence.author ?? "").trim().toLowerCase();
+  if (!author) return { allow: false, reason: "the PR author is unknown, so reviewer independence cannot be checked" };
+  if (String(review.recordedBySession ?? "") === merger) return { allow: false, reason: "the review was recorded by the merging session itself" };
+  for (const axis of ["standards", "spec"]) {
+    const who = String(review[`${axis}Reviewer`] ?? "").trim();
+    if (!who) return { allow: false, reason: `no ${axis} reviewer identity recorded` };
+    if (who === merger) return { allow: false, reason: `the ${axis} reviewer is the merging session` };
+    if (who.toLowerCase() === author) return { allow: false, reason: `the ${axis} reviewer is the PR author` };
+  }
+  return { allow: true, reason: "checks passed and Standards and Spec PASS recorded for this head" };
+}
+
+// Default evidence source: GitHub through the existing gh login, plus the
+// review record kept in the profile directory.
+export function gatherMergeEvidence(ref, { run = (cmd, args) => execFileSync(cmd, args, { encoding: "utf8", timeout: 15000 }), env = process.env, read = (p) => readFileSync(p, "utf8") } = {}) {
+  try {
+    const view = JSON.parse(run("gh", ["pr", "view", ref, "--json", "headRefOid,statusCheckRollup,author"]));
+    const headSha = String(view.headRefOid ?? "");
+    const author = String(view.author?.login ?? "");
+    const checks = (view.statusCheckRollup ?? []).map((c) => ({ state: c.conclusion || c.state || "PENDING" }));
+    let review;
+    try { review = JSON.parse(read(reviewRecordPath(headSha, env))); } catch { review = undefined; }
+    return { headSha, author, checks, review };
+  } catch (error) {
+    return { error: String(error?.message ?? error).split("\n")[0] };
+  }
+}
+
+export function reviewRecord({ headSha, standards, spec, standardsReviewer, specReviewer, recordedBySession }) {
+  if (!SHA.test(String(headSha))) return { ok: false, reason: "headSha must be a full 40-character commit SHA" };
+  const verdict = (v) => (v === "PASS" || v === "FAIL" ? v : null);
+  if (!verdict(standards) || !verdict(spec)) return { ok: false, reason: "standards and spec must each be PASS or FAIL" };
+  const id = (v) => (typeof v === "string" ? v.trim() : "");
+  if (!id(standardsReviewer) || !id(specReviewer)) return { ok: false, reason: "each verdict needs its reviewer identity or session id" };
+  if (!id(recordedBySession)) return { ok: false, reason: "the recording session has no id" };
+  if (id(standardsReviewer) === id(recordedBySession) || id(specReviewer) === id(recordedBySession)) {
+    return { ok: false, reason: "a session cannot record its own review verdict" };
+  }
+  return { ok: true, record: {
+    schema: "pi-agentic-driver.merge-review.v1", headSha, standards, spec,
+    standardsReviewer: id(standardsReviewer), specReviewer: id(specReviewer), recordedBySession: id(recordedBySession),
+  } };
+}

package/scripts/enforcement/outward_effect_pi.js

@@ -0,0 +1,156 @@
+// The only writable outward route for a driver-owned journey. A worker's
+// independent shell actions are outside this boundary.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { isNativeTuiContext } from "./native_tui_context.js";
+
+export const OUTWARD_TOOL = "agentic_journey_outward_effect";
+const SHA = /^[a-f0-9]{40}$/;
+const BRANCH = /^(?!main$|master$)[a-zA-Z0-9][a-zA-Z0-9._/-]{0,100}$/;
+const BASE = /^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,100}$/;
+const REPO = /^[a-zA-Z0-9-]+\/[a-zA-Z0-9._-]+$/;
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const run = (bin, args, cwd, input) => execFileSync(bin, args, {
+  cwd, encoding: "utf8", timeout: 15_000, maxBuffer: 16 * 1024 * 1024,
+  ...(input === undefined ? {} : { input: JSON.stringify(input) }),
+}).trim();
+const git = (args, cwd) => run("git", args, cwd);
+const remoteHead = (cwd, branch) => {
+  const line = git(["ls-remote", "origin", `refs/heads/${branch}`], cwd);
+  if (!line) return null;
+  const match = /^([a-f0-9]{40})\trefs\/heads\/(.+)$/.exec(line);
+  if (!match || match[2] !== branch) throw new Error("remote branch observation ambiguous");
+  return match[1];
+};
+const gh = (args, cwd, options, input) => run(options.ghExecutable ?? "gh", args, cwd, input);
+const pr = (repository, number, cwd, options) => JSON.parse(gh(["api", `repos/${repository}/pulls/${number}`], cwd, options));
+const prs = (repository, branch, cwd, options) => {
+  const owner = repository.split("/")[0];
+  const list = JSON.parse(gh(["api", `repos/${repository}/pulls?state=all&head=${owner}:${branch}&per_page=100`], cwd, options));
+  if (!Array.isArray(list) || list.length > 1 || list.length === 100) throw new Error("PR observation ambiguous");
+  return list[0] ?? null;
+};
+function matchingPr(item, request) {
+  return item?.state === "open" && item?.draft === true && item?.head?.ref === request.branch &&
+    item.head?.sha === request.targetHead && item.head?.repo?.full_name === request.repository &&
+    item.base?.ref === request.base && item.base?.repo?.full_name === request.repository &&
+    item.title === request.title && digest(item.body ?? "") === digest(request.body);
+}
+function validate(request) {
+  if (!request || !["push", "pr-create", "pr-update"].includes(request.action) ||
+      !/^[a-zA-Z0-9_-]{1,100}$/.test(request.journeyId ?? "") ||
+      !/^[a-zA-Z0-9_-]{1,100}$/.test(request.effectId ?? "") ||
+      !REPO.test(request.repository ?? "") || !BRANCH.test(request.branch ?? "") ||
+      !SHA.test(request.targetHead ?? "")) throw new Error("invalid outward effect identity");
+  if (request.action === "push") {
+    if (request.expectedHead !== null && !SHA.test(request.expectedHead ?? "")) throw new Error("expected remote head required (or null for a new branch)");
+  } else if (!BASE.test(request.base ?? "") || typeof request.title !== "string" ||
+      !request.title.trim() || request.title.length > 200 || typeof request.body !== "string" ||
+      Buffer.byteLength(request.body, "utf8") > 16000 ||
+      (request.action === "pr-create" && request.number !== undefined) ||
+      (request.action === "pr-update" && (!Number.isSafeInteger(request.number) || request.number < 1 ||
+        !/^[a-f0-9]{64}$/.test(request.previousBodyDigest ?? "")))) {
+    throw new Error("invalid private PR request");
+  }
+}
+async function privateRepository(request, cwd, options) {
+  if (options.repositoryProof) return options.repositoryProof(request, cwd);
+  const url = git(["remote", "get-url", "origin"], cwd);
+  const https = `https://github.com/${request.repository}.git`;
+  const ssh = `git@github.com:${request.repository}.git`;
+  if (![https, https.slice(0, -4), ssh, ssh.slice(0, -4)].includes(url)) throw new Error("origin does not match requested repository");
+  const observed = JSON.parse(gh(["repo", "view", request.repository, "--json", "nameWithOwner,isPrivate"], cwd, options));
+  if (observed.nameWithOwner !== request.repository || observed.isPrivate !== true) throw new Error("verified private repository required");
+  return true;
+}
+
+export async function executeOutwardEffect(request, context, options = {}) {
+  try {
+    validate(request);
+    const cwd = realpathSync(context.cwd);
+    git(["check-ref-format", "--branch", request.branch], cwd);
+    if (request.action !== "push") git(["check-ref-format", "--branch", request.base], cwd);
+    if (await privateRepository(request, cwd, options) !== true) throw new Error("verified private repository required");
+    if (!isNativeTuiContext(context)) throw new Error("native TUI confirmation required");
+    const store = await options.getJourneyStore(context);
+    const journeys = await store.listJourneys();
+    if (!journeys.some((entry) => entry.journeyId === request.journeyId &&
+        realpathSync(entry.repository) === cwd)) {
+      throw new Error("existing durable journey required");
+    }
+    const confirmed = await context.ui.confirm("Confirm outward journey effect",
+      `${request.action} for ${request.repository}, branch ${request.branch}, journey ${request.journeyId}?`);
+    if (confirmed !== true) throw new Error("native confirmation not granted");
+    const spec = request.action === "push"
+      ? { expectedHead: request.expectedHead, targetHead: request.targetHead }
+      : { targetHead: request.targetHead, base: request.base, titleDigest: digest(request.title),
+        bodyDigest: digest(request.body), ...(request.action === "pr-update" ? { number: request.number } : {}),
+        ...(request.previousBodyDigest ? { previousBodyDigest: request.previousBodyDigest } : {}) };
+    const record = { id: `out-${digest(`${request.journeyId}:${request.effectId}`).slice(0, 32)}`,
+      digest: digest(JSON.stringify({ action: request.action, repository: request.repository, branch: request.branch, spec })),
+      repository: cwd, createdAt: Date.now(), kind: request.action, journeyId: request.journeyId };
+    // createdAt must remain stable across reattachment; the store checks every
+    // immutable field except its timestamp, which is not part of the identity.
+    const observe = () => {
+      if (request.action === "push") {
+        const head = remoteHead(cwd, request.branch);
+        return head === request.targetHead ? { verified: true, reference: head } : { verified: false };
+      }
+      const item = request.action === "pr-create"
+        ? prs(request.repository, request.branch, cwd, options)
+        : pr(request.repository, request.number, cwd, options);
+      return matchingPr(item, request) && Number.isSafeInteger(item.number)
+        ? { verified: true, reference: String(item.number) } : { verified: false };
+    };
+    const apply = () => {
+      if (request.action === "push") {
+        const local = git(["rev-parse", "HEAD"], cwd);
+        if (local !== request.targetHead || git(["branch", "--show-current"], cwd) !== request.branch ||
+            remoteHead(cwd, request.branch) !== request.expectedHead) throw new Error("branch or remote head drift");
+        git(["push", "origin", `${request.targetHead}:refs/heads/${request.branch}`], cwd);
+        return;
+      }
+      if (remoteHead(cwd, request.branch) !== request.targetHead) throw new Error("PR head is not on the remote");
+      const existing = request.action === "pr-create"
+        ? prs(request.repository, request.branch, cwd, options)
+        : pr(request.repository, request.number, cwd, options);
+      if (request.action === "pr-create") {
+        if (existing) throw new Error("PR already exists; observe only");
+        gh(["api", "--method", "POST", `repos/${request.repository}/pulls`, "--input", "-"], cwd, options,
+          { title: request.title, body: request.body, head: request.branch, base: request.base, draft: true });
+      } else {
+        if (existing?.state !== "open" || existing?.draft !== true || existing?.head?.ref !== request.branch ||
+            existing?.head?.sha !== request.targetHead || existing?.head?.repo?.full_name !== request.repository ||
+            existing?.base?.ref !== request.base || digest(existing?.body ?? "") !== request.previousBodyDigest) {
+          throw new Error("PR baseline changed; refusing update");
+        }
+        gh(["api", "--method", "PATCH", `repos/${request.repository}/pulls/${request.number}`, "--input", "-"],
+          cwd, options, { title: request.title, body: request.body, base: request.base });
+      }
+    };
+    const result = await store.runOutwardEffect(record, { apply, observe, boundary: options.boundary });
+    return { schema: "agentic-driver.outward-effect.v1", ok: result.state === "verified", status: result.state,
+      reference: result.report ?? null, nonAuthorizing: true };
+  } catch (error) {
+    return { schema: "agentic-driver.outward-effect.v1", ok: false, status: "blocked",
+      reason: String(error?.message ?? error).slice(0, 256), nonAuthorizing: true };
+  }
+}
+
+export function registerOutwardEffectInterface(pi, options = {}) {
+  pi.registerTool({ name: OUTWARD_TOOL,
+    description: "Confirm one durable Git push or draft private PR create/update for an existing journey; uncertain effects are never replayed.",
+    parameters: {
+      type: "object", additionalProperties: false,
+      required: ["action", "journeyId", "effectId", "repository", "branch", "targetHead"],
+      properties: Object.fromEntries(["action", "journeyId", "effectId", "repository", "branch", "targetHead",
+        "expectedHead", "base", "title", "body", "number", "previousBodyDigest"].map((key) =>
+        [key, { type: key === "number" ? "integer" : key === "expectedHead" ? ["string", "null"] : "string" }])),
+    },
+    async execute(_id, params, _signal, _update, context) {
+      const result = await executeOutwardEffect(params, context, options);
+      return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+    },
+  });
+}