@worca/app 1.2.0 → 1.3.0-rc.2

package/src/core/auto/proposal.mjs

@@ -0,0 +1,132 @@
+// The `workflow` question payload (spec §5.3/§5.4) and the sanitiser for its
+// answer. Pure: the orchestrator hands in the template (new or matched), the
+// per-node tunables and the registry slice, and gets back exactly what the CLI
+// and the browser render.
+import { buildGraphManifest } from '../../shared/graph/manifest.mjs';
+import { cleanText } from '../../shared/graph/assemble.mjs';
+import { slugify } from '../artifacts.mjs';
+import { GRAPH_DEFAULT_WORKFLOW, AUTO_WORKFLOW_ID, MEMORY_DEFRAG_WORKFLOW_ID } from '../workflows.mjs';
+
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+
+/** Tunables keyed by assembled node ids -> keyed by the matched row's node ids. */
+export function remapTunables(tunables, nodeMap) {
+  const out = {};
+  for (const [id, sel] of Object.entries(tunables || {})) {
+    const to = nodeMap?.get?.(id);
+    if (to) out[to] = { ...sel };
+  }
+  return out;
+}
+
+/**
+ * @param {{round:number, shape:object, template:object, match:{id:string,name:string}|null,
+ *          tunables:Record<string,object>, registry:Record<string,object>,
+ *          models:Array<{id:string,label?:string,efforts?:string[],hidden?:boolean}>, warnings?:Array, costUsd?:number,
+ *          fingerprint?:string, ignoredProjectOverrides?:boolean}} o
+ */
+export function buildProposal({ round, shape, template, match = null, tunables = {}, registry = {}, models = [], warnings = [], costUsd = 0, fingerprint = '', ignoredProjectOverrides = false }) {
+  const name = shape?.name || template?.name || 'Auto workflow';
+  const agentsByKey = {};
+  for (const n of template.nodes || []) if (n.kind === 'agent' && registry[n.key]) agentsByKey[n.key] = registry[n.key];
+  // B1 (2026-09-07 review): paint what resolveGraph will RUN (workflows.mjs:664) — an overlay
+  // model without an effort suppresses the row's authored effort, so a matched twin's "high"
+  // must not be shown next to a classifier-picked model that carries none. The manifest (the
+  // graph's band chips, manifest.mjs:145) and the table below read the SAME effective pair:
+  // an explicit `effort: ''` overlay is what makes the manifest agree.
+  const nodes = {};
+  const overlays = {};
+  for (const n of template.nodes || []) {
+    if (n.kind !== 'agent') continue;
+    const meta = registry[n.key] || {};
+    const cfg = n.config || {};
+    const t = tunables[n.id] || {};
+    const effort = t.effort ?? (t.model ? '' : (cfg.effort ?? ''));
+    overlays[n.id] = t.model && t.effort === undefined ? { ...t, effort: '' } : { ...t };
+    const asks = !!meta.asksQuestions;
+    nodes[n.id] = {
+      key: n.key,
+      label: meta.displayName || n.key,
+      model: t.model ?? cfg.model ?? '',
+      effort,
+      fanOut: !!(t.fanOut ?? cfg.fanOut ?? meta.fanOut ?? false),
+      askQuestions: asks ? (meta.questionsLocked ? !!meta.questionsDefault : !!(t.askQuestions ?? cfg.askQuestions ?? meta.questionsDefault ?? false)) : false,
+      asksQuestions: asks,
+      questionsLocked: asks && !!meta.questionsLocked,
+      canFanOut: !!meta.fanOut,
+    };
+  }
+  const manifest = buildGraphManifest({ ...template, id: match ? match.id : AUTO_WORKFLOW_ID, name }, agentsByKey, { overlays: { nodes: overlays } });
+  // The DISPATCH order of the AGENT nodes (rank, then launch order) — the manifest
+  // already computes it for the run monitor; a reused composer row's graph.nodes order
+  // is arbitrary. The steps cells bucket EVERY node — the Task card, End and the gates
+  // ride along with `key: null` — so keep only the agent cells.
+  const order = (manifest.steps || [])
+    .filter((s) => s.kind === 'agents')
+    .flatMap((s) => s.nodes.filter((n) => n.key).map((n) => n.id));
+  return {
+    round,
+    name,
+    reasoning: shape?.reasoning || '',
+    taskKind: shape?.taskKind || 'prompt',
+    size: shape?.size || 'medium',
+    signals: Array.isArray(shape?.signals) ? [...shape.signals] : [],
+    warnings: (warnings || []).map((w) => (typeof w === 'string' ? w : w.message)).filter(Boolean),
+    match: match ? { id: match.id, name: match.name } : null,
+    manifest,
+    order,
+    nodes,
+    models: models.filter((m) => m && !m.hidden).map((m) => ({ id: m.id, label: m.label || m.id, efforts: [...(m.efforts || [])] })),
+    costUsd: Number.isFinite(costUsd) ? costUsd : 0,
+    fingerprint: typeof fingerprint === 'string' ? fingerprint : '',
+    ignoredProjectOverrides: !!ignoredProjectOverrides,
+  };
+}
+
+/**
+ * @returns {{decision:'accept',name:string,nodes:object}|{decision:'revise',text:string}|{decision:'cancel'}|null}
+ */
+export function sanitizeProposalAnswer(payload, { proposal, models = [], registry = {} }) {
+  if (!isObject(payload)) return null;
+  const d = payload.decision;
+  if (d === 'cancel') return { decision: 'cancel' };
+  if (d === 'revise') {
+    const text = typeof payload.text === 'string' ? payload.text.trim().slice(0, 4096) : '';
+    return text ? { decision: 'revise', text } : null;
+  }
+  if (d !== 'accept') return null;
+  const name = cleanText(payload.name, 60) || proposal.name;
+  const byId = new Map(models.map((m) => [String(m.id).toLowerCase(), m]));   // the FULL catalog: a hidden id still resolves
+  const nodes = {};
+  for (const [nodeId, sel] of Object.entries(isObject(payload.nodes) ? payload.nodes : {})) {
+    const known = proposal.nodes?.[nodeId];
+    if (!known || !isObject(sel)) continue;
+    const meta = registry[known.key] || {};
+    const out = {};
+    if (typeof sel.model === 'string') {
+      const m = byId.get(sel.model.trim().toLowerCase());
+      if (m) out.model = m.id;
+      // '' clears the model AND the effort: resolveGraph keeps a row's authored effort
+      // when the overlay's model is falsy, which would leave an effort with no model.
+      else if (sel.model.trim() === '') { out.model = ''; out.effort = ''; }
+    }
+    if (typeof sel.effort === 'string') {
+      const mid = out.model !== undefined ? out.model : known.model;
+      const m = mid ? byId.get(String(mid).toLowerCase()) : null;
+      if (m && (m.efforts || []).includes(sel.effort)) out.effort = sel.effort;
+    }
+    if (typeof sel.fanOut === 'boolean' && meta.fanOut) out.fanOut = sel.fanOut;
+    if (typeof sel.askQuestions === 'boolean' && meta.asksQuestions && !meta.questionsLocked) out.askQuestions = sel.askQuestions;
+    if (Object.keys(out).length) nodes[nodeId] = out;
+  }
+  return { decision: 'accept', name, nodes };
+}
+
+/** `wf_<slug>` that no row owns; reserved / empty slugs become wf_auto-workflow. */
+export async function mintAutoWorkflowId(name, exists) {
+  let stem = `wf_${slugify(name)}`;
+  if (stem === GRAPH_DEFAULT_WORKFLOW.id || stem === AUTO_WORKFLOW_ID || stem === MEMORY_DEFRAG_WORKFLOW_ID || stem === 'wf_untitled') stem = 'wf_auto-workflow';
+  let id = stem;
+  for (let n = 2; await exists(id); n += 1) id = `${stem}-${n}`;
+  return id;
+}

