@worca/app 1.0.0 → 1.1.1

package/src/core/claude-runner.mjs

@@ -36,12 +36,82 @@ import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { prepareModelEnv } from './model-env.mjs';
 import { classifyError, strongestClass } from './recoverable-error.mjs';
+import { explainUnspawnableClaude, resolveClaudeBin } from './preflight.mjs';
 import { writeFile, mkdir, appendFile, readFile, access } from 'node:fs/promises';
-import { constants as FS } from 'node:fs';
+import { constants as FS, mkdtempSync, writeFileSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
 
 const DEFAULT_BIN = process.env.WORCA_CLAUDE_BIN || process.env.ORCH_CLAUDE_BIN || 'claude';
 
+// Grace between the abort SIGTERM and the SIGKILL escalation. Claude Code shuts
+// down synchronously (fsync'd ~/.claude.json saves); a SIGKILL that lands inside
+// such a write strands ~/.claude.json.tmp.<pid>.<hex> (2026-08-30: 2099 files,
+// 4.4 GB, all from test runs under IO load). 5 s is generous on an idle disk
+// (SIGTERM exits in ~0.5 s) and only delays a stop when the child is wedged.
+export const DEFAULT_SIGKILL_GRACE_MS = 5000;
+export function sigkillGraceMs() {
+  const n = Number(process.env.WORCA_SIGKILL_GRACE_MS);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_SIGKILL_GRACE_MS;
+}
+
+/** What `--settings` carries, or null when there is nothing to carry (no hook
+ *  telemetry, no permission rules) — then the flag is omitted entirely. */
+export function buildSettingsPayload(permissionRules) {
+  const hook = buildHookSettings();
+  const hasRules = !!permissionRules && Object.values(permissionRules).some((a) => Array.isArray(a) && a.length);
+  // Present-but-malformed rules (e.g. `{deny: 'Bash(curl:*)'}`) make the object
+  // truthy while hasRules stays false, so the whole policy would drop out of
+  // argv silently. Say it once, then take the same no-rules path (fail-open,
+  // matching the guardrail-set read path) — the empty/absent cases ({}, {deny: []}, null)
+  // are normal and stay quiet.
+  if (!hasRules && permissionRules && typeof permissionRules === 'object'
+      && Object.values(permissionRules).some((a) => a != null && !Array.isArray(a))) {
+    console.warn('[worca] guardrails: permissionRules is malformed (deny/allow/ask must be arrays of strings) — ignoring it; this spawn carries NO permission rules');
+  }
+  if (!hook && !hasRules) return null;
+  const settings = {};
+  if (hook) settings.hooks = hook.hooks;
+  if (hasRules) settings.permissions = permissionRules;
+  return { hook: !!hook, settings };
+}
+
+/**
+ * Largest command line we hand to spawn() inline (GH #380). Windows caps the
+ * whole CreateProcess command line at 32,767 chars and Linux caps a single
+ * argument at 128 KiB, and a real task prompt (a 1000-line markdown plus the
+ * rendered channel artifacts) sails past both — `spawn ENAMETOOLONG` / E2BIG at
+ * the first node. Above this limit the prompt travels on stdin and the system
+ * prompt / settings as files (planClaudeInvocation); below it the argv is
+ * byte-identical to what it always was. The figure leaves ~12K of headroom
+ * under the Windows cap for the exe path, quoting, and flags this measure
+ * cannot see, and is deliberately platform-independent so the offload path is
+ * exercised (and testable) everywhere, not only on Windows.
+ *
+ * Inline JSON, or the path of a file holding that same JSON when the invocation
+ * is staged (GH #380 — the CLI accepts either).
+ */
+export const ARGV_INLINE_LIMIT = 20000;
+
+/** Conservative size of the command line spawn() would build: every argument
+ *  quoted and space-separated, after the binary. Over-counts slightly on
+ *  purpose (a prompt with embedded quotes grows under Windows escaping). */
+export function argvLength(bin, args) {
+  return String(bin || '').length + args.reduce((n, a) => n + String(a).length + 3, 0);
+}
+
+/** Log each npm-shim resolution once per process, not once per spawn. */
+const _resolveNoted = new Set();
+
+/** The spawn-failure Error for `bin`: the OS message, plus the Windows npm-shim
+ *  explanation when that is what actually went wrong (ENOENT on a bare name
+ *  whose only PATH hit is claude.cmd; EINVAL on an explicit .cmd). */
+function spawnFailure(bin, err, prefix) {
+  const hint = /ENOENT|EINVAL/.test(String(err && err.code || err && err.message || ''))
+    ? explainUnspawnableClaude(bin) : null;
+  return new Error(`${prefix}: ${err.message}${hint ? ` — ${hint}` : ''}`);
+}
+
 // Cap for the stderr detail embedded in a non-zero-exit Error message. The
 // audit trail and the UI error banner consume that message; an uncapped
 // stderrBuf (hundreds of KB of MCP/retry chatter) must not ride into them when
@@ -108,27 +178,15 @@ export function buildHookSettings() {
  * flags would be last-wins at the CLI, silently dropping one payload.
  * [] when there is nothing to say, so the baseline argv is byte-identical.
  * @param {{deny?:string[],allow?:string[],ask?:string[]}|null|undefined} permissionRules
+ * @param {string|null} [settingsFile] staged path (GH #380): `--settings <path>` carries the same JSON
  * @returns {string[]}
  */
-export function buildSettingsArgs(permissionRules) {
-  const hook = buildHookSettings();
-  const hasRules = !!permissionRules && Object.values(permissionRules).some((a) => Array.isArray(a) && a.length);
-  // Present-but-malformed rules (e.g. `{deny: 'Bash(curl:*)'}`) make the object
-  // truthy while hasRules stays false, so the whole policy would drop out of
-  // argv silently. Say it once, then take the same no-rules path (fail-open,
-  // matching the guardrail-set read path) — the empty/absent cases ({}, {deny: []}, null)
-  // are normal and stay quiet.
-  if (!hasRules && permissionRules && typeof permissionRules === 'object'
-      && Object.values(permissionRules).some((a) => a != null && !Array.isArray(a))) {
-    console.warn('[worca] guardrails: permissionRules is malformed (deny/allow/ask must be arrays of strings) — ignoring it; this spawn carries NO permission rules');
-  }
-  if (!hook && !hasRules) return [];
-  const settings = {};
-  if (hook) settings.hooks = hook.hooks;
-  if (hasRules) settings.permissions = permissionRules;
+export function buildSettingsArgs(permissionRules, settingsFile = null) {
+  const payload = buildSettingsPayload(permissionRules);
+  if (!payload) return [];
   const args = [];
-  if (hook) args.push('--include-hook-events');
-  args.push('--settings', JSON.stringify(settings));
+  if (payload.hook) args.push('--include-hook-events');
+  args.push('--settings', settingsFile || JSON.stringify(payload.settings));
   return args;
 }
 
@@ -185,7 +243,7 @@ export function buildSpawnEnv(envScrub, envAllowlist) {
  * passed through by the orchestrator (handled by caller mapping mock->env or
  * by passing systemPrompt/prompt markers; we also honor a `mock` field).
  */
-function mockEnabled(opts) {
+export function mockEnabled(opts) {
   if (opts && opts.mock) return true;
   const v = process.env.WORCA_MOCK ?? process.env.ORCH_MOCK;
   return !!v && v !== '0' && v.toLowerCase() !== 'false';
@@ -217,10 +275,23 @@ function mockEnabled(opts) {
  * @param {string[]} [o.envAllowlist]    guardrail: extra env var names to keep under scrub
  * @param {Record<string,string>} [o.modelEnv] per-model routing env (design §4.4), merged
  *   LAST over the spawn env (it survives scrub and wins collisions — explicit operator
- *   config outranks ambient-env hygiene); reserved keys are re-dropped here defensively
+ *   config outranks ambient-env hygiene); reserved keys are re-dropped here defensively.
+ *   An ANTHROPIC_MODEL key is the WIRE id (#374): it replaces `model` in the spawned
+ *   `--model` flag, while `model` (the catalog id) stays worca's handle everywhere else
  * @param {string[]} [o.workspaceWriteTargets] §8.10 MOCK-ONLY member checkouts the mock
  *   implementer writes into instead of `cwd` (empty/absent => today's cwd behavior).
  *   Never reaches argv: `runReal` ignores it by construction.
+ * @param {string[]} [o.tools]              --tools <list>: the built-in tool allowlist ([] ⇒ `--tools ""`,
+ *   no built-ins at all; MCP tools are unaffected). Absent ⇒ flag omitted (claude defaults).
+ * @param {boolean} [o.strictMcpConfig]     --strict-mcp-config: only --mcp-config servers load
+ * @param {string[]} [o.settingSources]     --setting-sources <list> (e.g. ['project'] drops user hooks/plugins/skills)
+ * @param {boolean} [o.disableSlashCommands] --disable-slash-commands
+ * @param {boolean} [o.includePartialMessages] --include-partial-messages (stream_event text deltas)
+ * @param {number} [o.maxTurns]             --max-turns <n> (positive safe integer; else omitted)
+ * @param {number|null} [o.maxBudgetUsd]    --max-budget-usd <n> (finite > 0; null/else omitted)
+ * @param {string} [o.appendSubagentSystemPrompt] --append-subagent-system-prompt <text> (Task children only)
+ *   All eight are Ask Worca sandbox options (ask-worca-design.md §6.3) and default-off.
+ * @param {number} [o.argvInlineLimit]     override ARGV_INLINE_LIMIT (GH #380; tests force the staged path)
  * @returns {Promise<{text:string, exitCode:number}>}
  */
 export async function runClaude(o = {}) {
@@ -247,6 +318,17 @@ export async function runClaude(o = {}) {
     modelEnv,
     workspaceWriteTargets,
     resumeSessionId,
+    // Ask Worca sandbox hardening (ask-worca-design.md §6.3/§6.8). All default-off:
+    // undefined here ⇒ nothing emitted ⇒ every legacy argv stays byte-identical.
+    tools,
+    strictMcpConfig,
+    settingSources,
+    disableSlashCommands,
+    includePartialMessages,
+    maxTurns,
+    maxBudgetUsd,
+    appendSubagentSystemPrompt,
+    argvInlineLimit,
     bin = DEFAULT_BIN,
   } = o;
 
@@ -261,7 +343,7 @@ export async function runClaude(o = {}) {
     // workspaceWriteTargets is the one option that is mock-ONLY (§8.10) and it must be
     // named HERE too, or the mock implementer never sees it (this call is a gate, not
     // a pass-through; test/spawn-args.test.mjs asserts the forwarding end to end).
-    return runMock({ cwd, systemPrompt, prompt, onEvent, signal, resumeSessionId, workspaceWriteTargets });
+    return runMock({ cwd, systemPrompt, prompt, onEvent, signal, resumeSessionId, workspaceWriteTargets, permissionMode });
   }
 
   return runReal({
@@ -282,6 +364,15 @@ export async function runClaude(o = {}) {
     envScrub,
     envAllowlist,
     modelEnv,
+    tools,
+    strictMcpConfig,
+    settingSources,
+    disableSlashCommands,
+    includePartialMessages,
+    maxTurns,
+    maxBudgetUsd,
+    appendSubagentSystemPrompt,
+    argvInlineLimit,
   });
 }
 
@@ -308,11 +399,23 @@ export async function runClaude(o = {}) {
 export function buildClaudeArgs({
   prompt, systemPrompt, permissionMode, model, effort, allowedTools, resumeSessionId,
   mcpConfigPath, mcpServerGrants, permissionRules,
-}) {
-  const args = ['-p', prompt, '--output-format', 'stream-json', '--verbose', '--permission-mode', permissionMode];
+  // Ask Worca hardening options (ask-worca-design.md §6.3). `tools` is renamed on the
+  // way in because the legacy body below already owns a local `tools` (the
+  // --allowedTools union).
+  tools: builtinTools, strictMcpConfig, settingSources, disableSlashCommands, includePartialMessages,
+  maxTurns, maxBudgetUsd, appendSubagentSystemPrompt,
+}, delivery = {}) {
+  // delivery (GH #380, set only by planClaudeInvocation's staged branch):
+  //   promptViaStdin   -> bare `-p`; the prompt is written to the child's stdin
+  //   systemPromptFile -> `--append-system-prompt-file <path>` instead of the text
+  //   settingsFile     -> `--settings <path>` instead of the inline JSON
+  const { promptViaStdin = false, systemPromptFile = null, settingsFile = null } = delivery;
+  const args = promptViaStdin ? ['-p'] : ['-p', prompt];
+  args.push('--output-format', 'stream-json', '--verbose', '--permission-mode', permissionMode);
   if (resumeSessionId) args.push('--resume', resumeSessionId);
   if (systemPrompt) {
-    args.push('--append-system-prompt', systemPrompt);
+    if (systemPromptFile) args.push('--append-system-prompt-file', systemPromptFile);
+    else args.push('--append-system-prompt', systemPrompt);
   }
   if (model) {
     args.push('--model', model);
@@ -323,7 +426,7 @@ export function buildClaudeArgs({
   // SINGLE inline JSON (two --settings flags would be last-wins at the CLI). [] when
   // there is neither, so the baseline argv is unchanged; a CLI that rejects these
   // flags would only ever fail when the operator opted in.
-  for (const a of buildSettingsArgs(permissionRules)) args.push(a);
+  for (const a of buildSettingsArgs(permissionRules, settingsFile)) args.push(a);
   if (mcpConfigPath) args.push('--mcp-config', mcpConfigPath);
   const tools = Array.isArray(allowedTools) ? allowedTools.slice() : [];
   for (const s of (Array.isArray(mcpServerGrants) ? mcpServerGrants : [])) {
@@ -332,43 +435,181 @@ export function buildClaudeArgs({
   if (tools.length) {
     args.push('--allowedTools', tools.join(','));
   }
+  // ── Ask Worca hardening flags (ask-worca-design.md §6.3 / §6.8) ──────────────
+  // Every one is default-off: absent / false / invalid ⇒ NOTHING is emitted, so
+  // every legacy argv stays byte-identical (test/spawn-args.test.mjs). Appended
+  // AFTER the legacy block so the baseline prefix never moves. Probed on 2.1.239:
+  // `--tools ""` = no built-in tools (MCP tools survive); the hidden `--max-turns`
+  // and `--append-subagent-system-prompt` are accepted and enforced.
+  // Filter to usable names FIRST, then decide: testing the RAW list while emitting
+  // the FILTERED join made `settingSources: [1]` emit `--setting-sources ""` (where
+  // `[]` emits nothing) and `['Read', '']` emit a trailing comma.
+  const names = (v) => (Array.isArray(v) ? v.filter((s) => typeof s === 'string' && s) : []);
+  // --tools is the one list whose empty value is meaningful (`--tools ""` = no
+  // built-in tools at all, §6.3), so the ARRAY decides whether the flag is emitted.
+  if (Array.isArray(builtinTools)) {
+    args.push('--tools', names(builtinTools).join(','));
+  }
+  if (strictMcpConfig === true) args.push('--strict-mcp-config');
+  const sources = names(settingSources);
+  if (sources.length) {
+    args.push('--setting-sources', sources.join(','));
+  }
+  if (disableSlashCommands === true) args.push('--disable-slash-commands');
+  if (includePartialMessages === true) args.push('--include-partial-messages');
+  if (Number.isSafeInteger(maxTurns) && maxTurns > 0) args.push('--max-turns', String(maxTurns));
+  if (typeof maxBudgetUsd === 'number' && Number.isFinite(maxBudgetUsd) && maxBudgetUsd > 0) {
+    args.push('--max-budget-usd', String(maxBudgetUsd));
+  }
+  if (typeof appendSubagentSystemPrompt === 'string' && appendSubagentSystemPrompt) {
+    args.push('--append-subagent-system-prompt', appendSubagentSystemPrompt);
+  }
   return args;
 }
 
-function runReal({ cwd, systemPrompt, prompt, allowedTools, permissionMode, model, effort, onEvent, signal, bin, resumeSessionId, mcpConfigPath, mcpServerGrants, permissionRules, envScrub, envAllowlist, modelEnv }) {
-  return new Promise((resolveP, rejectP) => {
-    const args = buildClaudeArgs({
-      prompt, systemPrompt, permissionMode, model, effort, allowedTools, resumeSessionId,
-      mcpConfigPath, mcpServerGrants, permissionRules,
-    });
+/**
+ * Decide how ONE invocation reaches the CLI (GH #380). Pure: no I/O.
+ *  - inline (the common case): `args` is exactly buildClaudeArgs(opts); `stdin`
+ *    null; `files` empty.
+ *  - staged (argv over `limit`): the prompt goes on stdin (`-p` reads it — the
+ *    model sees the exact text, unlike a "read this file" instruction), the
+ *    system prompt and the settings JSON become files under `dir`, and no
+ *    argument carries free text any more, so the argv is short by construction.
+ * @param {object} opts  the buildClaudeArgs options
+ * @param {{bin?:string, dir?:string|(() => string), limit?:number}} [o]  `dir` may be a
+ *   factory, called only when staging is actually needed (so the caller creates
+ *   a temp dir exactly when one will be used)
+ * @returns {{args:string[], stdin:string|null, files:{path:string,content:string}[], staged:boolean, inlineLength:number}}
+ */
+export function planClaudeInvocation(opts, { bin = DEFAULT_BIN, dir = null, limit = ARGV_INLINE_LIMIT } = {}) {
+  const inline = buildClaudeArgs(opts);
+  const inlineLength = argvLength(bin, inline);
+  if (inlineLength <= limit) return { args: inline, stdin: null, files: [], staged: false, inlineLength };
+  if (!dir) throw new Error('planClaudeInvocation: a staging dir is required when the argv is over the limit');
+  if (typeof dir === 'function') dir = dir();
+  const files = [];
+  const prompt = typeof opts.prompt === 'string' ? opts.prompt : '';
+  const promptViaStdin = prompt.length > 0;             // an empty prompt stays `-p ''` — nothing to pipe
+  let systemPromptFile = null;
+  if (opts.systemPrompt) {
+    systemPromptFile = join(dir, 'system-prompt.md');
+    files.push({ path: systemPromptFile, content: opts.systemPrompt });
+  }
+  let settingsFile = null;
+  const payload = buildSettingsPayload(opts.permissionRules);
+  if (payload) {
+    settingsFile = join(dir, 'settings.json');
+    files.push({ path: settingsFile, content: JSON.stringify(payload.settings) });
+  }
+  const args = buildClaudeArgs(opts, { promptViaStdin, systemPromptFile, settingsFile });
+  return { args, stdin: promptViaStdin ? prompt : null, files, staged: true, inlineLength };
+}
 
-    // undefined when the guardrail is off, and the spread then adds NO `env` key —
-    // spawn inherits process.env exactly as it did before guardrails existed.
-    const guardrailEnv = buildSpawnEnv(envScrub, envAllowlist);
+/** planClaudeInvocation + the I/O: a private temp dir is created and the files
+ *  written ONLY on the staged branch (`dir` is null otherwise, so the caller has
+ *  nothing to clean up). Synchronous on purpose — a few hundred KB once per
+ *  spawn, and it keeps the spawn sequence in runReal linear. */
+export function stageClaudeInvocation(opts, { bin = DEFAULT_BIN, limit = ARGV_INLINE_LIMIT } = {}) {
+  let dir = null;
+  const plan = planClaudeInvocation(opts, { bin, limit, dir: () => (dir = mkdtempSync(join(tmpdir(), 'worca-claude-'))) });
+  for (const file of plan.files) writeFileSync(file.path, file.content, 'utf8');
+  return { ...plan, dir };
+}
 
-    // Per-model routing env (design §4.4) merges LAST: it survives scrub and
-    // wins collisions (explicit operator config outranks ambient-env hygiene),
-    // except reserved keys, which are re-dropped here defensively — the write
-    // path already rejects them, so a drop means a hand-edited settings file.
-    // With no modelEnv (or nothing surviving the filter) the spawn env is
-    // byte-identical to the pre-feature behavior, including the undefined
-    // -> inherit-process.env case.
-    let spawnEnv = guardrailEnv;
+function runReal({ cwd, systemPrompt, prompt, allowedTools, permissionMode, model, effort, onEvent, signal, bin, resumeSessionId, mcpConfigPath, mcpServerGrants, permissionRules, envScrub, envAllowlist, modelEnv, tools, strictMcpConfig, settingSources, disableSlashCommands, includePartialMessages, maxTurns, maxBudgetUsd, appendSubagentSystemPrompt, argvInlineLimit }) {
+  return new Promise((resolveP, rejectP) => {
+    // Per-model routing env (design §4.4), prepared BEFORE argv: reserved keys
+    // are re-dropped here defensively — the write path already rejects them, so
+    // a drop means a hand-edited settings file — and the surviving map is also
+    // where the wire id (below) is read from.
+    let safeModelEnv = null;
+    let wireModelDropped = false;
     if (modelEnv && Object.keys(modelEnv).length) {
       const { env: safe, dropped } = prepareModelEnv(modelEnv);
       for (const k of dropped) {
         console.warn(`[worca] modelEnv: dropping reserved/invalid key ${JSON.stringify(k)}`);
       }
-      if (Object.keys(safe).length) spawnEnv = { ...(guardrailEnv ?? process.env), ...safe };
+      // A configured wire id that didn't survive (unresolvable ${VAR}, empty, or
+      // whitespace-only) fell into `dropped`: we silently fall back to the catalog
+      // id below, so warn specifically — the generic drop line above doesn't say
+      // the argv model changed, and the wire-model line never fires (ids match).
+      wireModelDropped = 'ANTHROPIC_MODEL' in modelEnv && dropped.includes('ANTHROPIC_MODEL');
+      if (Object.keys(safe).length) safeModelEnv = safe;
+    }
+
+    // Wire id (#374): ANTHROPIC_MODEL in the resolved model env names the id the
+    // ENDPOINT should see; the catalog id stays worca's handle (config refs, cost
+    // flags). Passed as an explicit --model — self-documenting in logs and immune
+    // to CLI flag/env precedence — so the env var alone would otherwise be dead.
+    const wireModel = safeModelEnv?.ANTHROPIC_MODEL || model;
+    if (wireModelDropped && wireModel === model) {
+      console.warn(`[worca] model ${JSON.stringify(model ?? '')}: configured wire model was dropped (unresolved/empty) — using the catalog id`);
+    } else if (wireModel !== model) {
+      console.warn(`[worca] model ${JSON.stringify(model ?? '')}: wire model ${JSON.stringify(wireModel)}`);
     }
 
+    // Windows + npm-installed Claude Code: the bare name is a .cmd shim Node
+    // cannot spawn; resolveClaudeBin swaps in the package's native claude.exe.
+    // Everywhere else this is `bin` unchanged. Resolved BEFORE the argv plan so
+    // the command-line measure below counts the path that is actually spawned.
+    const resolved = resolveClaudeBin(bin);
+    if (resolved.note && !_resolveNoted.has(resolved.bin)) {
+      _resolveNoted.add(resolved.bin);
+      console.warn(`[worca] ${resolved.note}`);
+    }
+
+    // GH #380: inline argv when it fits, else prompt on stdin + files (see
+    // ARGV_INLINE_LIMIT). The staging dir, when any, is removed on every
+    // terminal path below (finish) and on a failed spawn.
+    const limit = Number.isFinite(argvInlineLimit) && argvInlineLimit > 0 ? argvInlineLimit : ARGV_INLINE_LIMIT;
+    let plan;
+    try {
+      plan = stageClaudeInvocation({
+        prompt, systemPrompt, permissionMode, model: wireModel, effort, allowedTools, resumeSessionId,
+        mcpConfigPath, mcpServerGrants, permissionRules,
+        tools, strictMcpConfig, settingSources, disableSlashCommands, includePartialMessages,
+        maxTurns, maxBudgetUsd, appendSubagentSystemPrompt,
+      }, { bin: resolved.bin, limit });
+    } catch (err) {
+      rejectP(new Error(`Failed to stage the claude prompt files: ${err.message}`));
+      return;
+    }
+    const { args } = plan;
+    const cleanupStaged = () => {
+      if (!plan.dir) return;
+      try { rmSync(plan.dir, { recursive: true, force: true }); } catch { /* best effort */ }
+    };
+    if (plan.staged) {
+      console.warn(`[worca] claude argv would be ${plan.inlineLength} chars (limit ${limit}): prompt on stdin, system prompt/settings as files`);
+    }
+
+    // undefined when the guardrail is off, and the spread then adds NO `env` key —
+    // spawn inherits process.env exactly as it did before guardrails existed.
+    const guardrailEnv = buildSpawnEnv(envScrub, envAllowlist);
+
+    // Model env merges LAST: it survives scrub and wins collisions (explicit
+    // operator config outranks ambient-env hygiene). With no modelEnv (or
+    // nothing surviving the filter) the spawn env is byte-identical to the
+    // pre-feature behavior, including the undefined -> inherit-process.env case.
+    let spawnEnv = guardrailEnv;
+    if (safeModelEnv) spawnEnv = { ...(guardrailEnv ?? process.env), ...safeModelEnv };
+
     let child;
     try {
-      child = spawn(bin, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], ...(spawnEnv ? { env: spawnEnv } : {}) });
+      child = spawn(resolved.bin, args, {
+        cwd, stdio: [plan.stdin != null ? 'pipe' : 'ignore', 'pipe', 'pipe'], ...(spawnEnv ? { env: spawnEnv } : {}),
+      });
     } catch (err) {
-      rejectP(new Error(`Failed to spawn ${bin}: ${err.message}`));
+      cleanupStaged();
+      rejectP(spawnFailure(bin, err, `Failed to spawn ${bin}`));
       return;
     }
+    if (plan.stdin != null) {
+      // A child that dies before draining stdin (bad flag, ENOENT surfaced
+      // late) raises EPIPE here; the 'error'/'close' handlers own the real cause.
+      child.stdin.on('error', () => {});
+      child.stdin.end(plan.stdin, 'utf8');
+    }
 
     let resultText = '';
     let assistantText = '';
@@ -396,7 +637,7 @@ function runReal({ cwd, systemPrompt, prompt, allowedTools, permissionMode, mode
         } catch {
           /* ignore */
         }
-      }, 1500).unref?.();
+      }, sigkillGraceMs()).unref?.();
     };
     if (signal) {
       if (signal.aborted) onAbort();
@@ -407,6 +648,7 @@ function runReal({ cwd, systemPrompt, prompt, allowedTools, permissionMode, mode
       if (settled) return;
       settled = true;
       if (signal) signal.removeEventListener?.('abort', onAbort);
+      cleanupStaged();
       fn(arg);
     };
 
@@ -486,7 +728,7 @@ function runReal({ cwd, systemPrompt, prompt, allowedTools, permissionMode, mode
     });
 
     child.on('error', (err) => {
-      finish(rejectP, new Error(`${bin} error: ${err.message}`));
+      finish(rejectP, spawnFailure(bin, err, `${bin} error`));
     });
 
     child.on('close', (code) => {
@@ -611,6 +853,24 @@ async function emitLog(onEvent, text) {
   await new Promise((r) => setTimeout(r, 0));
 }
 
+/**
+ * The roles the offline mock runner can SERVE — one per arm of the role switch
+ * below (the `ask` arm is the Ask-Worca assistant, not a writer role). Exported
+ * because three consumers need the vocabulary and none of them may hard-code it:
+ * meta v2 validation (an unknown `mockRole` is a warning + drop), GET /api/agents
+ * (the Agents view's role picker) and the graph executor's mock-role chain.
+ * test/mock-writer-roles.test.mjs parses the switch and pins the lockstep.
+ */
+export const MOCK_WRITER_ROLES = new Set([
+  'clarify', 'planner-plan', 'refiner', 'decomposer', 'implementer', 'reviewer', 'plan-review',
+  'workspace-scan', 'agent-gen', 'workspace-reviewer', 'manual-tests-checklist', 'manual-web-ui-testing',
+  'generic-producer', 'generic-verifier',
+]);
+
+/** Named so the executor's mock-role chain and the switch cannot drift apart. */
+export const MOCK_ROLE_CLARIFY = 'clarify';
+export const MOCK_ROLE_DECOMPOSER = 'decomposer';
+
 /**
  * The mock-fan-out roles (mirror the orchestrator's FANOUT_ELIGIBLE intent): the
  * roles whose real runs may spawn sub-agents. Keyed by the MOCK_ROLE strings.
@@ -675,6 +935,109 @@ async function emitMockSubAgents(role, onEvent, signal) {
   }
 }
 
+// ── Ask Worca mock role (ask-worca-design.md §6.7) ───────────────────────────
+
+/** Emit a raw stream-json frame through the SAME envelope runReal uses (the rl 'line' handler above). */
+function emitRaw(onEvent, raw) {
+  const cost = extractResultCost(raw);
+  const text = extractText(raw);
+  safeEmit(onEvent, { type: raw.type, raw, text: text || undefined, ...(cost != null ? { costUsd: cost } : {}) });
+}
+
+const ASK_CONTEXT_BLOCK_RE = /\[worca context\][\s\S]*?\[\/worca context\]\s*/;
+
+/**
+ * The offline Ask Worca assistant: frames in the shapes probed on claude 2.1.239
+ * (system/init → message_start → text deltas → assistant blocks → tool_use /
+ * tool_result pairs → message_delta → result), chosen from the USER text so
+ * tests control the scenario. Never touches the filesystem, never reads prompt
+ * markers, never spawns the MCP child. The limit / failure scenarios emit their
+ * `result` frame and then REJECT exactly like the real CLI (exit 1, empty stderr).
+ */
+async function mockAsk({ markers, prompt, cwd, onEvent, signal, resumeSessionId }) {
+  const userText = String(prompt ?? '').replace(ASK_CONTEXT_BLOCK_RE, '');
+  let card = {};
+  try { card = markers.MOCK_ASK_CARD ? JSON.parse(markers.MOCK_ASK_CARD) : {}; } catch { card = {}; }
+  if (!card || typeof card !== 'object' || Array.isArray(card)) card = {};
+  const fail = /\bMOCK_FAIL\b/.test(userText);
+  const maxTurns = /\bMOCK_MAX_TURNS\b/.test(userText);
+  const maxBudget = /\bMOCK_MAX_BUDGET\b/.test(userText);
+  const slow = /\bMOCK_SLOW\b/.test(userText);
+  const agents = /\bagents?\b/i.test(userText);
+  const propose = /\b(propose|start|run)\b/i.test(userText);
+
+  const SID = resumeSessionId || 'mock-session-ask-1';
+  const USAGE = { input_tokens: 10, output_tokens: 20, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 };
+  const firstLine = userText.split(/\r?\n/).map((l) => l.trim()).find(Boolean) || '';
+  const ANSWER = `[mock] ${firstLine.slice(0, 200)}`;
+  const init = { type: 'system', subtype: 'init', session_id: SID, cwd, model: 'mock', permissionMode: 'dontAsk',
+    tools: ['Task', 'mcp__worca__list_runs', 'mcp__worca__get_run', 'mcp__worca__propose_run'],
+    mcp_servers: [{ name: 'worca', status: 'connected' }], plugins: [], skills: [], slash_commands: [], agents: [], uuid: 'mock-uuid-init' };
+  const mstart = (id) => ({ type: 'stream_event', event: { type: 'message_start', message: { id, model: 'mock', role: 'assistant', content: [], usage: USAGE } }, parent_tool_use_id: null, session_id: SID });
+  const delta = (t) => ({ type: 'stream_event', event: { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: t } }, parent_tool_use_id: null, session_id: SID });
+  const mdelta = { type: 'stream_event', event: { type: 'message_delta', delta: { stop_reason: 'end_turn' }, usage: USAGE }, parent_tool_use_id: null, session_id: SID };
+  const atext = (id, t) => ({ type: 'assistant', message: { id, model: 'mock', role: 'assistant', content: [{ type: 'text', text: t }], usage: USAGE }, parent_tool_use_id: null, session_id: SID });
+  const atool = (id, toolId, name, input, ptu = null) => ({ type: 'assistant', message: { id, model: 'mock', role: 'assistant', content: [{ type: 'tool_use', id: toolId, name, input, caller: { type: 'direct' } }], usage: USAGE }, parent_tool_use_id: ptu, session_id: SID });
+  const uresult = (toolId, text, ptu = null, extra = {}) => ({ type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: toolId, content: [{ type: 'text', text }] }] }, parent_tool_use_id: ptu, session_id: SID, ...extra });
+  const result = (over = {}) => ({ type: 'result', subtype: 'success', is_error: false, duration_ms: 10, duration_api_ms: 8, num_turns: 1, session_id: SID, total_cost_usd: 0,
+    usage: USAGE, modelUsage: {}, permission_denials: [], terminal_reason: 'completed', result: ANSWER, ...over });
+  const MSG1 = 'msg_mock_ask_1';
+  const MSG2 = 'msg_mock_ask_2';
+
+  const frames = [init, mstart(MSG1)];
+  if (fail) {
+    frames.push(result({ subtype: 'error_during_execution', is_error: true, errors: ['mock failure'], terminal_reason: 'api_error', result: 'mock failure', num_turns: 0 }));
+  } else if (maxTurns || maxBudget) {
+    frames.push(delta('[mock] '), delta('partial'), atext(MSG1, '[mock] partial'),
+      atool(MSG1, 'toolu_mock_1', 'mcp__worca__list_runs', {}), uresult('toolu_mock_1', '[]'));
+    frames.push(maxTurns
+      ? result({ subtype: 'error_max_turns', is_error: true, errors: ['Reached maximum number of turns (1)'], terminal_reason: 'max_turns', num_turns: 2, stop_reason: 'tool_use', result: undefined })
+      : result({ subtype: 'error_max_budget_usd', is_error: true, errors: ['Reached maximum budget ($0.0001)'], terminal_reason: 'budget_exhausted', result: undefined }));
+  } else {
+    let answerMsg = MSG1;
+    if (agents) {
+      frames.push(
+        atool(MSG1, 'toolu_mock_task', 'Agent', { description: 'count runs', subagent_type: 'general-purpose', prompt: 'count the runs' }),
+        atool('msg_mock_child_1', 'toolu_mock_child_1', 'mcp__worca__list_runs', {}, 'toolu_mock_task'),
+        uresult('toolu_mock_child_1', '[]', 'toolu_mock_task'),
+        uresult('toolu_mock_task', 'count: 0', null, { tool_use_result: {
+          status: 'completed', agentId: 'mock-agent-1', agentType: 'general-purpose', content: [{ type: 'text', text: 'count: 0' }],
+          resolvedModel: 'mock-haiku', totalDurationMs: 10, totalTokens: 1234, totalToolUseCount: 1,
+          usage: { input_tokens: 1000, output_tokens: 234, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+        } }),
+      );
+      answerMsg = MSG2;
+    }
+    if (propose) {
+      frames.push(delta('[mock] '), delta('preparing '), delta('a run'), atext(MSG1, 'Preparing a run card.'),
+        atool(MSG1, 'toolu_mock_propose', 'mcp__worca__propose_run', card), uresult('toolu_mock_propose', JSON.stringify({ ok: true })));
+      answerMsg = MSG2;
+    }
+    if (answerMsg !== MSG1) frames.push(mstart(answerMsg));
+    frames.push(delta('[mock] '), delta(firstLine.slice(0, 200)), atext(answerMsg, ANSWER), mdelta);
+    frames.push(result(agents
+      ? { modelUsage: { 'mock-haiku': { inputTokens: 1000, outputTokens: 234, cacheReadInputTokens: 0, cacheCreationInputTokens: 0, costUSD: 0, canonicalModel: 'mock-haiku' } } }
+      : {}));
+  }
+
+  safeEmit(onEvent, { type: 'session', sessionId: SID });
+  for (const f of frames) {
+    abortIfNeeded(signal);
+    emitRaw(onEvent, f);
+    await new Promise((r) => setTimeout(r, slow ? 300 : 0));
+  }
+  abortIfNeeded(signal);
+  if (fail || maxTurns || maxBudget) {
+    // Probed on 2.1.239: these subtypes exit 1 with EMPTY stderr, so runReal rejects with the
+    // stdout `result` text (MOCK_FAIL) or 'no stderr' (the limits). turn.mjs (P2) reads the
+    // reducer's resultSubtype before classifying the rejection.
+    const err = new Error(`claude exited with code 1: ${fail ? 'mock failure' : 'no stderr'}`);
+    err.errorClass = null;
+    throw err;
+  }
+  return { text: ANSWER, exitCode: 0 };
+}
+
 function abortIfNeeded(signal) {
   if (signal?.aborted) {
     const err = new Error('aborted');
@@ -686,8 +1049,20 @@ function abortIfNeeded(signal) {
 /**
  * Offline mock: emits a few log lines and performs role-appropriate writes.
  */
-async function runMock({ cwd, systemPrompt, prompt, onEvent, signal, resumeSessionId, workspaceWriteTargets }) {
+async function runMock({ cwd, systemPrompt, prompt, onEvent, signal, resumeSessionId, workspaceWriteTargets, permissionMode }) {
   abortIfNeeded(signal);
+  // Ask Worca mock role (ask-worca-design.md §6.7): detected from the SYSTEM PROMPT
+  // ONLY and dispatched before any prompt-sourced marker is honoured — a chat
+  // message containing `MOCK_ASK: /x.json` (or any MOCK_* line) must never reach
+  // the MOCK_ASK file-write arm below, and the user text can never pick the role.
+  // `dontAsk` is the ask recipe's permission mode and has no legacy caller
+  // (spawn.mjs:20), so it takes the ask arm markers or not: a P2 turn that forgot
+  // `turn.mock` must not fall through to parseMarkers(prompt)/inferRole, where the
+  // chat text alone picks a role that writes to the scratch cwd.
+  const sysMarkers = parseMarkers('', systemPrompt);
+  if (sysMarkers.MOCK_ROLE === 'ask' || permissionMode === 'dontAsk') {
+    return mockAsk({ markers: sysMarkers, prompt, cwd, onEvent, signal, resumeSessionId });
+  }
   const m = parseMarkers(prompt, systemPrompt);
   const role = m.MOCK_ROLE || inferRole(prompt, systemPrompt);
   const cycle = Number(m.MOCK_CYCLE || '1') || 1;
@@ -704,7 +1079,7 @@ async function runMock({ cwd, systemPrompt, prompt, onEvent, signal, resumeSessi
   // Ask-then-resume (spec 2026-07-11): asking replaces the role side effects
   // for this invocation; the orchestrator gates the user and resumes. The
   // session event above already fired, so the resume has a session id.
-  if (m.MOCK_ASK) {
+  if (m.MOCK_ASK && permissionMode !== 'dontAsk') {   // belt and braces: dontAsk already took the ask arm above
     await ensureDir(m.MOCK_ASK);
     await writeFile(m.MOCK_ASK, JSON.stringify({
       questions: [{ id: 'q1', question: `Mock question from ${role}?`, options: ['Option A', 'Option B'], allowFreeText: true }],
@@ -717,7 +1092,7 @@ async function runMock({ cwd, systemPrompt, prompt, onEvent, signal, resumeSessi
 
   let text = `[mock] role ${role} complete`;
   switch (role) {
-    case 'clarify':
+    case MOCK_ROLE_CLARIFY:
       text = await mockClarify(m, cycle, onEvent);
       break;
     case 'planner-plan':
@@ -726,7 +1101,7 @@ async function runMock({ cwd, systemPrompt, prompt, onEvent, signal, resumeSessi
     case 'refiner':
       text = await mockRefiner(m, cycle, onEvent);
       break;
-    case 'decomposer':
+    case MOCK_ROLE_DECOMPOSER:
       text = await mockDecomposer(m, onEvent);
       break;
     case 'implementer':
@@ -1210,13 +1585,15 @@ async function mockAgentGen(m, onEvent) {
     ? words[0] + words.slice(1).map((w) => w[0].toUpperCase() + w.slice(1)).join('')
     : 'customAgent';
   const meta = {
-    key, displayName: name, description: `mock-generated agent for ${name}`,
-    color: 'amber', runnerType: 'producer', loopSource: false, fanOut: false,
-    asksQuestions: true, questionsLocked: false, questionsDefault: false,
-    consumes: ['plan'], optionalConsumes: [], produces: ['review'], connectsTo: '*', order: 99,
+    metaVersion: 2, key, displayName: name, description: `mock-generated agent for ${name}`,
+    color: 'amber', runnerType: 'producer', domain: 'general', fanOut: false,
+    asksQuestions: true, questionsLocked: false, questionsDefault: false, order: 99,
+    inputs: [{ id: 'plan', type: 'md', label: 'Plan' }],
+    outputs: [{ id: 'review', type: 'md', filename: 'review-{cycle}.md' }],
   };
   if (m.MOCK_OUT) {
-    const md = `# Agent: ${name}\n\nYou are ${name} (deterministic mock body).\n\n## Inputs\n- the plan\n\n## Outputs\n- a review markdown\n`;
+    const md = `# Agent: ${name}\n\nYou are ${name} (deterministic mock body).\n\n`
+      + '## Ports\n\n- `plan` (in, md) — the plan to review.\n- `review` (out, md) — the review this agent writes.\n';
     await ensureDir(m.MOCK_OUT);
     await writeFile(m.MOCK_OUT, md, 'utf8');
     safeEmit(onEvent, { type: 'tool_use', text: `wrote ${m.MOCK_OUT}`, raw: { mock: true, file: m.MOCK_OUT } });