@cleocode/playbooks 2026.6.13 → 2026.6.14

package/dist/index.d.ts

@@ -27,5 +27,5 @@ export { approveGate, type CreateApprovalGateInput, createApprovalGate, E_APPROV
 export { type MigratePlaybookFileResult, migratePlaybook, migratePlaybookFile, type NodeComplianceEntry, type PlaybookComplianceReport, validatePlaybookCompliance, } from './migrate-e4.js';
 export { type ParsePlaybookResult, PlaybookParseError, parsePlaybook, } from './parser.js';
 export { DEFAULT_POLICY_RULES, type EvaluatePolicyResult, evaluatePolicy, type PolicyRule, } from './policy.js';
-export { type AgentDispatcher, type AgentDispatchInput, type AgentDispatchResult, type DeterministicRunInput, type DeterministicRunner, type DeterministicRunResult, E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, type ExecutePlaybookOptions, type ExecutePlaybookResult, executePlaybook, type PlaybookTerminalStatus, type ResumePlaybookOptions, resumePlaybook, } from './runtime.js';
+export { type AgentDispatcher, type AgentDispatchInput, type AgentDispatchResult, type DeterministicRunInput, type DeterministicRunner, type DeterministicRunResult, E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, type ExecutePlaybookOptions, type ExecutePlaybookResult, executePlaybook, type PlaybookTerminalStatus, type ResumePlaybookOptions, resolveStepBindings, resumePlaybook, } from './runtime.js';
 export { type CreatePlaybookApprovalInput, type CreatePlaybookRunInput, createPlaybookApproval, createPlaybookRun, deletePlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, type ListPlaybookRunsOptions, listPlaybookApprovals, listPlaybookRuns, updatePlaybookApproval, updatePlaybookRun, } from './state.js';

package/dist/index.js

@@ -37,6 +37,8 @@ export { DEFAULT_POLICY_RULES, evaluatePolicy, } from './policy.js';
 // ensures-schema registry (`@cleocode/contracts` data + `@cleocode/core`
 // accessors). No cross-package consumer imported them, so dropping the
 // re-exports is safe.
-export { E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, executePlaybook, resumePlaybook, } from './runtime.js';
+export { E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, executePlaybook, 
+// T1944 (M4): per-step `node.inputs` → dispatch-boundary binding resolver.
+resolveStepBindings, resumePlaybook, } from './runtime.js';
 // W4-8: state layer CRUD for playbook_runs + playbook_approvals
 export { createPlaybookApproval, createPlaybookRun, deletePlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, listPlaybookApprovals, listPlaybookRuns, updatePlaybookApproval, updatePlaybookRun, } from './state.js';

package/dist/parser.js

@@ -230,6 +230,17 @@ function parseAgenticNode(raw, base, index) {
         inputs = acc;
     }
     const context_files = parseStringArray(raw.context_files, `nodes[${index}].context_files`);
+    // T11759 (M4): per-stage LLM pin. Each is an optional non-empty string — the
+    // dispatcher resolves them through the E9 chokepoint at dispatch time. Absent
+    // fields leave resolution unchanged (additive).
+    const profile = parseOptionalNonEmptyString(raw.profile, `nodes[${index}].profile`);
+    const model = parseOptionalNonEmptyString(raw.model, `nodes[${index}].model`);
+    const provider = parseOptionalNonEmptyString(raw.provider, `nodes[${index}].provider`);
+    // T1947 (M4): per-step skill/tool allowlists. Each is an optional string[] —
+    // enforced at spawn time by composeSpawnPayload as an INTERSECTION against the
+    // Tier-0/1/2 baseline (restrict-only, never expand). Absent → no restriction.
+    const allowed_skills = parseStringArray(raw.allowed_skills, `nodes[${index}].allowed_skills`);
+    const allowed_tools = parseStringArray(raw.allowed_tools, `nodes[${index}].allowed_tools`);
     return {
         ...base,
         type: 'agentic',
@@ -238,6 +249,11 @@ function parseAgenticNode(raw, base, index) {
         role,
         inputs,
         ...(context_files !== undefined ? { context_files } : {}),
+        ...(profile !== undefined ? { profile } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(provider !== undefined ? { provider } : {}),
+        ...(allowed_skills !== undefined ? { allowed_skills } : {}),
+        ...(allowed_tools !== undefined ? { allowed_tools } : {}),
     };
 }
 function parseDeterministicNode(raw, base, index) {
@@ -529,6 +545,23 @@ function parseStringArray(raw, field) {
         return v;
     });
 }
+/**
+ * Parse an optional scalar string field that, when present, MUST be a non-empty
+ * string (T11759 — the per-stage LLM pins `profile` / `model` / `provider`).
+ *
+ * @param raw - Raw YAML value.
+ * @param field - Field path for diagnostics.
+ * @returns The trimmed-as-authored string, or `undefined` when absent.
+ * @throws {PlaybookParseError} When present but not a non-empty string.
+ */
+function parseOptionalNonEmptyString(raw, field) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw new PlaybookParseError(`${field} must be a non-empty string`, field, raw);
+    }
+    return raw;
+}
 /**
  * Detect cycles across the combined edge-set (explicit `edges[]` plus
  * `depends[]` back-references). Uses 3-color DFS.

package/dist/runtime.d.ts

@@ -35,7 +35,7 @@
  * @task T1261 PSYCHE E4 — contract enforcement + context boundary
  */
 import type { DatabaseSync } from 'node:sqlite';
