@evoclock/pi-agentic-driver 0.6.0 → 0.7.0

package/README.md

@@ -1,4 +1,4 @@
-# pi-agentic-driver v0.6.0
+# pi-agentic-driver v0.7.0
 
 <p align="center">
   <img src="assets/Yamagane-origami.png" alt="pi-agentic-driver, Yamagane origami mark" width="140"/>
@@ -7,7 +7,7 @@
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL%20v3-blue?style=flat" alt="License: AGPL v3"/></a>
   <a href="https://www.npmjs.com/package/@evoclock/pi-agentic-driver"><img src="https://img.shields.io/npm/v/@evoclock/pi-agentic-driver?style=flat" alt="npm version"/></a>
-  <img src="https://img.shields.io/badge/version-0.6.0-blue?style=flat" alt="Version 0.6.0"/>
+  <img src="https://img.shields.io/badge/version-0.7.0-blue?style=flat" alt="Version 0.7.0"/>
   <img src="https://img.shields.io/badge/status-active%20development%20%26%20testing-orange?style=flat" alt="Status"/>
   <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=flat&logo=javascript&logoColor=black" alt="JavaScript"/>
   <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript"/>
@@ -345,18 +345,72 @@ Small models on your own desk are worth taking seriously as reviewers.
 
 </details>
 
+<details>
+<summary><strong>autonomous journeys, overnight operation</strong> <em>(released, 0.7.0)</em></summary>
+
+Dispatch a worker journey that runs end to end while you are away. The
+journey proceeds through steps without pausing for confirmation, replaces
+agents that get stuck, and records everything in one report you read when
+you come back.
+
+Autonomy is entered by your words alone. Say "run these overnight end to
+end" or "don't wait for me" and the journey runs in autonomous mode. Say
+"do these two things" and it runs in the normal mode, pausing for you
+between steps. The mode is recorded in the report either way.
+
+The journeys run work you dispatch in natural language: work that is real
+and authorized but not yet formally placed on a kanban board. A task board
+integration is planned, and once it ships, planned journeys will execute
+board-managed work with the same containment and safety guarantees.
+
+### The cast
+
+You name the agents for the journey, and that list becomes the standing
+permission. If the implementer gets stuck at 3am, a replacement spawns
+automatically: same role, same model, both in the list you authorized.
+If a task needs an agent you didn't name, the attempt is recorded and that
+thread stops. Nothing outside your list can appear while you sleep.
+
+The cast is frozen at dispatch and never grows. It can only shrink in
+practice (roles finishing their work), never widen.
+
+### When agents get stuck
+
+A stuck agent doesn't block the journey. The journey detects the stall,
+spawns a replacement from the cast, and the replacement starts with a
+mandatory gap analysis: read the task spec, inspect the repository, consult
+the journey history, and state what remains before resuming. The replacement
+must show that the remaining work is smaller than what its predecessor left.
+If it can't, the journey stops that role and continues with the others.
+
+### The morning report
+
+One block tells you what happened: the terminal state, each step's outcome,
+every replacement with its gap analysis and progress judgment, and any
+denials. Every claim is tied to a receipt or a report excerpt. No prose
+narrative to reconstruct; you read the report and know exactly where things
+stand.
+
+</details>
+
+<details>
+<summary><strong>attended-authority guard</strong> <em>(released, 0.7.0)</em></summary>
+
+The safety net between an agent and your shell. When a model tries to
+delete, overwrite, or push, the guard stops it and asks you. Safe commands
+pass through untouched. If you deny, you get a clear reason and the session
+continues, and the agent does not retry behind your back. In headless runs
+where no human can confirm, destructive commands are refused rather than
+silently allowed.
+
+</details>
+
 **Under development in this theme:**
 
 - **native macOS container proof.** The native Apple Container runtime has
   passed a fixed local isolation qualification: read-only repository mount,
   no network, automatic removal. The native Pi adapter is not yet part of the
   released package.
-- **attended-authority guard.** The safety net between an agent and your
-  shell. When a model tries to delete, overwrite, or push, the guard stops it
-  and asks you. Safe commands pass through untouched. If you deny, you get a
-  clear reason and the session continues, and the agent does not retry behind
-  your back. In headless runs where no human can confirm, destructive
-  commands are refused rather than silently allowed.
 
 ## Session continuity
 
@@ -436,7 +490,7 @@ pi install npm:@evoclock/pi-agentic-driver
 Or from Git at a pinned tag:
 
 ```sh
-pi install git:github.com/evoclock/pi-agentic-driver@v0.6.0
+pi install git:github.com/evoclock/pi-agentic-driver@v0.7.0
 ```
 
 Released extensions load standalone; neither requires the other.