package/src/core/auto/recipes.mjs

@@ -0,0 +1,75 @@
+// The ONE Auto-path module where agent keys may appear (spec D23): prompt
+// guidance for the classifier and the canned shapes the offline mock answers
+// with. The assembler and the orchestrator never read these keys — they read
+// port meta.
+
+// Rendered into BOTH selection paths — the Ask system prompt (prompt.mjs renderCatalog)
+// and the classifier system prompt (classify.mjs) — so the sizing principle is stated
+// here once: build UP from the implementer, one rung per concrete signal (2026-09-07 ladder).
+export const RECIPE_GUIDE = [
+  '## Recipes (starting points — adapt them to the task)',
+  'Sizing: build the workflow UP from the implementer and add a stage only when a concrete signal in the task itself demands it — every extra stage must earn its cost in time and money; when unsure between two shapes, take the lighter one. Never inflate "size" or "signals" to justify a stage.',
+  'taskKind names what the user GAVE, never how big the work is: prompt = an idea, request or bug report with no plan; plan-partial = a sketch or a plan with gaps; plan-complete-detailed = a complete, detailed plan; plan-complete-small = a complete but small plan. Only plan-complete-* makes the task document the plan of record, so never label a prompt as a plan to reach a lighter rung — the ladder below reaches it directly.',
+  'The ladder (each rung adds ONE stage to the rung before it; take the first rung that fits):',
+  '- trivial — implementer only: a well-specified small change whose result the tests can check (a dependency bump, a config or copy change, a one-file fix, a rename, a complete small plan)',
+  '- small — implementer ⇄ reviewer: the change is bigger than one bounded edit (several files, a new code path, a public interface, anything a second pair of eyes should check) but the text already says precisely what to build — a complete, detailed plan lands here',
+  '- needs a plan — clarify → planner → implementer ⇄ reviewer: the text says WHAT but not HOW, so the implementer would have to explore the codebase and design before writing (a plain prompt whose change is more than trivial)',
+  '- big plan — clarify → planner → refiner (selfLoop) → implementer ⇄ reviewer: the plan to be written is large or subtle enough that a second pass on it pays off (many files or subsystems, cross-cutting behaviour, unclear edge cases)',
+  '- given plan, large — refiner (selfLoop) → implementer ⇄ reviewer: the user GAVE a complete plan that is large or has gaps worth tightening before implementation; a partial plan (plan-partial) gets a planner in front: planner → refiner (selfLoop) → implementer ⇄ reviewer',
+  'Clarify: it goes only directly in front of a planner (its answers feed the planner), only on a plain prompt (taskKind prompt), and only when a human is in the loop — the trivial and small rungs, a given plan and a run without a human never get it.',
+  'Modifiers (exceptions, never a default — each needs a real signal in the task itself):',
+  '- web / UI feature — ONLY for a very big user-facing UI feature (many screens or flows, a new page with complex interaction): append manualTestsChecklist → manualWebUiTesting after the reviewer; its review loops back into the implementer automatically. A CSS tweak, a single component change or any small or medium UI change stays with the reviewer only, and the fingerprint\'s "web-ui likely" hint is context about the repository, never a trigger',
+  '- large task — only when the task really spans many files or subsystems: insert decomposer between the last planning stage and the implementer and set the implementer\'s fanOut to true',
+  '- risky or large plan — only for an irreversible or high-blast-radius change (data migrations, auth, billing, public APIs) or a plan too big to check by eye: add planReviewer right after the planner (it loops back into the planner)',
+  'Rules: only a clarifier stage asks the user up front; a verifier loops automatically to the nearest earlier stage that can take its verdict (declare "loops" only to override, "loop": false to suppress); give "selfLoop": true to every stage whose card says it can loop on itself; use "parallel" only for stages that do not depend on each other; a stage after a parallel group waits for the whole group on every cycle; a verifier after a group loops back to a stage BEFORE the group unless it reads a member\'s output directly (the assembler enforces this — never loop into a member the verifier does not read); plugin and user agents (the card\'s origin field: plugin:<name> or user) fit wherever their ports match.',
+].join('\n');
+
+const S = (agent, extra = {}) => ({ agent, ...extra });
+const REFINER = () => S('refiner', { selfLoop: true });
+
+/** Every rung × modifier the classifier is taught, as shapes the tests run offline. */
+export const RECIPE_SHAPES = Object.freeze([
+  // the ladder
+  { id: 'trivial', shape: { name: 'Quick fix', taskKind: 'prompt', stages: [S('implementer')] } },
+  { id: 'small', shape: { name: 'Implement + review', taskKind: 'prompt', stages: [S('implementer'), S('reviewer')] } },
+  { id: 'needs-plan', shape: { name: 'Clarify, plan, implement + review', taskKind: 'prompt', stages: [S('clarify'), S('planner'), S('implementer'), S('reviewer')] } },
+  { id: 'prompt', shape: { name: 'Clarify, plan, refine, implement + review', taskKind: 'prompt', stages: [S('clarify'), S('planner'), REFINER(), S('implementer'), S('reviewer')] } },
+  { id: 'plan-partial', shape: { name: 'Plan, refine, implement + review', taskKind: 'plan-partial', stages: [S('planner'), REFINER(), S('implementer'), S('reviewer')] } },
+  { id: 'plan-complete-detailed', shape: { name: 'Implement + review the plan', taskKind: 'plan-complete-detailed', stages: [S('implementer'), S('reviewer')] } },
+  { id: 'plan-complete-large', shape: { name: 'Refine, implement + review the plan', taskKind: 'plan-complete-detailed', stages: [REFINER(), S('implementer'), S('reviewer')] } },
+  { id: 'plan-complete-small', shape: { name: 'Implement the plan', taskKind: 'plan-complete-small', stages: [S('implementer')] } },
+  // modifiers
+  { id: 'prompt+web', shape: { name: 'Clarify, plan, refine, implement + web tests', taskKind: 'prompt', stages: [S('clarify'), S('planner'), REFINER(), S('implementer'), S('reviewer'), S('manualTestsChecklist'), S('manualWebUiTesting')] } },
+  { id: 'prompt+large', shape: { name: 'Clarify, plan, refine, decompose, implement + review', taskKind: 'prompt', stages: [S('clarify'), S('planner'), REFINER(), S('decomposer'), S('implementer', { fanOut: true }), S('reviewer')] } },
+  { id: 'prompt+risky', shape: { name: 'Clarify, plan + plan review, refine, implement + review', taskKind: 'prompt', stages: [S('clarify'), S('planner'), S('planReviewer'), REFINER(), S('implementer'), S('reviewer')] } },
+  { id: 'plan-partial+web+large', shape: { name: 'Plan, refine, decompose, implement + web tests', taskKind: 'plan-partial', stages: [S('planner'), REFINER(), S('decomposer'), S('implementer', { fanOut: true }), S('reviewer'), S('manualTestsChecklist'), S('manualWebUiTesting')] } },
+  { id: 'plan-complete-detailed+web', shape: { name: 'Implement, review + web tests', taskKind: 'plan-complete-detailed', stages: [S('implementer'), S('reviewer'), S('manualTestsChecklist'), S('manualWebUiTesting')] } },
+  // A group may sit anywhere; a verifier after it loops to a stage the whole group
+  // depends on (or to a member it reads) — the assembler refuses anything else.
+  { id: 'parallel-end', shape: { name: 'Plan, refine, implement, review ∥ checklist', taskKind: 'plan-partial', stages: [S('planner'), REFINER(), S('implementer'), { parallel: [S('reviewer'), S('manualTestsChecklist')] }] } },
+  { id: 'parallel-mid', shape: { name: 'Plan, refine, implement, review ∥ checklist, web tests', taskKind: 'plan-partial', stages: [S('planner'), REFINER(), S('implementer'), { parallel: [S('reviewer'), S('manualTestsChecklist')] }, S('manualWebUiTesting')] } },
+]);
+
+const WEB_RE = /\b(web|ui|page|button|css|react|vue|svelte|browser|frontend|front-end|html|component|modal|dropdown|theme)\b/i;
+const clone = (v) => JSON.parse(JSON.stringify(v));
+const byId = (id) => clone(RECIPE_SHAPES.find((r) => r.id === id).shape);
+
+/**
+ * The offline classifier: cheap, deterministic heuristics over the task text.
+ * Never spawns anything — `npm run smoke`-style runs and the test suite depend on it.
+ */
+export function mockShapeFor(taskText, { humanInLoop = true } = {}) {
+  const text = String(taskText || '').trim();
+  const hasHeading = /^#{1,3}\s+\S/m.test(text);
+  let shape;
+  if (hasHeading) shape = text.length >= 1200 ? byId('plan-complete-detailed') : byId('plan-complete-small');
+  else if (text.length < 80) shape = byId('trivial');
+  else if (WEB_RE.test(text)) shape = byId('prompt+web');
+  else shape = byId('prompt');
+  if (!humanInLoop) shape.stages = shape.stages.filter((s) => s.agent !== 'clarify');
+  shape.reasoning = `mock classifier: ${hasHeading ? 'the task is a plan' : text.length < 80 ? 'a trivial prompt' : 'a free-form prompt'}${WEB_RE.test(text) && !hasHeading && text.length >= 80 ? ' for a web feature' : ''}`;
+  const web = WEB_RE.test(text) && !hasHeading && text.length >= 80;
+  shape.size = hasHeading ? (text.length >= 1200 ? 'large' : 'small') : (text.length < 80 ? 'small' : 'medium');
+  shape.signals = hasHeading ? ['plan', text.length >= 1200 ? 'large' : 'trivial'] : (text.length < 80 ? ['trivial'] : (web ? ['web UI'] : []));
+  return shape;
+}