-import type { PlaybookDefinition } from '@cleocode/contracts';
+import type { PlaybookAgenticNode, PlaybookDefinition } from '@cleocode/contracts';
 /**
  * Input payload handed to {@link AgentDispatcher.dispatch} on every
  * `agentic` node execution. All fields are read-only from the dispatcher's
@@ -52,8 +52,69 @@ export interface AgentDispatchInput {
     taskId: string;
     /** Snapshot of the accumulated bindings at dispatch time. */
     context: Record<string, unknown>;
+    /**
+     * Per-step resolved bindings for this node (T1944 · M4 cantbook done-gate).
+     *
+     * Additive field. Built by {@link resolveStepBindings} from
+     * {@link PlaybookAgenticNode.inputs} — each declared input is a mustache
+     * `{{path}}` template resolved against the accumulated run `context` (via the
+     * canonical T1238 {@link DefaultVariableResolver}), then layered ON TOP of
+     * that context so a step input SHADOWS a same-named context key.
+     *
+     * The runtime always populates this when dispatching an agentic node (it is a
+     * shallow copy of `context` when the node declares no `inputs`). It is typed
+     * optional only to keep the change strictly additive for any out-of-tree
+     * dispatcher that constructs an {@link AgentDispatchInput} directly.
+     *
+     * Resolver precedence (highest → lowest):
+     * `step bindings ⊳ playbook bindings (run context) ⊳ session ⊳ project-context ⊳ env ⊳ default`.
+     */
+    bindings?: Record<string, unknown>;
     /** 1-based iteration counter for this specific node (retry-aware). */
     iteration: number;
+    /**
+     * Name of the running playbook (`.cantbook`) — the first segment of the
+     * cantbook node identity `cantbook:<playbook>#<nodeId>` (T11759 · M4).
+     *
+     * Additive. The runtime always populates it for agentic nodes; the dispatcher
+     * uses it (with {@link nodeId}) to resolve a declared per-stage LLM profile
+     * through the E9 chokepoint. Optional only so an out-of-tree dispatcher that
+     * constructs an {@link AgentDispatchInput} directly remains source-compatible.
+     */
+    playbookName?: string;
+    /**
+     * The node's declared per-stage LLM pin (T11759 · M4) — lifted verbatim from
+     * {@link PlaybookAgenticNode.profile} / `.model` / `.provider`.
+     *
+     * Additive + all-optional. When any field is set the dispatcher resolves the
+     * stage's LLM through `resolveLLMForSystem` keyed by the cantbook node
+     * identity, honoring the profile pin; when all are unset resolution is
+     * unchanged. The runtime NEVER acts on these itself — it only forwards them.
+     */
+    profile?: string;
+    /** Inline model-id pin forwarded from {@link PlaybookAgenticNode.model} (T11759). */
+    model?: string;
+    /** Inline provider pin forwarded from {@link PlaybookAgenticNode.provider} (T11759). */
+    provider?: string;
+    /**
+     * Per-step skill allowlist lifted verbatim from
+     * {@link PlaybookAgenticNode.allowed_skills} (T1947 · M4).
+     *
+     * Additive + optional. When present the dispatcher passes it to
+     * `composeSpawnPayload`, which intersects it with the resolved agent's skill
+     * baseline (Tier-0/1/2) — the allowlist can only RESTRICT, never expand. When
+     * absent the spawn carries its full baseline skill set. The runtime NEVER acts
+     * on this itself — it only forwards it.
+     */
+    allowedSkills?: string[];
+    /**
+     * Per-step tool allowlist lifted verbatim from
+     * {@link PlaybookAgenticNode.allowed_tools} (T1947 · M4).
+     *
+     * Same restrict-only intersection semantics as {@link allowedSkills}, applied
+     * to the spawn's tool baseline.
+     */
+    allowedTools?: string[];
 }
 /**
  * Terminal output returned by {@link AgentDispatcher.dispatch}. The runtime
@@ -191,6 +252,45 @@ export declare const E_PLAYBOOK_RUNTIME_INVALID: "E_PLAYBOOK_RUNTIME_INVALID";
  * does not resolve to an `approved` gate.
  */
 export declare const E_PLAYBOOK_RESUME_BLOCKED: "E_PLAYBOOK_RESUME_BLOCKED";
