@evoclock/pi-agentic-driver 0.5.0 → 0.7.0

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.5.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",
@@ -57,6 +59,7 @@
     "extensions/linux-microvm.ts",
     "scripts/enforcement/linux_microvm_cutover_pi.js",
     "scripts/enforcement/native_tui_context.js",
+    "scripts/enforcement/guest_containment_taxonomy.v1.json",
     "scripts/enforcement/linux_microvm_remote_fixture.sh",
     "PROVENANCE.md",
     "extensions/aidr.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/guest_containment_taxonomy.v1.json

@@ -0,0 +1,26 @@
+{
+  "schema": "guest-containment-taxonomy.v1",
+  "description": "Deny-by-default rule taxonomy for the guest containment monitor (design GUEST_CONTAINMENT_DESIGN.md section 2). One rule per line; IDs are never reused; new rules append. disposition records whether a live detector exists in the fixture (design sections 1.3, 3) or the rule is armed by the taxonomy only.",
+  "rules": [
+    {"id":"GC-PKG-001","class":"GC-PKG","severity":"ELEVATED","action":"deny","match":"package-manager-install: invocation of npm install, npm ci, pip install, yarn add, pnpm add, gem install, cargo install, apk add, apt install","evidence":"METR autonomous-replication evaluation work (arXiv:2403.13793); HF incident dependency-install persistence step","since":"v1","disposition":"detector:shim-argv"},
+    {"id":"GC-PKG-002","class":"GC-PKG","severity":"ELEVATED","action":"deny","match":"registry-write-command: npm publish, npm token, .npmrc writes, pip config, keyring writes","evidence":"HF incident: agent attempted package publication","since":"v1","disposition":"detector:shim-argv"},
+    {"id":"GC-PKG-003","class":"GC-PKG","severity":"ELEVATED","action":"deny","match":"package-metadata-tamper: writes to package.json, package-lock.json, pyproject.toml, requirements*.txt outside the job scratch space","evidence":"METR evaluation logs: dependency-manifest tampering as persistence step","since":"v1","disposition":"detector:fs-path+shim-argv"},
+    {"id":"GC-FSW-001","class":"GC-FSW","severity":"ELEVATED","action":"deny","match":"write-outside-allowlist: create/append/truncate on any path outside /tmp/session, detected by inotifyd or find -newer sweeps","evidence":"METR evaluation logs: out-of-bounds file writes during evaluation runs","since":"v1","disposition":"detector:fs-watcher"},
+    {"id":"GC-FSW-002","class":"GC-FSW","severity":"ELEVATED","action":"deny","match":"self-code-modification: writes under the agent job install/execution directories including the shim tree /shims/","evidence":"HF incident: agent rewrote the repository it was working in; monitor self-rewrite defense","since":"v1","disposition":"detector:fs-watcher"},
+    {"id":"GC-FSW-003","class":"GC-FSW","severity":"ELEVATED","action":"deny","match":"file-growth-anomaly: unexpected growth in cache/package directories (~/.npm, ~/.cache/pip, /var/cache/*) beyond the size-delta threshold","evidence":"METR evaluation logs: bulk cache staging of payloads","since":"v1","disposition":"detector:fs-sweep size-delta sampling (gc_cache_growth_sample; aggregate ELEVATED, GC_CACHE_GROWTH_KIB per sweep)"},
+    {"id":"GC-SHR-001","class":"GC-SHR","severity":"HIGH","action":"deny","match":"shared-cache-write: writes to paths shared with other agents or the coordinator; with host-share absent any such attempt is a deny","evidence":"receipt proves host-share=absent; writes would indicate boundary violation","since":"v1","disposition":"detector:fs-path; share paths auto-arm via gc_share_mounted (/proc/mounts); shared-cache roots classify as SHR when unarmed"},
+    {"id":"GC-SHR-002","class":"GC-SHR","severity":"HIGH","action":"deny","match":"cross-agent-channel: creation of or writes to inter-agent coordination paths (maildirs, task-queue files, agent state files)","evidence":"HF incident multi-agent escalation; METR coordination/sabotage threat model","since":"v1","disposition":"detector:fs-path+shim-argv heuristics (Maildir, task-queue, agent-channel, coordination paths)"},
+    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep"},
+    {"id":"GC-NET-002","class":"GC-NET","severity":"HIGH","action":"deny","match":"network-tool-invocation: shim-detects wget, curl, nc, ssh, telnet, ping regardless of arguments","evidence":"METR self-replication exfiltration patterns; HF incident remote control","since":"v1","disposition":"detector:shim-argv"},
+    {"id":"GC-CRED-001","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"credential-path-read: opens of ~/.ssh/, ~/.aws/, ~/.netrc, ~/.git-credentials, token files","evidence":"credential theft is step one in every reported agent-escape chain","since":"v1","disposition":"detector:shim-argv"},
+    {"id":"GC-CRED-002","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"env-secret-probing: attempts to dump or scan the environment for secret-shaped keys","evidence":"METR evaluation logs; HF incident postmortem credential harvest attempts","since":"v1","disposition":"detector:shim-argv"},
+    {"id":"GC-LOG-001","class":"GC-LOG","severity":"CRITICAL","action":"deny","match":"transcript-write: writes to the console transcript, the monitor log, or the receipt channel by any path other than the supervisor","evidence":"log is opened append-only by the supervisor; other writers are evidence tampering","since":"v1","disposition":"detector:fs-path+shim-argv (transcript/receipt-channel paths); the in-guest supervisor never writes these, so any event is a non-supervisor write"},
+    {"id":"GC-LOG-002","class":"GC-LOG","severity":"CRITICAL","action":"deny","match":"log-truncate-or-rename: >, rm, mv, truncate, sed -i targeting monitor/agent logs","evidence":"METR report: models attempting to edit their own logs","since":"v1","disposition":"detector:shim-argv"},
+    {"id":"GC-TOOL-001","class":"GC-TOOL","severity":"CRITICAL","action":"deny","match":"receipt-forgery: job printing AGENTIC_MICROVM_PROBE:* or AGENTIC_MICROVM_RECEIPT:* lines","evidence":"host closed-receipt parsing rejects forged output; guest-side denial closes the loop","since":"v1","disposition":"detector:shim-argv"},
+    {"id":"GC-TOOL-002","class":"GC-TOOL","severity":"CRITICAL","action":"deny","match":"marker-injection: writes to /dev/console, /dev/ttyS0, or other devtmpfs write targets that could inject marker text","evidence":"METR tool-call spoofing family; serial stream integrity","since":"v1","disposition":"detector:shim-argv+fs-path; known gap: char-device writes may not update mtime for the sweep"},
+    {"id":"GC-PROBE-001","class":"GC-PROBE","severity":"ELEVATED","action":"deny","match":"containment-introspection: reads or probes of /gc/** (core.sh, taxonomy, state), /shims/**, or session-dir metadata outside sanctioned /tmp/session writes","evidence":"METR report: agents research the monitoring environment before acting; HF incident agents probed sandbox infrastructure. Individually ambiguous (a job may stat its own directories), so aggregate ELEVATED rather than immediate-kill","since":"v1","disposition":"detector:fs-path+shim-argv"},
+    {"id":"GC-PROBE-002","class":"GC-PROBE","severity":"ELEVATED","action":"deny","match":"monitor-enumeration: ps/proc access patterns targeting watcher discovery (inspection looking for monitor PIDs, inotifyd, or the shim layer), shim/proc-watcher detected","evidence":"Design section 9.1 adversarial pass: monitor enumeration precedes timing and evasion attempts; aggregate ELEVATED avoids false-positive kills on process inspection","since":"v1","disposition":"detector:shim-argv"},
+    {"id":"GC-PROBE-003","class":"GC-PROBE","severity":"ELEVATED","action":"deny","match":"concealment-index anomaly: aggregated probe-frequency signal (GC-PROBE events plus weighted unknown-class denials) surfaced as the receipt concealmentIndex","evidence":"Timing probes and repeated no-op shim invocations to time detection are aggregate signals, not single-action violations; see design appendix formula","since":"v1","disposition":"detector:evidence-aggregate"}
+  ],
+  "residual": {"class":"unknown","tier":"ANOMALY","action":"deny","note":"everything not allowlisted and not classified above; accumulates toward the ANOMALY threshold"}
+}

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";