package/src/core/auto/repo-look.mjs

@@ -0,0 +1,46 @@
+// A short-lived, read-only DETACHED checkout the Auto classifier may Grep/Glob/Read
+// (spec D6 amendment, 2026-09-07). The run path needs none: the run's own worktree IS
+// the checkout (orchestrator.mjs _autoRound passes this.runCwd). The chat path
+// (propose_workflow) has no worktree, so it borrows one here for the duration of ONE
+// classifier call and removes it in close(). fs + the DB-free git primitives of
+// ../worktree.mjs only — no shell, no hard-coded separators; no agent key is named here (D23).
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createDetachedWorktree, removeWorktree, isValidSourceRef } from '../worktree.mjs';
+
+export const REPO_LOOK_DIRNAME = 'auto-look';
+
+/**
+ * @param {string} projectDir the project's live checkout — read for HEAD, never used as cwd
+ * @param {string} baseDir where the throwaway checkout lives (the chat passes <worcaHome>/tmp/ask)
+ * @param {{signal?:AbortSignal|null, log?:(msg:string)=>void}} [o]
+ * @returns {Promise<{cwd:string, close:() => Promise<void>}|null>} null ⇒ no git repository, HEAD does
+ *   not resolve, or git failed — the caller then classifies from the task text only, as before.
+ */
+export async function openRepoLook(projectDir, baseDir, { signal = null, log = () => {} } = {}) {
+  try {
+    if (!projectDir || !baseDir || !existsSync(join(projectDir, '.git'))) return null;
+    if (signal?.aborted) throw new Error('aborted before the checkout');
+    if (!(await isValidSourceRef(projectDir, 'HEAD'))) return null;
+    mkdirSync(baseDir, { recursive: true });
+    const worktreeDir = join(baseDir, `${REPO_LOOK_DIRNAME}-${randomBytes(4).toString('hex')}`);
+    // The signal is spread in ONLY when present: worktree.mjs's git() forwards it verbatim to
+    // child_process.spawn, and Node rejects `options.signal: null` (ERR_INVALID_ARG_TYPE) — git()
+    // would swallow that as ok:false and this whole look would silently degrade to text-only.
+    await createDetachedWorktree({ projectDir, worktreeDir, ref: 'HEAD', ...(signal ? { signal } : {}) });
+    let closed = false;
+    const close = async () => {
+      if (closed) return;
+      closed = true;
+      try {
+        const res = await removeWorktree({ projectDir, worktreeDir, branch: null, force: true });
+        for (const s of (res.steps || []).filter((x) => !x.ok)) log(`repo look: ${s.step} failed for ${worktreeDir}: ${s.stderr || 'unknown error'}`);
+      } catch (err) { log(`repo look: could not remove ${worktreeDir}: ${err && err.message ? err.message : err}`); }
+    };
+    return { cwd: worktreeDir, close };
+  } catch (err) {
+    log(`repo look unavailable (${err && err.message ? err.message : err}); classifying from the task text only`);
+    return null;
+  }
+}