+/**
+ * Resolve a {@link PlaybookAgenticNode}'s declared `inputs` into the per-step
+ * binding map handed to the dispatcher (T1944 · M4 cantbook done-gate).
+ *
+ * Each `inputs` value is a mustache `{{path}}` template. Templates are resolved
+ * against the accumulated run `context` using the canonical T1238
+ * {@link DefaultVariableResolver} (no second substitution engine — DRY) and the
+ * resolved key/value pairs are then layered ON TOP of the run context. The
+ * result is the dispatch-time binding map.
+ *
+ * ## Canonical resolver precedence (highest → lowest)
+ *
+ * 1. **step bindings** — the resolved `node.inputs` themselves. They are merged
+ *    LAST over the run context, so a step input always SHADOWS a same-named
+ *    context key (AC3 / AC6).
+ * 2. **playbook bindings** — the accumulated run `context` (seeded from the
+ *    playbook's declared inputs + every prior node's merged output).
+ * 3. **session / project-context / env / default** — supplied to the underlying
+ *    {@link DefaultVariableResolver} via the {@link SubstitutionContext} below.
+ *
+ * The run `context` is exposed to the resolver through BOTH the `projectContext`
+ * tier (which supports dot-notation, so `{{inputs.epicId}}` and `{{context.foo}}`
+ * resolve into nested objects) and `process.env` (the `env` tier). The
+ * resolver runs in lenient mode.
+ *
+ * ## Missing-key rule
+ *
+ * Lenient. When a `{{path}}` template references a value that resolves through
+ * NO tier, the literal placeholder text is left intact in the bound value (e.g.
+ * `{{missing}}` stays `"{{missing}}"`). This mirrors the canonical T1238
+ * lenient posture — a missing input never aborts the dispatch; the agent
+ * receives the literal placeholder and can fail loudly downstream if required.
+ *
+ * @param node - The agentic node whose `inputs` are resolved.
+ * @param context - The accumulated run bindings at dispatch time.
+ * @returns A new binding map = `{ ...context, ...resolvedStepInputs }`. When the
+ *   node declares no `inputs`, this is a shallow copy of `context`.
+ */
+export declare function resolveStepBindings(node: PlaybookAgenticNode, context: Record<string, unknown>): Record<string, unknown>;
 /**
  * Execute a playbook from its entry node until a terminal state is reached
  * (`completed`, `failed`, `exceeded_iteration_cap`, or `pending_approval`).

package/dist/runtime.js

@@ -41,7 +41,10 @@ import { dirname, join } from 'node:path';
 // contracts leaf); core does NOT depend on playbooks, so this import direction
 // is cycle-free (mirrors the existing `@cleocode/core/store/schema` import in
 // `./schema.ts`).
-import { getEnsuresSchema, listEnsuresSchemaNames } from '@cleocode/core';
+// T1944 (M4): `defaultVariableResolver` is the canonical T1238 mustache engine,
+// re-used here (DRY) to resolve `PlaybookAgenticNode.inputs` `{{path}}`
+// templates at the dispatch boundary rather than re-implementing substitution.
+import { defaultVariableResolver, getEnsuresSchema, listEnsuresSchemaNames } from '@cleocode/core';
 import { createApprovalGate, getPlaybookSecret } from './approval.js';
 import { createPlaybookApproval, createPlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, updatePlaybookRun, } from './state.js';
 /**
@@ -249,12 +252,74 @@ function resolveNode(nodeId, idx) {
 // ---------------------------------------------------------------------------
 // Per-node execution
 // ---------------------------------------------------------------------------
+/**
+ * Resolve a {@link PlaybookAgenticNode}'s declared `inputs` into the per-step
+ * binding map handed to the dispatcher (T1944 · M4 cantbook done-gate).
+ *
+ * Each `inputs` value is a mustache `{{path}}` template. Templates are resolved
+ * against the accumulated run `context` using the canonical T1238
+ * {@link DefaultVariableResolver} (no second substitution engine — DRY) and the
+ * resolved key/value pairs are then layered ON TOP of the run context. The
+ * result is the dispatch-time binding map.
+ *
+ * ## Canonical resolver precedence (highest → lowest)
+ *
+ * 1. **step bindings** — the resolved `node.inputs` themselves. They are merged
+ *    LAST over the run context, so a step input always SHADOWS a same-named
+ *    context key (AC3 / AC6).
+ * 2. **playbook bindings** — the accumulated run `context` (seeded from the
+ *    playbook's declared inputs + every prior node's merged output).
+ * 3. **session / project-context / env / default** — supplied to the underlying
+ *    {@link DefaultVariableResolver} via the {@link SubstitutionContext} below.
+ *
+ * The run `context` is exposed to the resolver through BOTH the `projectContext`
+ * tier (which supports dot-notation, so `{{inputs.epicId}}` and `{{context.foo}}`
+ * resolve into nested objects) and `process.env` (the `env` tier). The
+ * resolver runs in lenient mode.
+ *
+ * ## Missing-key rule
+ *
+ * Lenient. When a `{{path}}` template references a value that resolves through
+ * NO tier, the literal placeholder text is left intact in the bound value (e.g.
+ * `{{missing}}` stays `"{{missing}}"`). This mirrors the canonical T1238
+ * lenient posture — a missing input never aborts the dispatch; the agent
+ * receives the literal placeholder and can fail loudly downstream if required.
+ *
+ * @param node - The agentic node whose `inputs` are resolved.
+ * @param context - The accumulated run bindings at dispatch time.
+ * @returns A new binding map = `{ ...context, ...resolvedStepInputs }`. When the
+ *   node declares no `inputs`, this is a shallow copy of `context`.
+ */
+export function resolveStepBindings(node, context) {
+    // No declared inputs — bindings are just a snapshot of the run context.
+    if (node.inputs === undefined || Object.keys(node.inputs).length === 0) {
+        return { ...context };
+    }
+    // Expose the run context to the canonical resolver. `projectContext` is the
+    // dot-notation-capable tier, so `{{inputs.epicId}}` / `{{context.foo.bar}}`
+    // walk into nested objects; flat keys (`{{epicId}}`) resolve via a
+    // single-segment walk on the same tier.
+    const substitutionContext = {
+        projectContext: context,
+        env: process.env,
+    };
+    const resolvedInputs = {};
+    for (const [key, template] of Object.entries(node.inputs)) {
+        // Lenient resolve — missing placeholders are left literal (see TSDoc).
+        const result = defaultVariableResolver.resolve(template, substitutionContext, {
+            strict: false,
+        });
+        resolvedInputs[key] = result.text;
+    }
+    // Step bindings shadow the run context for same-named keys (AC3 / AC6).
+    return { ...context, ...resolvedInputs };
+}
 /**
  * Execute a single `agentic` node via the injected {@link AgentDispatcher}.
  * The dispatcher receives the current context and must return a success /
  * failure envelope — any thrown exception is normalized into a failure.
  */