@@ -450,7 +504,7 @@ extensions you want with the object form in your Pi settings:
 {
   "packages": [
     {
-      "source": "npm:@evoclock/pi-agentic-driver@0.6.0",
+      "source": "npm:@evoclock/pi-agentic-driver@0.7.0",
       "extensions": [
         "extensions/aidr.ts",
         "extensions/code-phage.js"

package/extensions/attended-authority-guard.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
   "license": "AGPL-3.0-or-later",
@@ -34,6 +34,8 @@
     "governance"
   ],
   "files": [
+    "extensions/attended-authority-guard.ts",
+    "scripts/enforcement/attended_authority_guard.js",
     "extensions/code-phage.js",
     "extensions/herdr-communication.ts",
     "extensions/herdr-dispatch.ts",

package/scripts/enforcement/attended_authority_guard.js

@@ -0,0 +1,223 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Attended-authority destructive-command guard for Pi.
+//
+// Ported observable behavior (private reference: scripts/enforcement/
+// pi_attended_authority.js + cc_destructive_command_guard_hook.py):
+// - Intercept tool calls before execution via the `tool_call` event.
+// - Destructive shell/Git operations require native confirmation.
+// - Safe reads/builds/tests pass through untouched.
+// - An explicit denial returns a clear reason and the session continues;
+//   no hidden retry and no automatic re-ask.
+// - Headless / no-confirmation contexts refuse destructive operations
+//   fail-closed.
+// - No bypasses, no model-supplied authority, no silent escalation. The
+//   model cannot mark a call safe; classification is structural only.
+
+import { isNativeTuiContext } from "./native_tui_context.js";
+
+export const GUARD_SCHEMA = "pi-agentic-driver.attended-authority.v1";
+
+// Tool names that can mutate the workspace.
+const MUTATING_TOOLS = new Set(["bash", "write", "edit"]);
+
+// Read-only / build / test commands that always pass through.
+const SAFE_COMMAND_PREFIXES = [
+  "cat", "ls", "head", "tail", "grep", "rg", "find", "sed -n", "awk",
+  "wc", "file", "stat", "which", "echo", "pwd", "date", "env",
+  "node --check", "node --test", "npm test", "npm run",
+  "python3 -m pytest", "pytest", "make", "cmake",
+  "git status", "git log", "git diff", "git show", "git branch",
+  "git remote", "git rev-parse", "git blame", "git describe",
+  "git config --get", "git ls-files",
+];
+
+// Arbitrary-code interpreter execution: any code payload can perform a
+// destructive operation, so these forms are classified fail-closed.
+const DESTRUCTIVE_SHELL_PATTERNS = [
+  { pattern: /\brm\b[^|;&]*\s(-[a-z]*[rf][a-z]*\s|--recursive|--force)/, kind: "recursive or forced file deletion" },
+  { pattern: /\bsudo\s+rm\b/, kind: "privileged file deletion" },
+  { pattern: /\brmdir\b|\bunlink\b/, kind: "file or directory deletion" },
+  { pattern: /\bmkfs\b|\bshred\b|\bdd\b\s+if=/, kind: "irreversible disk or file operation" },
+  { pattern: /\btruncate\s+-s\s*0\b/, kind: "file truncation" },
+  { pattern: /\bkill\b\s+-9\b|\bpkill\b/, kind: "forced process termination" },
+  { pattern: /\bchmod\s+-R\b|\bchown\s+-R\b/, kind: "recursive permission change" },
+  { pattern: /\bnode\s+(-e|--eval)\b/, kind: "arbitrary JavaScript execution via node -e" },
+  { pattern: /\bpython3?\s+-c\b/, kind: "arbitrary Python execution via python -c" },
+  { pattern: /\bnpx\b/, kind: "arbitrary package execution via npx" },
+];
+
+// Scope note: plain `rm file` (no -r/-f) is intentionally NOT classified
+// destructive here; the guard targets recursive/forced deletion and
+// irreversible operations. Any `git push`, forced or not, is treated
+// conservatively as destructive because pushes publish history to remotes.
+
+// Destructive Git operations.
+const DESTRUCTIVE_GIT_PATTERNS = [
+  { pattern: /\bgit\s+push\b[^|;&]*(--force|-f\b)/, kind: "forced Git push" },
+  { pattern: /\bgit\s+push\b/, kind: "Git push" },
+  { pattern: /\bgit\s+reset\s+--hard\b/, kind: "hard Git reset" },
+  { pattern: /\bgit\s+reset\b/, kind: "Git reset" },
+  { pattern: /\bgit\s+clean\b/, kind: "Git clean" },
+  { pattern: /\bgit\s+checkout\s+--\s/, kind: "Git working-tree discard" },
+  { pattern: /\bgit\s+restore\b/, kind: "Git working-tree discard" },
+  { pattern: /\bgit\s+stash\s+(drop|clear|pop)\b/, kind: "Git stash mutation" },
+  { pattern: /\bgit\s+stash\b/, kind: "Git stash mutation" },
+  { pattern: /\bgit\s+rebase\b/, kind: "Git history rewrite" },
+  { pattern: /\bgit\s+filter-(branch|repo)\b/, kind: "Git history rewrite" },
+  { pattern: /\bgit\s+commit\b[^|;&]*--amend\b/, kind: "Git history rewrite" },
+  { pattern: /\bgit\s+branch\s+(-D|-d)\b/, kind: "protected branch deletion" },
+  { pattern: /\bgit\s+tag\s+-d\b/, kind: "protected tag deletion" },
+  { pattern: /\bgit\s+cherry-pick\b|\bgit\s+revert\b/, kind: "Git history mutation" },
+];
+
+// Paths whose deletion or overwrite is always treated as destructive.
+const PROTECTED_PATHS = [
+  ".env", ".ssh", ".gnupg", "node_modules", ".git",
+  "package-lock.json", "pnpm-lock.yaml", "Cargo.lock", "poetry.lock",
+];
+
+// Quote-aware tokenization: normalizes shell quoting so `rm '-rf'`,
+// `git "push"`, and split/embedded quoting such as `r'm' '-rf'` still
+// expose their destructive tokens to the patterns. Escapes are also
+// stripped (`\rm` -> `rm`) so an escaped destructive token cannot dodge
+// classification. Normalization is only used for the destructive
+// patterns, never to widen the safe-prefix list.
+function unquoteTokens(text) {
+  return String(text ?? "")
+    .split(/[\s\n]+/)
+    .map((token) => token
+      .replace(/^"/, "").replace(/"$/, "")
+      .replace(/^'/, "").replace(/'$/, "")
+      .replace(/["']/g, "")
+      .replace(/\\(.)/g, "$1"))
+    .join(" ");
+}
+
+export function classifyBashCommand(command) {
+  const text = String(command ?? "").trim();
+  if (!text) return { destructive: false };
+  // A safe prefix wins only when the whole command is that single simple
+  // command (no chaining, redirection, or command substitution), so a
+  // destructive payload cannot hide behind a safe-looking prefix.
+  const compound = /[;&|>`]|\$\(|\n/.test(text);
+  const redirection = /(^|\s)(>{1,2}|<)/.test(text);
+  // Structural destructive verdicts win over safe-looking prefixes, so a
+  // destructive form such as `git branch -D` cannot hide behind a safe
+  // prefix such as `git branch`.
+  for (const { pattern, kind } of DESTRUCTIVE_SHELL_PATTERNS) {
+    if (pattern.test(text) || pattern.test(unquoteTokens(text))) return { destructive: true, kind };
+  }
+  for (const { pattern, kind } of DESTRUCTIVE_GIT_PATTERNS) {
+    if (pattern.test(text) || pattern.test(unquoteTokens(text))) return { destructive: true, kind };
+  }
+  if (!compound && !redirection) {
+    for (const prefix of SAFE_COMMAND_PREFIXES) {
+      if (text === prefix || text.startsWith(`${prefix} `) || text.startsWith(`${prefix}\t`)) {
+        return { destructive: false };
+      }
+    }
+  }
+  // Output redirection overwrites an existing file in place.
+  const redirect = text.match(/(?:^|\s)>{1,2}\s*([^\s;&|]+)\s*$/);
+  if (redirect) {
+    const target = redirect[1].replace(/^["']|["']$/g, "");
+    return {
+      destructive: true,
+      kind: `file overwrite via redirection to ${target}`,
+    };
+  }
+  // Unrecognized non-safe commands are not destructive by default; the
+  // guard only intercepts structurally destructive operations.
+  return { destructive: false };
+}
+
+function touchesProtectedPath(path) {
+  const normalized = String(path ?? "").replace(/\\/g, "/");
+  return PROTECTED_PATHS.some((entry) =>
+    normalized === entry
+    || normalized.endsWith(`/${entry}`)
+    || normalized.includes(`/${entry}/`)
+    || normalized.startsWith(`./${entry}`),
+  );
+}
+
+// Existing-file overwrite detection is injected so tests stay filesystem-free.
+export function classifyWriteCall(toolName, input, existsSync) {
+  if (toolName !== "write" && toolName !== "edit") {
+    return { destructive: false };
+  }
+  const path = input?.path ?? input?.file_path ?? "";
+  if (touchesProtectedPath(path)) {
+    return { destructive: true, kind: `protected path write to ${path}` };
+  }
+  if (toolName === "write" && typeof existsSync === "function" && path && existsSync(path)) {
+    return { destructive: true, kind: `overwrite of existing file ${path}` };
+  }
+  return { destructive: false };
+}
+
+export function confirmationBody(toolName, input, kind) {
+  return [
+    `Attended-authority guard: ${kind}.`,
+    `Tool: ${toolName}`,
+    toolName === "bash" ? `Command: ${input?.command}` : `Path: ${input?.path ?? input?.file_path ?? ""}`,
+    "",
+    "Allow this destructive operation?",
+  ].join("\n");
+}
+
+export function denialReason(toolName, kind, context) {
+  if (!isNativeTuiContext(context)) {
+    return `${GUARD_SCHEMA}: destructive ${toolName} operation (${kind}) refused fail-closed: no native confirmation surface in this headless context`;
+  }
+  return `${GUARD_SCHEMA}: destructive ${toolName} operation (${kind}) denied by user; the session continues and this call is not retried`;
+}
+
+/**
+ * Core guard for one tool call. Returns undefined to allow the call, or
+ * `{ block: true, reason }` to refuse it. Confirmation is native-only:
+ * `ctx.ui.confirm` in an interactive TUI. Headless contexts never confirm.
+ * Model-supplied fields on the event can never grant authority.
+ */
+export async function guardToolCall(event, ctx, options = {}) {
+  const toolName = String(event?.toolName ?? "").toLowerCase();
+  if (!MUTATING_TOOLS.has(toolName)) return undefined;
+  const input = event?.input && typeof event.input === "object" ? event.input : {};
+
+  const bash = toolName === "bash"
+    ? classifyBashCommand(input.command)
+    : { destructive: false };
+  const write = toolName === "bash"
+    ? { destructive: false }
+    : classifyWriteCall(toolName, input, options.existsSync);
+  const verdict = bash.destructive ? bash : write;
+  if (!verdict.destructive) return undefined;
+
+  const context = options.context ?? ctx;
+  if (!isNativeTuiContext(context)) {
+    return { block: true, reason: denialReason(toolName, verdict.kind, context) };
+  }
+  const confirmed = await context.ui.confirm(
+    "Destructive operation",
+    confirmationBody(toolName, input, verdict.kind),
+  );
+  if (confirmed === true) return undefined;
+  return { block: true, reason: denialReason(toolName, verdict.kind, context) };
+}
+
+/**
+ * Register the guard on a Pi host instance. Duplicate registration on the
+ * same instance is ignored.
+ */
+const REGISTERED = new WeakSet();
+
+export function registerAttendedAuthorityGuard(pi, options = {}) {
+  if (!pi || REGISTERED.has(pi)) return undefined;
+  REGISTERED.add(pi);
+  pi.on?.("tool_call", (event, ctx) => guardToolCall(event, ctx, options));
+  return { registered: true, schema: GUARD_SCHEMA };
+}
+
+export default guardToolCall;

package/scripts/enforcement/herdr_async_dispatch_pi.js

@@ -20,7 +20,9 @@ import { isNativeTuiContext } from "./native_tui_context.js";
 export const WORKER_DISPATCH_TOOL = "agentic_worker_dispatch";
 export const WORKER_DISPATCH_SCHEMA = "agentic-driver.worker-dispatch.v1";
 export const WORKER_DISPATCH_MODES = Object.freeze(["continuous", "turn-by-turn"]);
+export const WORKER_DISPATCH_AUTONOMY_MODES = Object.freeze(["confirmed-default", "autonomous"]);
 export const DEFAULT_MODE = "continuous";
+export const DEFAULT_AUTONOMY = "confirmed-default";
 const DEFAULT_JOURNEY_STEPS = 50;
 const MAX_JOURNEY_STEPS = 200;
 const MAX_REPORT_BYTES = 32 * 1024;
@@ -39,9 +41,22 @@ export const WORKER_DISPATCH_PARAMETERS = Object.freeze({
     action: { type: "string", enum: ["dispatch", "pulse"] },
     role: { type: "string", pattern: "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", maxLength: 64 },
     mode: { type: "string", enum: WORKER_DISPATCH_MODES },
+    autonomy: { type: "string", enum: WORKER_DISPATCH_AUTONOMY_MODES },
     maxSteps: { type: "integer", minimum: 1, maximum: MAX_JOURNEY_STEPS },
     stepPrompt: { type: "string", minLength: 1, maxLength: 8192 },
     model: { type: "string", pattern: "^[a-z0-9][a-z0-9._-]{0,63}(?:\\/[a-z0-9][a-z0-9._-]{0,127})*$", maxLength: 192 },
+    cast: {
+      type: "object",
+      properties: {
+        roles: { type: "array", items: { type: "string", pattern: "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, maxItems: 8 },
+        models: {
+          type: "object",
+          patternProperties: { "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$": { type: "string", pattern: "^[a-z0-9][a-z0-9._-]{0,63}(?:\\/[a-z0-9][a-z0-9._-]{0,127})*$", maxLength: 192 } },
+          additionalProperties: false,
+        },
+      },
+      additionalProperties: false,
+    },
   },
   required: ["action", "role"],
   allOf: [
@@ -83,6 +98,53 @@ function failure(action, error) {
   };
 }
 
+function frozenCastEntries(source) {
+  if (Array.isArray(source)) {
+    return source.map((entry) => ({
+      role: entry?.role,
+      models: Array.isArray(entry?.models) ? entry.models : [entry?.model],
+    }));
+  }
+  if (source && typeof source === "object" && Array.isArray(source.roles)) {
+    return source.roles.map((role) => ({
+      role,
+      models: Array.isArray(source.models?.[role])
+        ? source.models[role]
+        : [source.models?.[role]],
+    }));
+  }
+  return [];
+}
+
+function materializeFrozenCast(params, options) {
+  const source = params.cast ?? options.cast;
+  const entries = source === undefined
+    ? [{ role: params.role, models: [params.model ?? options.model] }]
+    : frozenCastEntries(source);
+  const roles = [];
+  const models = {};
+  for (const entry of entries) {
+    if (typeof entry.role !== "string" || roles.includes(entry.role)) continue;
+    roles.push(entry.role);
+    models[entry.role] = Object.freeze(
+      entry.models.filter((model, index, values) => typeof model === "string" && values.indexOf(model) === index),
+    );
+  }
+  return Object.freeze({ roles: Object.freeze(roles), models: Object.freeze(models) });
+}
+
+function checkFrozenCast(cast, role, model) {
+  const roleAuthorized = Array.isArray(cast?.roles) && cast.roles.includes(role);
+  const modelSet = roleAuthorized ? cast.models?.[role] : undefined;
+  const modelAuthorized = roleAuthorized && Array.isArray(modelSet) && modelSet.some((candidate) => candidate === model);
+  return Object.freeze({
+    authorized: modelAuthorized,
+    role,
+    model,
+    reason: modelAuthorized ? "in-cast" : "outside-cast",
+  });
+}
+
 // Worker pulse: liveness, current state, and dispatch eligibility, observed
 // through the existing non-authorizing get seam. Grants no authority.
 export async function workerPulse(role, context, options = {}, signal) {
@@ -146,6 +208,8 @@ function journeyReceipt(journey) {
   const body = [
     "[WORKER_JOURNEY_REPORT_BEGIN]",
     `mode: ${journey.mode}`,
+    `autonomy: ${journey.autonomy}`,
+    ...(journey.cast ? [`cast: ${JSON.stringify(journey.cast)}`] : []),
     `role: ${journey.role}`,
     `steps: ${journey.steps.length}`,
     `status: ${journey.status}`,
@@ -167,6 +231,7 @@ function journeyReceipt(journey) {
 // dispatch purposes and ends the journey explicitly as worker-unresponsive.
 export async function runWorkerJourney(params, context, options = {}, signal) {
   const mode = params.mode ?? DEFAULT_MODE;
+  const autonomy = params.autonomy ?? DEFAULT_AUTONOMY;
   const maxSteps = params.maxSteps ?? DEFAULT_JOURNEY_STEPS;
   if (!Number.isInteger(maxSteps) || maxSteps < 1 || maxSteps > MAX_JOURNEY_STEPS) {
     return failure("dispatch", dispatchError("max-steps-invalid",
@@ -176,15 +241,18 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
   const stepPrompt = params.stepPrompt;
   const taskStore = options.taskStore;
   const spawnReplacement = typeof options.spawnReplacement === "function" ? options.spawnReplacement : null;
-  const journey = { mode, role, steps: [], status: "failed", code: null, handoff: null };
+  const journey = { mode, autonomy, role, steps: [], status: "failed", code: null, handoff: null };
   const dispatched = new Set();
   const communicationOptions = options.communication ?? options;
-
+  const replacementRole = options.replacementRole ?? role;
+  const replacementModel = options.replacementModel ?? options.model ?? params.model;
   const finish = (status) => ({
     schema: WORKER_DISPATCH_SCHEMA,
     ok: status === "completed" || status === "exhausted" || status === "waiting-approval",
     action: "dispatch",
     mode,
+    autonomy,
+    ...(journey.cast ? { cast: journey.cast } : {}),
     role,
     status,
     steps: journey.steps,
@@ -209,28 +277,51 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
       journey.handoff = { attempted: false, reason: "replacement spawn is not available in this context" };
       return finish("worker-unresponsive");
     }
-    if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
-      journey.handoff = { attempted: false, reason: "native TUI confirmation unavailable for replacement spawn" };
-      return finish("worker-unresponsive");
-    }
-    let confirmed;
-    try {
-      confirmed = await context.ui.confirm("Spin up replacement worker", [
-        `Agent session for role ${role} became unresponsive (${reason}).`,
-        "Spin up one replacement worker through the guarded herdr-lifecycle spawn boundary?",
-        "The replacement resumes the same pending task sequence; existing task cards are reused, never duplicated.",
-      ].join("\n"));
-    } catch (error) {
-      journey.handoff = { attempted: false, reason: `confirmation failed: ${error.message}` };
+    const replacementRole = options.replacementRole ?? role;
+    const replacementModel = options.replacementModel ?? options.model ?? params.model;
+    if (autonomy === "autonomous" && castCheck.authorized !== true) {
+      journey.handoff = {
+        attempted: true,
+        ok: false,
+        spawned: false,
+        role: replacementRole,
+        model: replacementModel,
+        reason: "outside-cast",
+        castCheck,
+      };
       return finish("worker-unresponsive");
     }
-    if (confirmed !== true) {
-      journey.handoff = { attempted: false, reason: "native confirmation was not granted for the replacement spawn" };
-      return finish("worker-unresponsive");
+    if (autonomy !== "autonomous") {
+      if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
+        journey.handoff = { attempted: false, reason: "native TUI confirmation unavailable for replacement spawn" };
+        return finish("worker-unresponsive");
+      }
+      let confirmed;
+      try {
+        confirmed = await context.ui.confirm("Spin up replacement worker", [
+          `Agent session for role ${replacementRole} became unresponsive (${reason}).`,
+          "Spin up one replacement worker through the guarded herdr-lifecycle spawn boundary?",
+          "The replacement resumes the same pending task sequence; existing task cards are reused, never duplicated.",
+        ].join("\n"));
+      } catch (error) {
+        journey.handoff = { attempted: false, reason: `confirmation failed: ${error.message}` };
+        return finish("worker-unresponsive");
+      }
+      if (confirmed !== true) {
+        journey.handoff = { attempted: false, reason: "native confirmation was not granted for the replacement spawn" };
+        return finish("worker-unresponsive");
+      }
     }
     let spawned;
     try {
-      spawned = await spawnReplacement({ role, repository: options.repository, model: options.model, context, signal });
+      spawned = await spawnReplacement({
+        role: replacementRole,
+        repository: options.repository,
+        model: replacementModel,
+        context,
+        signal,
+        castCheck,
+      });
     } catch (error) {
       journey.handoff = { attempted: true, ok: false, error: String(error?.message || error).slice(0, 256) };
       return finish("worker-unresponsive");
@@ -238,9 +329,10 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
     journey.handoff = {
       attempted: true,
       ok: spawned?.ok === true,
-      role: spawned?.role ?? role,
+      role: spawned?.role ?? replacementRole,
       repository: spawned?.repository,
       modelArgv: spawned?.modelArgv,
+      castCheck,
       nonAuthorizing: true,
     };
     return finish("worker-unresponsive");
@@ -250,6 +342,34 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
   if (mode !== "continuous" && mode !== "turn-by-turn") {
     return failure("dispatch", dispatchError("mode-invalid", "dispatch mode must be continuous or turn-by-turn", "denied"));
   }
+  if (!WORKER_DISPATCH_AUTONOMY_MODES.includes(autonomy)) {
+    return failure("dispatch", dispatchError("autonomy-invalid", "autonomy must be confirmed-default or autonomous", "denied"));
+  }
+  if (params.cast) {
+    const castRoles = Array.isArray(params.cast)
+      ? params.cast.map((entry) => entry?.role).filter((role) => typeof role === "string")
+      : Array.isArray(params.cast.roles) ? params.cast.roles : [];
+    if (!castRoles.length) {
+      return failure("dispatch", dispatchError("cast-invalid", "the cast must include at least one role", "denied"));
+    }
+    for (const castRole of castRoles) {
+      if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(castRole) || castRole.length > 64) {
+        return failure("dispatch", dispatchError("cast-invalid", `invalid cast role name: ${castRole}`, "denied"));
+      }
+    }
+    const castModels = Array.isArray(params.cast)
+      ? Object.fromEntries(params.cast.map((entry) => [entry?.role, entry?.model]).filter(([role]) => typeof role === "string"))
+      : params.cast.models ?? {};
+    for (const [castRoleName, castModel] of Object.entries(castModels)) {
+      if (typeof castModel === "string" && !/^[a-z0-9][a-z0-9._-]{0,63}(?:\/[a-z0-9][a-z0-9._-]{0,127})*$/.test(castModel)) {
+        return failure("dispatch", dispatchError("cast-invalid", `invalid cast model for ${castRoleName}: ${castModel}`, "denied"));
+      }
+    }
+  }
+  if (autonomy === "autonomous") journey.cast = materializeFrozenCast(params, options);
+  const castCheck = autonomy === "autonomous"
+    ? checkFrozenCast(journey.cast, replacementRole, replacementModel)
+    : null;
   if (!taskStore || typeof taskStore.list !== "function") {
     return failure("dispatch", dispatchError("task-store-invalid", "a read-only task store is required", "denied"));
   }
@@ -304,29 +424,32 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
       return finish("waiting-approval");
     }
 
-    // Consequential dispatch requires native confirmation, once per step.
-    if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
-      journey.status = "failed";
-      journey.steps.push({ step: stepIndex, taskId: task.id, status: "failed", error: "native TUI confirmation unavailable" });
-      return finish("failed");
-    }
-    let confirmed;
-    try {
-      confirmed = await context.ui.confirm("Dispatch task to worker", [
-        `Dispatch one bounded step to role ${role}?`,
-        `Task: ${task.id}${task.subject ? ` — ${task.subject}` : ""}`,
-        `Mode: ${mode} (step ${stepIndex} of at most ${maxSteps})`,
-        "One prompt exchange, no retries; the worker returns one marked report.",
-      ].join("\n"));
-    } catch (error) {
-      journey.status = "failed";
-      journey.steps.push({ step: stepIndex, taskId: task.id, status: "failed", error: `confirmation failed: ${error.message}` });
-      return finish("failed");
-    }
-    if (confirmed !== true) {
-      journey.status = "cancelled";
-      journey.steps.push({ step: stepIndex, taskId: task.id, status: "cancelled", error: "native confirmation was not granted" });
-      return finish("cancelled");
+    // Consequential dispatch requires native confirmation, once per step,
+    // unless the initial dispatch explicitly authorized autonomous progression.
+    if (autonomy !== "autonomous") {
+      if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
+        journey.status = "failed";
+        journey.steps.push({ step: stepIndex, taskId: task.id, status: "failed", error: "native TUI confirmation unavailable" });
+        return finish("failed");
+      }
+      let confirmed;
+      try {
+        confirmed = await context.ui.confirm("Dispatch task to worker", [
+          `Dispatch one bounded step to role ${role}?`,
+          `Task: ${task.id}${task.subject ? ` — ${task.subject}` : ""}`,
+          `Mode: ${mode} (step ${stepIndex} of at most ${maxSteps})`,
+          "One prompt exchange, no retries; the worker returns one marked report.",
+        ].join("\n"));
+      } catch (error) {
+        journey.status = "failed";
+        journey.steps.push({ step: stepIndex, taskId: task.id, status: "failed", error: `confirmation failed: ${error.message}` });
+        return finish("failed");
+      }
+      if (confirmed !== true) {
+        journey.status = "cancelled";
+        journey.steps.push({ step: stepIndex, taskId: task.id, status: "cancelled", error: "native confirmation was not granted" });
+        return finish("cancelled");
+      }
     }
 
     // One prompt exchange. Any failure is terminal for the journey; there is
@@ -338,8 +461,50 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
       signal,
     );
     if (exchange.ok !== true) {
-      const unresponsive = exchange.code === "prompt_stalled" || exchange.code === "process_timeout";
+      const unresponsive = exchange.code === "prompt_stalled" || exchange.code === "prompt_delivery_unknown" || exchange.code === "process_timeout";
       if (unresponsive) {
+        if (autonomy === "autonomous" && castCheck?.authorized) {
+          // Autonomous replacement spawn: in-cast roles are replaced
+          // automatically through the guarded seam. The replacement's first
+          // prompt includes the mandatory gap-analysis instruction.
+          const replacementPrompt = `${stepPrompt}\n\nMANDATORY GAP-ANALYSIS PHASE: you are a replacement agent. Before resuming implementation work: (1) read the task spec; (2) inspect the repository state (code, tests, working tree) — not what prior reports claim; (3) consult the journey history for prior step reports, handoffs, and progress judgments; (4) produce a gap analysis: remaining work and the next concrete sub-step you will execute. You may not resume implementation until this phase is complete.`;
+          const replacement = await executeHerdrCommunication(
+            { action: "prompt", role, prompt: replacementPrompt, timeoutMs: 120000 },
+            context,
+            communicationOptions,
+            signal,
+          );
+          const gapAnalysis = replacement.ok === true
+            ? String(replacement.report ?? "").slice(0, 512)
+            : undefined;
+          const previousScope = journey.steps.filter(s => s.gapAnalysis).at(-1)?.gapAnalysis;
+          const progressCredited = replacement.ok === true && (!previousScope || gapAnalysis !== previousScope);
+          journey.steps.push({
+            step: journey.steps.length + 1,
+            taskId: task.id,
+            status: replacement.ok === true ? "replaced" : "worker-unresponsive",
+            error: replacement.ok === true ? undefined : String(replacement.code),
+            gapAnalysis,
+            progressCredited,
+            handoff: {
+              timestamp: new Date().toISOString(),
+              role,
+              triggerCode: exchange.code,
+              gapOutcome: gapAnalysis ? "produced" : "failed",
+              progressJudgment: progressCredited ? "credited" : "not-credited",
+            },
+          });
+          if (!progressCredited) {
+            journey.status = "worker-unresponsive-exhausted";
+            return finish("worker-unresponsive-exhausted");
+          }
+          // The replacement demonstrated progress: continue the journey with
+          // the next task instead of finishing. The replacement's exchange
+          // outcome determines whether the current task is retried or skipped.
+          if (replacement.ok !== true) {
+            return finish("worker-unresponsive");
+          }
+        }
         return handoffToReplacement(`exchange ended with ${exchange.code}`, task.id);
       }
       journey.status = exchange.code === "role_blocked" ? "role-blocked" : "failed";

package/scripts/enforcement/herdr_communication_pi.js

@@ -131,6 +131,7 @@ function errorResult(operation, error) {
     code: known.code,
     reason: known.message,
     ...(known.diagnostic ? { diagnostic: known.diagnostic } : {}),
+    ...(known.deliveryState ? { deliveryState: known.deliveryState } : {}),
     nonAuthorizing: true,
     authorityCreated: false,
   };
@@ -676,7 +677,7 @@ async function invokeHerdr(action, params, context, options = {}, signal) {
         timeoutMs: processTimeout,
         maxOutputBytes: MAX_PROCESS_OUTPUT_BYTES,
       });
-    } catch {
+    } catch (error) {
       return { internalFailure: "spawn_error" };
     }
     raw = await awaitBounded(pending, processTimeout, signal);
@@ -992,15 +993,15 @@ function allMarkerOccurrences(text, standaloneOnly = false, additionalPair = und
   return occurrences.sort((left, right) => left.index - right.index || left.end - right.end);
 }
 
-function promptContractRange(text, marker, occurrenceIndex) {
+function promptContractRange(text, marker, occurrenceIndex, { boundEnd = false } = {}) {
   const anchor = text.lastIndexOf(REPORT_CONTRACT_LINE, occurrenceIndex);
   if (anchor < 0) return undefined;
   const markerStart = anchor + REPORT_CONTRACT_LINE.length;
   const open = text.indexOf(marker.open, markerStart);
   if (open < 0 || open > occurrenceIndex) return undefined;
   const close = text.indexOf(marker.close, open + marker.open.length);
-  if (close < occurrenceIndex) return undefined;
   const end = close + marker.close.length;
+  if (boundEnd && end > occurrenceIndex) return undefined;
   if (Buffer.byteLength(text.slice(anchor, end), "utf8") > MAX_PROMPT_CONTRACT_ECHO_BYTES) return undefined;
   if (!/^\s*$/.test(text.slice(markerStart, open)) || !/^\s*$/.test(text.slice(open + marker.open.length, close))) return undefined;
   const otherMarkers = [...new Set(Object.values(REPORT_MARKERS)
@@ -1053,16 +1054,11 @@ function extractLatestReport(text, role) {
   }
   const prior = relevant.at(-3);
   if (prior?.marker === marker.open) {
-    // `recent-unwrapped` can retain one older unmatched opening before the
-    // newer pair. Ignore that prefix only when it is preceded by terminal
-    // history; an opening at the window boundary remains fail-closed so a
-    // nested/duplicate opening cannot be reclassified as stale history.
-    const prefixOpenCount = relevant.slice(0, -2).filter((item) => item.marker === marker.open).length;
-    const historicalPrefix = prefixOpenCount === 1
-      && text.slice(0, prior.index).trim().length > 0;
-    if (!historicalPrefix) {
-      throw communicationError("report_duplicate_open", "the latest role report contains a duplicate or nested opening marker");
-    }
+    // A duplicate or nested opening before the latest pair is never
+    // reclassified as stale history: stale unmatched opens are surfaced as
+    // bounded evidence in the prompt flow only, and a plain read stays
+    // fail-closed.
+    throw communicationError("report_duplicate_open", "the latest role report contains a duplicate or nested opening marker");
   }
   const rawBody = text.slice(open.end, close.index);
   const nestedMarkers = allMarkerOccurrences(rawBody, false, marker)
@@ -1083,6 +1079,76 @@ function extractLatestReport(text, role) {
   return body;
 }
 
+function lineStarts(text) {
+  const starts = [0];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") starts.push(index + 1);
+  }
+  return starts;
+}
+
+function provenancedReportSegment(pre, post, sentPrompt, role) {
+  const marker = reportMarkersForRole(role);
+  const preLines = pre.split("\n");
+  const starts = lineStarts(post);
+  const candidates = [];
+  let from = 0;
+  while (from <= post.length) {
+    const start = post.indexOf(sentPrompt, from);
+    if (start < 0) break;
+    from = start + 1;
+    if (!starts.includes(start)) continue;
+    const range = marker && promptContractRange(post, marker, start + sentPrompt.length, { boundEnd: true });
+    if (!range || range.end !== start + sentPrompt.length) continue;
+    const prefix = post.slice(0, start);
+    const prefixLines = prefix.endsWith("\n") ? prefix.slice(0, -1).split("\n") : prefix.split("\n");
+    const shared = Math.min(prefixLines.length, preLines.length);
+    if (shared < 1) continue;
+    const preFirstLine = preLines[0];
+    const prefixContainsPreSnapshot = prefixLines.some((line) => line === preFirstLine);
+    const preTailMatchesPrefix = preLines.slice(-shared).every((line, index) => line === prefixLines[prefixLines.length - shared + index]);
+    if (prefixContainsPreSnapshot || preTailMatchesPrefix) {
+      candidates.push({ start, end: range.end, aligned: shared });
+    }
+  }
+  if (!candidates.length) throw communicationError("report_scope_unavailable", "the prompted exchange could not be proven from terminal history");
+  const max = Math.max(...candidates.map((candidate) => candidate.aligned));
+  const winners = candidates.filter((candidate) => candidate.aligned === max);
+  if (winners.length !== 1) throw communicationError("report_scope_unavailable", "the prompted exchange boundary is ambiguous");
+  return winners[0];
+}
+
+function extractReportFromSegment(text, role, fromIndex = 0, fullText = text) {
+  const marker = reportMarkersForRole(role);
+  const segment = text.slice(fromIndex);
+  const relevant = allMarkerOccurrences(segment, true, marker)
+    .filter((item) => (item.marker === marker.open || item.marker === marker.close)
+      && !isPromptContractMarker(fullText, { index: item.index + fromIndex, end: item.end + fromIndex }, marker));
+  if (!relevant.length) throw communicationError("report_missing", "no complete role-specific report was observed");
+  const close = relevant.at(-1);
+  if (close.marker === marker.open) {
+    throw communicationError("report_truncated", "the latest role report has no closing marker");
+  }
+  const open = relevant.at(-2);
+  if (!open || open.marker !== marker.open) {
+    throw communicationError("report_reversed", "the latest role report has no matching opening marker");
+  }
+  const rawBody = segment.slice(open.end, close.index);
+  const nestedMarkers = allMarkerOccurrences(rawBody, false, marker)
+    .filter((item) => !isPromptContractMarker(fullText, { index: open.end + item.index, end: open.end + item.end }, marker));
+  if (nestedMarkers.length) {
+    throw communicationError("report_nested", "the latest role report contains a nested report marker");
+  }
+  const body = removePromptContractEchoes(rawBody, marker)
+    .replace(/^[ \t]*\r?\n/, "")
+    .replace(/\r?\n[ \t]*$/, "");
+  if (!body.trim()) throw communicationError("report_empty", "the latest role report is empty");
+  if (Buffer.byteLength(body, "utf8") > MAX_REPORT_BYTES) {
+    throw communicationError("report_oversized", "the latest role report exceeds the bounded report size");
+  }
+  return body;
+}
+
 export function extractLatestHerdrReport(text, role) {
   requireRole(role);
   if (typeof text !== "string") throw communicationError("report_missing", "report history is not text");
@@ -1119,7 +1185,36 @@ export async function executeHerdrCommunication(params, context, options = {}, s
       // change before it accepts settlement. A separate wait command can race
       // and match the role's pre-existing idle state, reading the empty marker
       // template before the new response exists.
-      const prompted = await invokeHerdr(operation, request, context, options, signal);
+      let pre;
+      try {
+        pre = readText(await invokeHerdr("read", { action: "read", role }, context, options, signal));
+      } catch {
+        throw communicationError("report_scope_unavailable", "the pre-prompt terminal snapshot is unavailable");
+      }
+      const revalidated = await invokeHerdr("get", { action: "get", role }, context, options, signal);
+      publicAgentObservation(extractAgent(revalidated, "agent_info"), role, repositories, { requirePromptable: true });
+      let prompted;
+      try {
+        prompted = await invokeHerdr(operation, request, context, options, signal);
+      } catch (error) {
+        if (!(error instanceof HerdrCommunicationError) || error.code !== "prompt_stalled") throw error;
+        try {
+          const recovered = await invokeHerdr("get", { action: "get", role }, context, options, signal);
+          const recovery = publicAgentObservation(extractAgent(recovered, "agent_info"), role, repositories);
+          const recoveredSeq = stateChangeSeq(recovered);
+          const initialSeq = stateChangeSeq(current);
+          if (recovery.status === "idle" && initialSeq !== undefined && recoveredSeq !== undefined && recoveredSeq !== initialSeq) throw error;
+          const unknown = communicationError("prompt_delivery_unknown", "prompt delivery is unknown; the adapter did not retry, and only the caller may issue a new explicit prompt");
+          unknown.deliveryState = "unknown";
+          throw unknown;
+        } catch (recoveryError) {
+          if (recoveryError instanceof HerdrCommunicationError && ["prompt_stalled", "prompt_delivery_unknown"].includes(recoveryError.code)) throw recoveryError;
+          const unknown = communicationError("prompt_delivery_unknown", "prompt delivery is unknown; the adapter did not retry, and only the caller may issue a new explicit prompt");
+          unknown.deliveryState = "unknown";
+          unknown.diagnostic = boundedFailureDiagnostic(recoveryError?.message);
+          throw unknown;
+        }
+      }
       const observation = publicAgentObservation(extractAgent(prompted, "agent_prompted"), role, repositories);
       const waitedStatus = observation.status;
       if (!WAIT_STATUSES.has(waitedStatus)) {
@@ -1129,7 +1224,10 @@ export async function executeHerdrCommunication(params, context, options = {}, s
         return errorResult(operation, communicationError("role_blocked", "the prompted role reached blocked state", "blocked"));
       }
       const rawReport = await invokeHerdr("read", { action: "read", role }, context, options, signal);
-      const report = extractLatestHerdrReport(readText(rawReport), role);
+      const post = readText(rawReport);
+      const sentPrompt = promptWithReportRequirement(role, request.prompt);
+      const boundary = provenancedReportSegment(pre, post, sentPrompt, role);
+      const report = extractReportFromSegment(post, role, boundary.end);
       return successResult(operation, {
         status: "complete",
         role,

package/scripts/enforcement/linux_microvm_remote_fixture.sh

@@ -2587,6 +2587,14 @@ if ! gc_cache_growth_sample "\$session" /root/.npm /root/.cache /var/cache >/dev
   gc_log_event "\$session" "sweep" "GC-FSW-003" "sampler" "cache-growth sampling failed" "error" >/dev/null 2>&1 || true
 fi
 if [ ! -f "\$session/kill" ]; then gc_session_end "\$session" || :; fi
+# Session outcome (compliance-gap harness): the job's outcome marker, bounded
+# and redacted, appended to the containment log before the envelope. The job
+# may write /tmp/session/result; a missing file means the job ended without
+# an outcome.
+if [ -f "/tmp/session/result" ]; then
+  outcome=\$(head -c 256 "/tmp/session/result" | tr '\r\n' '  ' | sed 's/[[:cntrl:]]//g')
+  gc_log_event "\$session" "supervisor" "session-outcome" "outcome" "\$outcome" >/dev/null 2>&1 || :
+fi
 # Denial-evidence transport (design section 5): framed base64 envelope on the
 # console channel, UTF-8, LF-only, fixed key order; pty-safe alphabet.
 if [ -f "\$session/containment.log.jsonl" ]; then