package/src/core/claude-runner.mjs

@@ -39,7 +39,11 @@ import { effectiveDebugSpawn } from './settings.mjs';
 import { classifyError, strongestClass } from './recoverable-error.mjs';
 import { explainUnspawnableClaude, resolveClaudeBin } from './preflight.mjs';
 import { hostGuardEnabled, hostGuardHookEntry, hostGuardSystemPrompt } from './host-guard.mjs';
-import { writeFile, mkdir, appendFile, readFile, access } from 'node:fs/promises';
+// The offline classifier and the shape normalizer the mock ask role answers
+// propose_workflow with — both pure (no DB, no spawn).
+import { mockShapeFor } from './auto/recipes.mjs';
+import { normalizeShape } from '../shared/graph/assemble.mjs';
+import { writeFile, mkdir, appendFile, readFile, access, readdir } from 'node:fs/promises';
 import { constants as FS, mkdtempSync, writeFileSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -342,7 +346,8 @@ export function mockEnabled(opts) {
  * @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 {string[]} [o.addDirs]            --add-dir <dir> per entry (Ask Worca's memory mount; the CLI loads <dir>/.claude/rules only with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 in the env — memory-deps.mjs / spawn.mjs set it)
+ *   All nine 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}>}
  */
@@ -380,6 +385,7 @@ export async function runClaude(o = {}) {
     maxTurns,
     maxBudgetUsd,
     appendSubagentSystemPrompt,
+    addDirs,
     argvInlineLimit,
     bin = DEFAULT_BIN,
   } = o;
@@ -424,6 +430,7 @@ export async function runClaude(o = {}) {
     maxTurns,
     maxBudgetUsd,
     appendSubagentSystemPrompt,
+    addDirs,
     argvInlineLimit,
   });
 }