-async function executeAgenticNode(node, runId, context, iteration, dispatcher) {
+async function executeAgenticNode(node, runId, context, iteration, dispatcher, playbookName) {
     const agentId = node.agent ?? node.skill;
     if (agentId === undefined) {
         // Parser guarantees at-least-one, but narrow defensively.
@@ -265,6 +330,9 @@ async function executeAgenticNode(node, runId, context, iteration, dispatcher) {
     }
     const taskIdRaw = context['taskId'];
     const taskId = typeof taskIdRaw === 'string' && taskIdRaw.length > 0 ? taskIdRaw : runId;
+    // T1944 (M4): resolve `node.inputs` `{{path}}` templates against the run
+    // context and layer them on top so step inputs shadow context (AC1/AC2/AC3).
+    const bindings = resolveStepBindings(node, context);
     try {
         const result = await dispatcher.dispatch({
             runId,
@@ -272,7 +340,20 @@ async function executeAgenticNode(node, runId, context, iteration, dispatcher) {
             agentId,
             taskId,
             context: { ...context },
+            bindings,
             iteration,
+            // T11759 (M4): forward the playbook name + the node's per-stage LLM pin so
+            // the dispatcher can resolve a declared `profile:` through the E9
+            // chokepoint. All-additive; omitted when the node declares no pin.
+            playbookName,
+            ...(node.profile !== undefined ? { profile: node.profile } : {}),
+            ...(node.model !== undefined ? { model: node.model } : {}),
+            ...(node.provider !== undefined ? { provider: node.provider } : {}),
+            // T1947 (M4): forward the per-step skill/tool allowlists so the dispatcher
+            // can intersect them against the Tier-0/1/2 baseline at spawn time. Omitted
+            // when the node declares no allowlist (additive — baseline unchanged).
+            ...(node.allowed_skills !== undefined ? { allowedSkills: node.allowed_skills } : {}),
+            ...(node.allowed_tools !== undefined ? { allowedTools: node.allowed_tools } : {}),
         });
         if (result.status === 'success') {
             return { kind: 'success', output: result.output };
@@ -512,7 +593,7 @@ async function runFromNode(args) {
         }
         let outcome;
         if (node.type === 'agentic') {
-            outcome = await executeAgenticNode(node, run.runId, context, attempt, dispatcher);
+            outcome = await executeAgenticNode(node, run.runId, context, attempt, dispatcher, playbook.name);
         }
         else if (node.type === 'deterministic') {
             outcome = await executeDeterministicNode(node, run.runId, context, attempt, dispatcher, deterministicRunner);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/playbooks",
-  "version": "2026.6.13",
+  "version": "2026.6.14",
   "description": "Playbook DSL + runtime for CLEO — T889 Orchestration Coherence v3",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,8 +19,8 @@
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
     "js-yaml": "^4.1.0",
-    "@cleocode/contracts": "2026.6.13",
-    "@cleocode/core": "2026.6.13"
+    "@cleocode/contracts": "2026.6.14",
+    "@cleocode/core": "2026.6.14"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/__tests__/fixtures/pi-skill-only.cantbook

@@ -0,0 +1,26 @@
+version: "1.0"
+name: pi-skill-only
+description: >
+  T11945 (M4) deterministic e2e fixture — a single skill-only agentic node. The
+  node names a real `ct-*` skill so the production dispatcher's
+  `runSkillNodeOrSpawn` takes the IN-PROCESS skill path (findSkill resolves it)
+  and, when a Pi runner is injected, routes the node THROUGH the PiAgentAdapter.
+  No `requires`/`ensures` contracts so schema enforcement never interferes with
+  the dispatch-path assertion. With no LLM credential resolvable in CI the Pi
+  loop terminates with the cleo-owned no-credential failure — proving the call
+  reached the Pi streamFn (the E9 chokepoint), not a live round-trip.
+
+inputs:
+  - name: taskId
+    required: true
+    description: Task id being executed (seeds the run context).
+
+nodes:
+  - id: execute
+    type: agentic
+    skill: ct-task-executor
+    description: >
+      Single skill-only node — routes in-process through the SkillExecutorAdapter,
+      and through the PiAgentAdapter when the Pi runner is wired (T11945).
+
+edges: []

package/src/__tests__/guarded-deterministic-dispatch.test.ts

@@ -0,0 +1,225 @@
+/**
+ * T11802 (M4 cantbook done-gate) — every `deterministic` (shell) node dispatch in
+ * `executePlaybook` routes through the `guard.ts` deny-first chokepoint.
+ *
+ * ## What this proves
+ *
+ *  - **AC1 / AC2** — a minimal `.cantbook` with a `deterministic` shell step,
+ *    executed through the REAL {@link executePlaybook} runtime with the
+ *    production-shaped {@link createGuardedDeterministicRunner} wired to a real
+ *    {@link createToolGuard}, reaches the guard: the spawned command actually runs
+ *    THROUGH `guard.executeShell` (proven by captured stdout in the merged run
+ *    context). There is NO `child_process` import in the runtime call graph — the
+ *    guard owns the spawn.
+ *  - **AC3** — when the SAME runtime dispatches a `deterministic` node whose
+ *    command is on the guard's denylist (`enforce` mode), the guard REJECTS it
+ *    BEFORE any process is spawned; the node terminates as a contained failure
+ *    (the runtime contract is non-throwing) carrying the guard's
+ *    `E_TOOL_GUARD_DENIED` message.
+ *  - **AC5** — no new state machine: the runtime is unchanged; only the injected
+ *    `deterministicRunner` is the guard-routed one.
+ *
+ * ## Determinism + isolation
+ *
+ *  - IN-PROCESS only — vitest source, NO subprocess driver (tsx unresolvable in CI).
+ *  - daemon-OFF — an in-memory `node:sqlite` DB, no daemon.
+ *  - The allowed command is `node -e <print>` (always present on the test box, no
+ *    network, no filesystem mutation) so the "guard actually spawned" assertion is
+ *    portable and side-effect-free.
+ *  - A temp project root scopes the guard's `allowedRoots`; `cwd` is pinned to it.
+ *
+ * @epic T11391
+ * @task T11802
+ * @saga T11387
+ */
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import type { PlaybookDefinition, PlaybookDeterministicNode } from '@cleocode/contracts';
+import {
+  createGuardedDeterministicRunner,
+  createToolGuard,
+  DEFAULT_DETERMINISTIC_DENIED_COMMANDS,
+} from '@cleocode/core/internal';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { type DeterministicRunner, executePlaybook } from '../runtime.js';
+
+const _require = createRequire(import.meta.url);
+type DatabaseSync = _DatabaseSyncType;
+const { DatabaseSync } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof _DatabaseSyncType>) => DatabaseSync;
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the T889 playbook-tables migration SQL. */
+const MIGRATION_SQL = resolve(
+  __dirname,
+  '../../../core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/migration.sql',
+);
+
+/** Apply a multi-statement Drizzle migration (split on the breakpoint token). */
+function applyMigration(db: DatabaseSync, sql: string): void {
+  const statements = sql
+    .split(/--> statement-breakpoint/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  for (const stmt of statements) {
+    const lines = stmt.split('\n');
+    const hasSql = lines.some((l) => l.trim().length > 0 && !l.trim().startsWith('--'));
+    if (hasSql) db.exec(stmt);
+  }
+}
+
+/** Build a single-node `deterministic` playbook (the entry node is terminal). */
+function singleDeterministicPlaybook(node: PlaybookDeterministicNode): PlaybookDefinition {
+  return { version: '1.0', name: 'guarded-shell', nodes: [node], edges: [] };
+}
+
+describe('T11802 (M4): deterministic node dispatch routes through guard.ts', () => {
+  let db: DatabaseSync;
+  let projectRoot: string;
+
+  beforeEach(() => {
+    db = new DatabaseSync(':memory:');
+    db.exec('PRAGMA foreign_keys=ON');
+    applyMigration(db, readFileSync(MIGRATION_SQL, 'utf8'));
+    projectRoot = mkdtempSync(join(tmpdir(), 't11802-guarded-shell-'));
+  });
+
+  afterEach(() => {
+    db.close();
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  /**
+   * Build the production-shaped deterministic runner: the SAME guard the CLI's
+   * `buildDefaultDeterministicRunner` constructs (allowedRoots + denylist +
+   * enforce), wrapped by `createGuardedDeterministicRunner`.
+   */
+  function buildGuardedRunner(): DeterministicRunner {
+    const tools = createToolGuard({
+      allowedRoots: [projectRoot],
+      deniedCommands: DEFAULT_DETERMINISTIC_DENIED_COMMANDS,
+      mode: 'enforce',
+    });
+    // Structurally assignable to the runtime's DeterministicRunner.
+    return createGuardedDeterministicRunner({ tools });
+  }
+
+  it('AC2: a shell step is intercepted by the guard — the command runs THROUGH guard.executeShell', async () => {
+    // `node -e` prints a sentinel; capturing it proves the guard actually
+    // spawned the process (not a mock).
+    const SENTINEL = 'guard-intercepted-T11802';
+    const node: PlaybookDeterministicNode = {
+      id: 'shell',
+      type: 'deterministic',
+      command: process.execPath, // node — always present, never on the denylist
+      args: ['-e', `process.stdout.write(${JSON.stringify(SENTINEL)})`],
+      cwd: projectRoot,
+    };
+
+    const result = await executePlaybook({
+      db,
+      playbook: singleDeterministicPlaybook(node),
+      playbookHash: 'hash-allowed',
+      initialContext: { taskId: 'T11802' },
+      dispatcher: {
+        // The agentic dispatcher must NEVER be reached for a deterministic node.
+        async dispatch() {
+          return {
+            status: 'failure',
+            output: {},
+            error: 'agentic dispatcher reached for a deterministic node — guard bypassed!',
+          };
+        },
+      },
+      deterministicRunner: buildGuardedRunner(),
+    });
+
+    expect(result.terminalStatus).toBe('completed');
+    // The guard's executeShell captured the child's stdout into the merged
+    // context — dispositive that the command was spawned THROUGH the guard.
+    expect(result.finalContext['shell_stdout']).toBe(SENTINEL);
+    expect(result.finalContext['shell_exitCode']).toBe(0);
+  });
+
+  it('AC3: a denied command is rejected by the guard denylist when dispatched from executePlaybook', async () => {
+    // `rm` is on DEFAULT_DETERMINISTIC_DENIED_COMMANDS — the guard rejects it
+    // BEFORE any process is spawned (enforce mode).
+    expect(DEFAULT_DETERMINISTIC_DENIED_COMMANDS).toContain('rm');
+
+    const node: PlaybookDeterministicNode = {
+      id: 'danger',
+      type: 'deterministic',
+      command: 'rm',
+      args: ['-rf', join(projectRoot, 'anything')],
+      cwd: projectRoot,
+      // One attempt → first denial is terminal (no retry storms).
+      on_failure: { max_iterations: 1 },
+    };
+
+    const result = await executePlaybook({
+      db,
+      playbook: singleDeterministicPlaybook(node),
+      playbookHash: 'hash-denied',
+      initialContext: { taskId: 'T11802' },
+      dispatcher: {
+        async dispatch() {
+          return {
+            status: 'failure',
+            output: {},
+            error: 'agentic dispatcher reached for a deterministic node — guard bypassed!',
+          };
+        },
+      },
+      deterministicRunner: buildGuardedRunner(),
+      maxIterationsDefault: 1,
+    });
+
+    // The denial is a contained node failure (the runtime never throws).
+    expect(result.terminalStatus).toBe('exceeded_iteration_cap');
+    expect(result.exceededNodeId).toBe('danger');
+    // The guard's enforce-mode rejection message reached the runtime.
+    expect(result.errorContext ?? '').toMatch(/denylist|E_TOOL_GUARD_DENIED|"rm"/);
+  });
+
+  it('AC1: the guard is the ONLY spawn path — a denied command never spawns rm', async () => {
+    // Targeting a path INSIDE the project root so, IF the guard were bypassed,
+    // rm would actually delete it. The guard must stop it first. We assert the
+    // failure shape (no rm executed) rather than filesystem side effects so the
+    // test is hermetic even on a box without `rm`.
+    const node: PlaybookDeterministicNode = {
+      id: 'danger',
+      type: 'deterministic',
+      command: '/bin/rm', // absolute path — basename `rm` is still denied
+      args: ['-f', join(projectRoot, 'sentinel')],
+      cwd: projectRoot,
+      on_failure: { max_iterations: 1 },
+    };
+
+    let agenticReached = false;
+    const result = await executePlaybook({
+      db,
+      playbook: singleDeterministicPlaybook(node),
+      playbookHash: 'hash-abs-denied',
+      initialContext: { taskId: 'T11802' },
+      dispatcher: {
+        async dispatch() {
+          agenticReached = true;
+          return { status: 'success', output: { bypassed: true } };
+        },
+      },
+      deterministicRunner: buildGuardedRunner(),
+      maxIterationsDefault: 1,
+    });
+
+    expect(agenticReached).toBe(false); // never fell back to the agentic path
+    expect(result.terminalStatus).toBe('exceeded_iteration_cap');
+    expect(result.errorContext ?? '').toMatch(/denylist|E_TOOL_GUARD_DENIED|"rm"/);
+  });
+});