@@ -446,8 +453,9 @@ export async function runClaude(o = {}) {
  *                        (docs/run-root-verification.md, branch (a); argv-attested
  *                        transcript phase0/out/v1a-rerun.jsonl, with a no-grant
  *                        negative control proving the grant is load-bearing).
- *  `--add-dir` is deliberately absent: it needs an env override to carry memory at
- *  all (E2) and no shipped feature uses it (§5.3 / §8.18). */
+ *  `--add-dir` carries Ask Worca's memory mount ONLY (`addDirs`): it needs the
+ *  CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 env override to load memory at all
+ *  (E2, re-probed 2026-09-13 on 2.1.270), and no pipeline path passes it (§5.3 / §8.18 unchanged). */
 export function buildClaudeArgs({
   prompt, systemPrompt, permissionMode, model, effort, allowedTools, resumeSessionId,
   mcpConfigPath, mcpServerGrants, permissionRules,
@@ -455,7 +463,7 @@ export function buildClaudeArgs({
   // way in because the legacy body below already owns a local `tools` (the
   // --allowedTools union).
   tools: builtinTools, strictMcpConfig, settingSources, disableSlashCommands, includePartialMessages,
-  maxTurns, maxBudgetUsd, appendSubagentSystemPrompt, hostGuard,
+  maxTurns, maxBudgetUsd, appendSubagentSystemPrompt, hostGuard, addDirs,
 }, delivery = {}) {
   // delivery (GH #380, set only by planClaudeInvocation's staged branch):
   //   promptViaStdin   -> bare `-p`; the prompt is written to the child's stdin
@@ -516,6 +524,9 @@ export function buildClaudeArgs({
   if (typeof appendSubagentSystemPrompt === 'string' && appendSubagentSystemPrompt) {
     args.push('--append-subagent-system-prompt', appendSubagentSystemPrompt);
   }
+  // Native-rules revision (2026-09-13): Ask Worca's memory mount. LAST, so every earlier argv
+  // stays a prefix; absent / [] / non-strings ⇒ nothing (the `names` filter above).
+  for (const d of names(addDirs)) args.push('--add-dir', d);
   return args;
 }
 
@@ -568,7 +579,7 @@ export function stageClaudeInvocation(opts, { bin = DEFAULT_BIN, limit = ARGV_IN
   return { ...plan, dir };
 }
 
-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 }) {
+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, addDirs, 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
@@ -647,7 +658,7 @@ function runReal({ cwd, systemPrompt, prompt, allowedTools, permissionMode, mode
         permissionMode, model: wireModel, effort, allowedTools, resumeSessionId,
         mcpConfigPath, mcpServerGrants, permissionRules,
         tools, strictMcpConfig, settingSources, disableSlashCommands, includePartialMessages,
-        maxTurns, maxBudgetUsd, appendSubagentSystemPrompt,
+        maxTurns, maxBudgetUsd, appendSubagentSystemPrompt, addDirs,
       }, { bin: resolved.bin, limit });
     } catch (err) {
       rejectP(new Error(`Failed to stage the claude prompt files: ${err.message}`));
@@ -965,7 +976,7 @@ async function emitLog(onEvent, text) {
  */
 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',
+  'workspace-scan', 'agent-gen', 'workspace-reviewer', 'manual-tests-checklist', 'manual-web-ui-testing', 'memory-defrag',
   'generic-producer', 'generic-verifier',
 ]);
 
@@ -973,6 +984,10 @@ export const MOCK_WRITER_ROLES = new Set([
 export const MOCK_ROLE_CLARIFY = 'clarify';
 export const MOCK_ROLE_DECOMPOSER = 'decomposer';
 
+/** The memory defragmenter's role, exported like the other two named roles (the switch below
+ *  still uses the literal string: mock-writer-roles.test.mjs parses the switch arms). */
+export const MOCK_ROLE_MEMORY_DEFRAG = 'memory-defrag';
+
 /**
  * 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.
@@ -1065,15 +1080,26 @@ async function mockAsk({ markers, prompt, cwd, onEvent, signal, resumeSessionId
   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);
+  // P3 (PD11): a workflow-card EVENT is matched first — it contains the words "workflow" and, when thenRun, "run",
+  // which would otherwise trip the two arms below. Then the workflow trigger, then the run proposal.
+  const wfEvent = /^\s*\[worca event\] workflow card (card_[0-9a-f]{8}) (?:(declined)|saved as (\S+) "([^"]*)"; thenRun=(true|false))/.exec(userText);
+  // A metrics-card EVENT, then the metrics trigger — both before the run arm, whose \brun\b would otherwise fire on
+  // "include my runs"-style prose (it does not, \b stops at the s, but "propose" would).
+  const tmEvent = /^\s*\[worca event\] metrics card (card_[0-9a-f]{8}) (applied|declined|failed)/.exec(userText);
+  // The metrics arm wants a CHANGE, not a question: "metrics" plus a verb of intent ("stop recording my metrics",
+  // "route ... to the metrics home"). A bare "which workspaces use team metrics?" gets the generic echo answer.
+  const metrics = !wfEvent && !tmEvent && /\bmetrics\b/i.test(userText)
+    && /\b(?:stop|start|turn|toggle|switch|record\w*|route|change|enable|disable|set)\b/i.test(userText);
+  const workflow = !wfEvent && !tmEvent && !metrics && /\bworkflow\b/i.test(userText);
+  const agents = !wfEvent && !tmEvent && /\bagents?\b/i.test(userText);
+  const propose = !wfEvent && !tmEvent && !workflow && !metrics && /\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'],
+    tools: ['Task', 'mcp__worca__list_runs', 'mcp__worca__get_run', 'mcp__worca__propose_run', 'mcp__worca__propose_workflow', 'mcp__worca__propose_metrics_change'],
     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 });
@@ -1110,6 +1136,43 @@ async function mockAsk({ markers, prompt, cwd, onEvent, signal, resumeSessionId
       );
       answerMsg = MSG2;
     }
+    if (workflow) {
+      // The result the real MCP child would return (plan PD1) — the parent re-assembles it with the real registry.
+      const shape = normalizeShape(mockShapeFor(userText, { humanInLoop: true }));
+      const wfInput = { task: userText.slice(0, 2000), projectKey: card.projectKey || null, thenRun: /\brun\b/i.test(userText) };
+      frames.push(delta('[mock] '), delta('building '), delta('a workflow'), atext(MSG1, 'Building a workflow card.'),
+        atool(MSG1, 'toolu_mock_workflow', 'mcp__worca__propose_workflow', wfInput),
+        uresult('toolu_mock_workflow', JSON.stringify({ ok: true, mode: 'task', projectKey: card.projectKey || null, projectName: null, name: shape.name, match: null,
+          warnings: [], summary: '', shape, costUsd: 0, fingerprint: 'top-level: (mock)\nhints: mock', note: '', thenRun: wfInput.thenRun })));
+      answerMsg = MSG2;
+    }
+    if (metrics) {
+      // The MCP child's validation result (metrics-proposal.mjs): the parent re-validates the INPUT and mints the card,
+      // so a mock card always targets the context project's "Include my runs" switch (no git involved when applied).
+      const tmInput = { kind: 'record', projectKey: card.projectKey || null, record: false, note: 'mock: stop recording my runs here' };
+      frames.push(delta('[mock] '), delta('proposing '), delta('a metrics change'), atext(MSG1, 'Proposing a metrics change card.'),
+        atool(MSG1, 'toolu_mock_metrics', 'mcp__worca__propose_metrics_change', tmInput),
+        uresult('toolu_mock_metrics', JSON.stringify({ ok: true, card: { type: 'metrics', ...tmInput } })));
+      answerMsg = MSG2;
+    }
+    if (tmEvent) {
+      const line = tmEvent[2] === 'declined' ? 'Declined — nothing changed.' : tmEvent[2] === 'failed' ? 'The change failed; check the error and try again.' : 'Applied.';
+      frames.push(delta('[mock] '), delta(tmEvent[2]), atext(MSG1, line));
+      answerMsg = MSG2;
+    }
+    if (wfEvent) {
+      // Every event arm answers on MSG2: a second atext on MSG1 would REPLACE the first reply's text.
+      if (wfEvent[2] === 'declined') {
+        frames.push(delta('[mock] '), delta('declined'), atext(MSG1, 'Declined. Want another auto workflow, tell me what to change, or pick a saved workflow?'));
+      } else if (wfEvent[5] === 'true') {
+        frames.push(delta('[mock] '), delta('proposing '), delta('a run'), atext(MSG1, `Proposing a run with "${wfEvent[4]}".`),
+          atool(MSG1, 'toolu_mock_propose', 'mcp__worca__propose_run', { ...card, workflowId: wfEvent[3], brief: `Run with "${wfEvent[4]}"` }),
+          uresult('toolu_mock_propose', JSON.stringify({ ok: true })));
+      } else {
+        frames.push(delta('[mock] '), delta('saved'), atext(MSG1, `Saved "${wfEvent[4]}". Say "run it" when you want a run with it.`));
+      }
+      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 })));
@@ -1230,6 +1293,9 @@ async function runMock({ cwd, systemPrompt, prompt, onEvent, signal, resumeSessi
     case 'manual-web-ui-testing':
       text = await mockManualWebUiTesting(m, cycle, onEvent);
       break;
+    case 'memory-defrag':
+      text = await mockMemoryDefrag(m, systemPrompt, onEvent);
+      break;
     case 'generic-producer':
       text = await mockGenericProducer(m, onEvent);
       break;
@@ -1331,6 +1397,61 @@ async function mockGenericProducer(m, onEvent) {
   return `[mock] generic artifact written to ${out}`;
 }
 
+/** The scope dirs the `## Worca memory` block of a system prompt names (memory-store.mjs
+ *  renderMemoryBlock: `<label> — <abs dir>:` lines under the heading; the block is contiguous,
+ *  so the first blank line ends it). The mock defragmenter finds its mount exactly the way the
+ *  real agent is told to — from its system prompt — so no MOCK marker is needed. Exported for
+ *  the parity test against a real renderMemoryBlock output. Both captures are greedy: a project
+ *  LABEL may itself contain ` — ` (the renderer's separator is the last one on the line), and a
+ *  Windows dir carries a drive colon while the line still ends with `:`. */
+export function memoryDirsFromPrompt(systemPrompt) {
+  const text = String(systemPrompt || '');
+  const at = text.indexOf('## Worca memory');
+  if (at === -1) return [];
+  const out = [];
+  for (const line of text.slice(at).split(/\r?\n/).slice(1)) {
+    if (!line.trim()) break;
+    const m = line.match(/^(?:Global|Project .*) — (.+):$/);
+    if (m) out.push(m[1]);
+  }
+  return out;
+}
+
+/** Memory defragment mock (agent-memory-design.md §7.1): in the FIRST scope dir the system
+ *  prompt names, fold the second (sorted) file's body into the first and EMPTY it (amendment
+ *  B19 — the memory tool set cannot unlink, so this is the path the real agent takes), then
+ *  write the report to MOCK_OUT. A defrag run mounts exactly ONE scope dir. */
+async function mockMemoryDefrag(m, systemPrompt, onEvent) {
+  const out = m.MOCK_OUT;
+  const dir = memoryDirsFromPrompt(systemPrompt)[0] || null;
+  await emitLog(onEvent, '[mock] memory defragmenter restructuring the mounted scope');
+  const lines = ['# Memory defragment report', ''];
+  let merged = null;
+  if (dir) {
+    const files = (await readdir(dir, { withFileTypes: true })).filter((e) => e.isFile() && e.name.endsWith('.md')).map((e) => e.name).sort();
+    if (files.length < 2) {
+      lines.push(`- ${dir}: ${files.length} file(s), nothing to merge`);
+    } else {
+      const [a, b] = files;
+      const bodyB = (await readFile(join(dir, b), 'utf8')).replace(/^---\n[\s\S]*?\n---\n/, '');
+      const text = `${await readFile(join(dir, a), 'utf8')}\n## Merged from ${b.slice(0, -3)}\n\n${bodyB}`;
+      await writeFile(join(dir, a), text, 'utf8');
+      await writeFile(join(dir, b), '', 'utf8');            // B19: an EMPTIED mount file is a deletion request
+      merged = [a, b];
+      lines.push(`- ${dir}: merged ${b} into ${a}; emptied ${b} (worca removes it at sync-back)`);
+      safeEmit(onEvent, { type: 'tool_use', text: `merged ${join(dir, b)} into ${join(dir, a)}`, raw: { mock: true, file: join(dir, a) } });
+    }
+  } else {
+    lines.push('- no memory scope in the system prompt: nothing to defragment');
+  }
+  if (out) {
+    await ensureDir(out);
+    await writeFile(out, `${lines.join('\n')}\n`, 'utf8');
+    safeEmit(onEvent, { type: 'tool_use', text: `wrote ${out}`, raw: { mock: true, file: out } });
+  }
+  return merged ? `[mock] memory defragment: merged ${merged[1]} into ${merged[0]}` : '[mock] memory defragment: nothing to merge';
+}
+
 async function mockPlannerPlan(m, onEvent) {
   const out = m.MOCK_OUT;
   const base = m.MOCK_BASE || 'feature';