@ijfw/memory-server 1.4.4 → 1.5.0

package/src/dispatch/colon-syntax.js

@@ -47,6 +47,11 @@ import { dirname, join } from 'path';
 // so the user-facing spelling 'domain-manifest:<op>' (matching the error
 // message and CLI surface) parses + routes uniformly. The set entry is the
 // hyphenated form so copy-paste from the error string Just Works.
+// v1.5.0 (T12): added 'state' — the state-SDK CLI face. Routes
+// `state:<verb> <json-payload>` straight into orchestrator/state-sdk.js
+// `query(verb, payload, ctx)`. This is the external-tooling surface for the
+// state-SDK; the JS module is the in-process surface and the MCP tool is the
+// remote surface (contract §0).
 const RUN_NAMESPACES = new Set([
   'compute',
   'index',
@@ -55,6 +60,7 @@ const RUN_NAMESPACES = new Set([
   'override',
   'extension',
   'domain-manifest',
+  'state',
 ]);
 const SEARCH_NAMESPACES = new Set(['compute', 'graph']);
 
@@ -166,13 +172,87 @@ export async function dispatchRun(parsed, ctx = {}) {
     const m = await import('./domain-manifest.js');
     return m.domainManifestDispatch({ command: parsed.command, args: parsed.args, projectRoot });
   }
+  if (parsed.namespace === 'state') {
+    return dispatchState(parsed, { projectRoot, sessionId });
+  }
 
   return {
     ok: false,
-    error: 'Unknown ijfw_run sub-command. Supported: compute:python, compute:js, index:<source>, detect:project_type, graph:traverse, override:<op>, extension:<op>, domain-manifest:<op>',
+    error: 'Unknown ijfw_run sub-command. Supported: compute:python, compute:js, index:<source>, detect:project_type, graph:traverse, override:<op>, extension:<op>, domain-manifest:<op>, state:<verb>',
   };
 }
 
+// --- state:<verb> dispatch -------------------------------------------------
+//
+// T12: external tooling reaches the state-SDK via the CLI colon-namespace.
+// `state:<verb> [json-payload]` parses the payload as JSON, then calls
+// orchestrator/state-sdk.js `query(verb, payload, ctx)`. The verb name is the
+// part after `state:` (e.g. `workflow.get`, `wave.advance`). The payload
+// defaults to `{}` when no args are supplied — read-only verbs like
+// `workflow.get` work with an empty payload.
+//
+// Errors come back as `{ ok: false, error, code }` so callers (cli-run.js,
+// shell hooks) can JSON.parse the stdout uniformly. Unknown verbs throw
+// inside `query()` and the throw is caught + surfaced with `code: 'UNKNOWN_VERB'`.
+async function dispatchState(parsed, { projectRoot, sessionId }) {
+  const verb = parsed.command;
+  if (!verb) {
+    return { ok: false, error: 'state:<verb> requires a verb after the colon.', code: 'NO_VERB' };
+  }
+
+  // Parse the JSON payload. Empty args -> `{}`. The colon-syntax parser
+  // already strips a single matching outer quote pair so callers can use
+  // either `state:foo '{"k":"v"}'` (shell-style) or `state:foo {"k":"v"}`
+  // (already-stripped) and reach the same handler.
+  const raw = String(parsed.args || '').trim();
+  let payload = {};
+  if (raw.length > 0) {
+    try {
+      payload = JSON.parse(raw);
+    } catch (err) {
+      return {
+        ok: false,
+        error: `state:${verb} payload is not valid JSON: ${err && err.message ? err.message : String(err)}`,
+        code: 'INVALID_JSON',
+      };
+    }
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+      return {
+        ok: false,
+        error: `state:${verb} payload must be a JSON object, got ${Array.isArray(payload) ? 'array' : typeof payload}.`,
+        code: 'INVALID_JSON',
+      };
+    }
+  }
+
+  // Lazy-import the SDK so this module stays cheap for the non-state
+  // dispatch paths (e.g. compute:python) and so a state-sdk init error
+  // surfaces as a structured ok:false instead of a top-level module crash.
+  let query;
+  try {
+    ({ query } = await import('../orchestrator/state-sdk.js'));
+  } catch (err) {
+    return {
+      ok: false,
+      error: `state:${verb} could not load state-sdk: ${err && err.message ? err.message : String(err)}`,
+      code: 'SDK_LOAD',
+    };
+  }
+
+  try {
+    const result = await query(verb, payload, { projectRoot, sessionId });
+    return result;
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    const isUnknownVerb = /unknown verb/i.test(msg);
+    return {
+      ok: false,
+      error: `state:${verb} did not complete: ${msg}`,
+      code: isUnknownVerb ? 'UNKNOWN_VERB' : (err && err.code) || 'ERROR',
+    };
+  }
+}
+
 async function dispatchCompute(parsed, { projectRoot, sessionId /*, provenance unused for compute runs */ }) {
   const cmd = parsed.command;
   if (cmd !== 'js' && cmd !== 'python') {

package/src/dispatch/extension.js

@@ -17,6 +17,26 @@
  *                             current project's platform dirs. Fired by the
  *                             session-start hook so org/user-scoped extensions
  *                             become available in every project session.
+ *
+ * TODO(v1.5.0-major S01 — IJFW_PARENT_PROJECT_ROOT env passthrough):
+ *   The Agent({ isolation: 'worktree' }) spawn path lives in the Claude Code
+ *   harness (Task tool / SDK), NOT in this MCP server's dispatch flow. When the
+ *   harness eventually exposes a hook for env passthrough on worktree dispatch,
+ *   the dispatcher MUST set:
+ *
+ *     IJFW_PARENT_PROJECT_ROOT=<absolute path to the orchestrator's projectRoot>
+ *
+ *   so that the subagent's `ijfw checkpoint` writes land in the PARENT project's
+ *   .ijfw/wave-<id>/ instead of the disposable worktree's .ijfw/. Until that
+ *   harness hook exists, the contract is documented in
+ *   `mcp-server/src/orchestrator/checkpoint-contract.md` ("Worktree isolation
+ *   drain protocol") and the orchestrator MUST run `ijfw worktree-drain
+ *   <waveId> <worktreePath>` BEFORE `git worktree remove` as a belt-and-
+ *   suspenders fallback (see dispatch/wave-cli.js worktree-drain handler).
+ *
+ *   Subagent-side: any agent template that may run in worktree isolation should
+ *   read `process.env.IJFW_PARENT_PROJECT_ROOT` (already honored transparently
+ *   by orchestrator/subagent-telemetry.js record/read/list).
  */
 
 import {
@@ -613,12 +633,14 @@ async function cmdDeactivate() {
 let _v143Handlers = null;
 async function loadV143Handlers() {
   if (_v143Handlers !== null) return _v143Handlers;
-  const [registry, signer, quota, active, wave] = await Promise.all([
+  const [registry, signer, quota, active, wave, checkpoint, worktree] = await Promise.all([
     import('./registry-cli.js'),
     import('./signer-cli.js'),
     import('./quota-cli.js'),
     import('./active-cli.js'),
-    import('./wave-cli.js'),  // v1.4.4 N9 — wave-status / wave-list
+    import('./wave-cli.js'),       // v1.4.4 N9 — wave-status / wave-list
+    import('./checkpoint-cli.js'), // v1.5.0 W11-A1 — ijfw checkpoint (S1)
+    import('./worktree-cli.js'),   // v1.5.0 W11-A2 — ijfw worktree provision (S2)
   ]);
   _v143Handlers = Object.assign(
     Object.create(null),
@@ -627,6 +649,8 @@ async function loadV143Handlers() {
     quota.handlers || {},
     active.handlers || {},
     wave.handlers || {},
+    checkpoint.handlers || {},
+    worktree.handlers || {},
   );
   return _v143Handlers;
 }

package/src/dispatch/registry-cli.js

@@ -28,6 +28,8 @@ import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir as osHomedir } from 'node:os';
 import { createPublicKey } from 'node:crypto';
+// v1.5.0 audit-LOW-update-#13: shared tmp-suffix helper.
+import { tmpSuffix } from '../lib/tmp-suffix.js';
 
 import {
   loadRegistrySources,
@@ -70,7 +72,8 @@ async function readRegistriesFile(ctx) {
 async function writeRegistriesFile(ctx, doc) {
   const path = registriesConfigPath(ctx);
   await mkdir(join(homedir(ctx), '.ijfw'), { recursive: true });
-  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  // v1.5.0 audit-LOW-update-#13: consolidate tmp-suffix shape via helper.
+  const tmp = `${path}.tmp.${tmpSuffix()}`;
   await writeFile(tmp, JSON.stringify(doc, null, 2) + '\n', 'utf8');
   const { rename } = await import('node:fs/promises');
   await rename(tmp, path);

package/src/dispatch/wave-cli.js

@@ -13,10 +13,11 @@
  * snapshot-based per lock-in #31 — no daemon, no subscriptions.
  */
 
-import { readdir, stat } from 'node:fs/promises';
+import { readdir, stat, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { readWaveState } from '../orchestrator/wave-state.js';
+import { drainCheckpoints } from '../orchestrator/subagent-telemetry.js';
 
 const WAVE_DIR_PREFIX = 'wave-';
 
@@ -111,18 +112,212 @@ export const handlers = {
       return { ok: true, output: '(no waves)' };
     }
     waves.sort((a, b) => b.mtimeMs - a.mtimeMs);
-    const rows = [];
-    for (const { id } of waves) {
-      const state = await readWaveState(id, projectRoot);
+    // v1.5.0 F3 (R3 fold-in): parallel reads via Promise.all.
+    // Sequential await over N waves was O(N*disk-latency); parallelised on N>3.
+    const states = await Promise.all(waves.map(({ id }) => readWaveState(id, projectRoot)));
+    const rows = waves.map(({ id }, i) => {
+      const state = states[i];
       const status = state?.frontmatter?.status ?? '?';
       const createdAt = state?.frontmatter?.created_at ?? '';
-      rows.push(`${id}\t${status}\t${createdAt}`);
-    }
+      return `${id}\t${status}\t${createdAt}`;
+    });
     return { ok: true, output: rows.join('\n') };
   },
+
+  // r17.1 (item 6): subagent "did anyone go silent?" check. Takes a wave id
+  // plus the list of subagent ids you EXPECTED to complete and reports which
+  // ones have a checkpoint receipt vs which are MIA. Closes the wayland-
+  // session pattern where 5 of 8 dispatched subagents went silent and the
+  // orchestrator (Claude) had no way to know without manually scanning.
+  //
+  // Usage:
+  //   ijfw wave-missing <waveId> <expectedId1> [<expectedId2> ...]
+  // Exits non-zero (via ctx-aware caller) when any expected id is missing.
+  //
+  // Why this is in IJFW vs a SKILL: the orchestrator harness doesn't notify
+  // Claude when an Agent subagent silently fails. IJFW can't fix that — only
+  // the harness can. What IJFW CAN do: give the orchestrator a deterministic,
+  // mechanical way to ask "are the receipts here?" without scraping the
+  // worktree filesystem by hand.
+  'wave-missing': async (args, ctx) => {
+    const tokens = tokenize(args);
+    const waveId = tokens[0];
+    let expected = tokens.slice(1);
+
+    // v1.5.0 audit-MED-work-M4: when the operator omits the expected list,
+    // try to read `.ijfw/wave-<id>/expected.json` (written at fan-out by the
+    // orchestrator). Closes the "orchestrator forgot to call wave-missing
+    // with the right argv" failure mode. argv list still wins when present.
+    if (waveId && expected.length === 0) {
+      const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+      try {
+        const f = join(projectRoot, '.ijfw', `${WAVE_DIR_PREFIX}${waveId}`, 'expected.json');
+        const raw = await readFile(f, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.expected)) {
+          expected = parsed.expected.filter((x) => typeof x === 'string' && x.length > 0);
+        }
+      } catch { /* no expected.json — fall through to usage error below */ }
+    }
+
+    if (!waveId || expected.length === 0) {
+      return {
+        ok: false,
+        error: 'Usage: ijfw wave-missing <waveId> <expectedSubId1> [<expectedSubId2> ...]',
+      };
+    }
+    // r17-M2: validate waveId so it can't traverse out of .ijfw/. The wave
+    // directory format is `wave-<id>` and ids are expected to be a small set
+    // of safe chars (alnum, dash, dot for versions, underscore).
+    if (!/^[A-Za-z0-9._-]+$/.test(waveId) || waveId.includes('..')) {
+      return { ok: false, error: `wave-missing: invalid waveId "${waveId}" (must match [A-Za-z0-9._-] and not contain "..")` };
+    }
+    // Also validate expected ids — they're echoed back to the user but
+    // also used in regex construction inside the present-set match. Safe-char
+    // gate prevents both reflection of garbage and any future use as paths.
+    for (const id of expected) {
+      if (!/^[A-Za-z0-9._-]+$/.test(id) || id.includes('..')) {
+        return { ok: false, error: `wave-missing: invalid expected id "${id}" (must match [A-Za-z0-9._-] and not contain "..")` };
+      }
+    }
+    const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+    const waveDir = join(projectRoot, '.ijfw', `${WAVE_DIR_PREFIX}${waveId}`);
+    let dirents = [];
+    try {
+      dirents = await readdir(waveDir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return {
+          ok: false,
+          output: `Wave ${waveId} has no .ijfw/wave-${waveId}/ directory. All ${expected.length} expected subagent(s) are MISSING.\nMissing: ${expected.join(', ')}`,
+        };
+      }
+      return { ok: false, error: `wave-missing: ${err.message}` };
+    }
+
+    // Two canonical receipt filename forms:
+    //   1. Wave-id-prefixed (Phase D synthesized + S01 CLI default):
+    //        subagent-<waveId>-<subId>.checkpoint.json
+    //   2. Bare runtime form (when ijfw checkpoint <waveId> <subId> ... runs
+    //      and the subId itself has no embedded dashes that collide):
+    //        subagent-<subId>.checkpoint.json
+    // We extract subId by stripping a leading "<waveId>-" if present, then
+    // taking everything before ".checkpoint.json". This avoids the regex-
+    // overlap bug where greedy captures double-counted a subId that happens
+    // to start with a word that resembles another subId.
+    const present = new Set();
+    const wavePrefix = `subagent-${waveId}-`;
+    const barePrefix = 'subagent-';
+    const suffix = '.checkpoint.json';
+    for (const ent of dirents) {
+      if (!ent.isFile()) continue;
+      const name = ent.name;
+      if (!name.startsWith(barePrefix) || !name.endsWith(suffix)) continue;
+      let subId;
+      if (name.startsWith(wavePrefix)) {
+        subId = name.slice(wavePrefix.length, name.length - suffix.length);
+      } else {
+        subId = name.slice(barePrefix.length, name.length - suffix.length);
+      }
+      if (subId.length > 0) present.add(subId);
+    }
+    const found = expected.filter(id => present.has(id));
+    const missing = expected.filter(id => !present.has(id));
+    const stray = [...present].filter(id => !expected.includes(id));
+
+    const lines = [
+      `Wave: ${waveId}`,
+      `Expected: ${expected.length} subagent(s)`,
+      `Present:  ${found.length} (${found.join(', ') || 'none'})`,
+      `Missing:  ${missing.length} (${missing.join(', ') || 'none'})`,
+    ];
+    if (stray.length > 0) {
+      lines.push(`Stray:    ${stray.length} (${stray.join(', ')}) — present but not expected`);
+    }
+    return {
+      ok: missing.length === 0,
+      output: lines.join('\n'),
+    };
+  },
+
+  // v1.5.0 audit-MED-work-M4: write `.ijfw/wave-<id>/expected.json` so a
+  // later `ijfw wave-missing <id>` call can self-config from disk and the
+  // orchestrator-LLM doesn't have to remember the expected subagent list at
+  // fan-in time. Usage:
+  //   ijfw wave-expected <waveId> <expectedSubId1> [<expectedSubId2> ...]
+  'wave-expected': async (args, ctx) => {
+    const tokens = tokenize(args);
+    const waveId = tokens[0];
+    const expected = tokens.slice(1);
+    if (!waveId || expected.length === 0) {
+      return {
+        ok: false,
+        error: 'Usage: ijfw wave-expected <waveId> <expectedSubId1> [<expectedSubId2> ...]',
+      };
+    }
+    if (!/^[A-Za-z0-9._-]+$/.test(waveId) || waveId.includes('..')) {
+      return { ok: false, error: `wave-expected: invalid waveId "${waveId}" (must match [A-Za-z0-9._-] and not contain "..")` };
+    }
+    for (const id of expected) {
+      if (!/^[A-Za-z0-9._-]+$/.test(id) || id.includes('..')) {
+        return { ok: false, error: `wave-expected: invalid expected id "${id}" (must match [A-Za-z0-9._-] and not contain "..")` };
+      }
+    }
+    const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+    const waveDir = join(projectRoot, '.ijfw', `${WAVE_DIR_PREFIX}${waveId}`);
+    try {
+      await mkdir(waveDir, { recursive: true });
+      const payload = JSON.stringify(
+        { wave_id: waveId, expected, recorded_at: new Date().toISOString() },
+        null, 2,
+      ) + '\n';
+      await writeFile(join(waveDir, 'expected.json'), payload, 'utf8');
+      return { ok: true, output: `ok: recorded ${expected.length} expected subagent(s) for ${waveId}` };
+    } catch (err) {
+      return { ok: false, error: `wave-expected: ${err && err.message ? err.message : String(err)}` };
+    }
+  },
+
+  // v1.5.0-major S01: belt-and-suspenders drain of subagent checkpoints from
+  // a worktree's .ijfw/wave-<id>/ into the parent project's .ijfw/wave-<id>/.
+  // Run BEFORE `git worktree remove` so checkpoints survive cleanup even if
+  // the subagent didn't honor IJFW_PARENT_PROJECT_ROOT (older callers, manual
+  // claude invocation in a worktree, etc.).
+  'worktree-drain': async (args, ctx) => {
+    const tokens = tokenize(args);
+    const [waveId, worktreePath] = tokens;
+    if (!waveId || !worktreePath) {
+      return {
+        ok: false,
+        error: 'Usage: ijfw worktree-drain <waveId> <worktreePath>',
+      };
+    }
+    const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+    try {
+      const result = await drainCheckpoints(waveId, worktreePath, projectRoot);
+      if (!result.ok) {
+        return { ok: false, error: `ijfw worktree-drain: ${result.reason}` };
+      }
+      return {
+        ok: true,
+        output: `ok: drained ${result.drained} checkpoint(s) from ${worktreePath}`,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: `ijfw worktree-drain: ${err && err.message ? err.message : String(err)}`,
+      };
+    }
+  },
 };
 
 export const subcommandHelp = {
   'wave-status': 'wave-status [<id>|latest] — print live state of a wave',
   'wave-list':   'wave-list — list all known waves (newest first)',
+  'wave-missing':
+    'wave-missing <waveId> [<expectedId1> ...] — list any dispatched subagents that have no checkpoint receipt (catches silent-failure dispatches). When expected ids are omitted, reads from .ijfw/wave-<id>/expected.json (written by `ijfw wave-expected`).',
+  'wave-expected':
+    'wave-expected <waveId> <expectedId1> [<expectedId2> ...] — record the expected subagent ids for a wave so `ijfw wave-missing <id>` can self-config (v1.5.0 audit-MED-work-M4)',
+  'worktree-drain':
+    'worktree-drain <waveId> <worktreePath> — copy subagent checkpoints from a worktree to the parent before `git worktree remove` (v1.5.0 S01)',
 };

package/src/dispatch/worktree-cli.js

@@ -0,0 +1,40 @@
+/**
+ * dispatch/worktree-cli.js — v1.5.0 S2 worktree provisioning CLI.
+ *
+ * Frozen export contract (briefing-locked):
+ *   export const worktreeHandlers      = Object.freeze({ worktree: handler });
+ *   export const worktreeSubcommandHelp = Object.freeze({ '<subcommand>': '<help>' });
+ *
+ * Handler returns a numeric exit code (0=ok, 1=failure, 2=usage), distinct
+ * from wave-cli's {ok,output} shape because this command writes JSON to stdout
+ * directly for downstream orchestrator consumption.
+ *
+ * Subcommand owned by this module:
+ *   - worktree provision <path>
+ */
+
+import { provisionWorktree } from '../orchestrator/worktree-provision.js';
+import { resolve } from 'node:path';
+
+const SUBCOMMAND_HELP = {
+  'worktree provision': 'ijfw worktree provision <path> — detect+install deps in a worktree (v1.5.0 S2)',
+};
+
+async function handleWorktree(args, _ctx) {
+  if (args[0] !== 'provision' || !args[1]) {
+    process.stderr.write('Usage: ijfw worktree provision <path>\n');
+    return 2;
+  }
+  const path = resolve(args[1]);
+  try {
+    const result = await provisionWorktree(path);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result.failed.length > 0 ? 1 : 0;
+  } catch (err) {
+    process.stderr.write(`ijfw worktree: ${err.message}\n`);
+    return 1;
+  }
+}
+
+export const worktreeHandlers = Object.freeze({ worktree: handleWorktree });
+export const worktreeSubcommandHelp = Object.freeze(SUBCOMMAND_HELP);

package/src/dispatch-planner.js

@@ -4,7 +4,9 @@
 // computes a dispatch manifest: each sub-wave is either SHARED (no file overlap
 // with peers in the same wave) or WORKTREE (overlaps -> needs isolation).
 //
-// Pure + synchronous. ESM. Zero deps. Filesystem only touched by caller.
+// Pure + synchronous. ESM. Zero deps. No filesystem writes — all state
+// persistence is the caller's responsibility via state-SDK query() (T6).
+// A spy regression test in test-dispatch-planner.js enforces this permanently.
 
 // eslint-disable-next-line security/detect-unsafe-regex -- plan markdown is bounded human-authored text; pattern is line-anchored and token-sized.
 const WAVE_HEADER = /^###\s+Wave\s+([0-9]+[A-Z])(?:-([A-Za-z0-9_+]+))?\b/;
@@ -54,7 +56,25 @@ export function parsePlan(markdown) {
         .split(/[,\s]+/)
         .map((s) => s.replace(/^`|`$/g, '').trim())
         .filter(Boolean);
-      for (const a of add) if (!target.files.includes(a)) target.files.push(a);
+      for (const a of add) {
+        // v1.5.0 audit-LOW-work-L7: refuse the universal glob `**` (and its
+        // common forms `**/*`, `./**`). It declares "every file under the
+        // repo," which guarantees overlap with every peer sub-wave and forces
+        // them all into worktree isolation — which is almost always a
+        // planner mistake, not a real declaration. Catch it at parse time
+        // with a clear message instead of letting it silently neutralise
+        // the wave-routing algorithm.
+        const norm = a.replace(/^\.\//, '');
+        if (norm === '**' || norm === '**/*' || norm === '*' || norm === '*/**') {
+          throw new Error(
+            `dispatch-planner: refusing universal glob "${a}" in Files: line ` +
+            `(declares every file in repo, forces every peer sub-wave into ` +
+            `worktree isolation — almost always a planner mistake). ` +
+            `Use specific path prefixes instead.`,
+          );
+        }
+        if (!target.files.includes(a)) target.files.push(a);
+      }
     }
   }
   push(currentSub);
@@ -182,6 +202,81 @@ export function mergeOrder(manifest) {
 
 function idOf(sw) { return sw.sub || sw.wave; }
 
+// ---------------------------------------------------------------------------
+// v1.5.0 T19 (G1) — env-var passthrough composer (pure, no fs writes).
+//
+// Computes the SDK-contract env map a dispatched subagent inherits, given
+// the parent's process env and the per-subagent (waveId, subId, isolation,
+// projectRoot) context. The actual dispatch is performed by the
+// `subagent.dispatch` SDK verb — this is the planner-side pure helper used
+// to construct the env passthrough payload BEFORE the verb call.
+//
+// Stays in dispatch-planner.js because:
+//   * Caller intent: the planner is the orchestrator's pure compute layer.
+//   * Test invariant: the dispatch-planner spy gate forbids ANY fs write —
+//     this helper performs zero fs I/O (read or write).
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose the deterministic env-var passthrough for a dispatched subagent.
+ *
+ * The SDK contract specifies these well-known names (verb contract §7
+ * `subagent.dispatch`):
+ *   * `IJFW_PROJECT_DIR`         — absolute project root
+ *   * `IJFW_PARENT_PROJECT_ROOT` — parent's project root (worktree subagents)
+ *   * `IJFW_WAVE_ID`             — wave id
+ *   * `IJFW_SUBAGENT_ID`         — this subagent's id
+ *   * `IJFW_ISOLATION`           — 'shared' | 'worktree'
+ *   * `IJFW_SESSION_ID`          — orchestrator session id (when set)
+ *
+ * Caller-supplied `extraEnv` keys override the SDK contract on collision —
+ * by design (caller's intent wins). Values are coerced to strings; null /
+ * undefined entries are dropped.
+ *
+ * @param {{projectRoot:string, waveId:string, subagentId:string,
+ *          isolation?:'shared'|'worktree', parentEnv?:object, extraEnv?:object}} input
+ * @returns {Record<string,string>} the composed env map (sorted-stable).
+ */
+export function composeDispatchEnv(input) {
+  if (!input || typeof input !== 'object') {
+    throw new Error('dispatch-planner.composeDispatchEnv: input object required');
+  }
+  const { projectRoot, waveId, subagentId } = input;
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new Error('dispatch-planner.composeDispatchEnv: projectRoot required');
+  }
+  if (typeof waveId !== 'string' || waveId.length === 0) {
+    throw new Error('dispatch-planner.composeDispatchEnv: waveId required');
+  }
+  if (typeof subagentId !== 'string' || subagentId.length === 0) {
+    throw new Error('dispatch-planner.composeDispatchEnv: subagentId required');
+  }
+  const isolation = input.isolation === 'shared' ? 'shared' : 'worktree';
+  const parentEnv = (input.parentEnv && typeof input.parentEnv === 'object')
+    ? input.parentEnv : {};
+  const extraEnv = (input.extraEnv && typeof input.extraEnv === 'object'
+    && !Array.isArray(input.extraEnv)) ? input.extraEnv : {};
+
+  const composed = {
+    IJFW_PROJECT_DIR: projectRoot,
+    IJFW_PARENT_PROJECT_ROOT: typeof parentEnv.IJFW_PARENT_PROJECT_ROOT === 'string'
+      && parentEnv.IJFW_PARENT_PROJECT_ROOT.length > 0
+      ? parentEnv.IJFW_PARENT_PROJECT_ROOT : projectRoot,
+    IJFW_WAVE_ID: waveId,
+    IJFW_SUBAGENT_ID: subagentId,
+    IJFW_ISOLATION: isolation,
+  };
+  if (typeof parentEnv.IJFW_SESSION_ID === 'string' && parentEnv.IJFW_SESSION_ID.length > 0) {
+    composed.IJFW_SESSION_ID = parentEnv.IJFW_SESSION_ID;
+  }
+  for (const [k, v] of Object.entries(extraEnv)) {
+    if (v === null || v === undefined) continue;
+    composed[k] = String(v);
+  }
+  // Stable sort for deterministic output ordering.
+  return Object.fromEntries(Object.keys(composed).sort().map((k) => [k, composed[k]]));
+}
+
 // Glob-aware intersection. Treats `*`/`**` as wildcards so a declaration
 // like `claude/commands/*.md` conflicts with `claude/commands/status.md`.
 // Returns true on any exact match OR glob-vs-literal match.

package/src/dream/runner.mjs

@@ -38,6 +38,8 @@ import { existsSync, mkdirSync, appendFileSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isOnCooldown, markCompleted } from './cooldown.js';
+import { shouldRunNow } from './state-file.js';
+import { runStages } from './stage-runner.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -91,13 +93,24 @@ function log(line) {
 }
 
 // ---------------------------------------------------------------------------
-// Cooldown gate
+// Idle gate (M4 — replaces legacy 4h cooldown with min_idle_minutes
+// gate, default 30 min, override via IJFW_DREAM_MIN_IDLE_MIN).
+// Legacy cooldown.markCompleted() is still called as a final stage so
+// downstream code reading the old marker keeps working.
 // ---------------------------------------------------------------------------
 
-if (isOnCooldown(stateDir)) {
-  log(`skip: cooldown active (host=${opts.host}, reason=${opts.reason})`);
+const MIN_IDLE_MIN = Number(process.env.IJFW_DREAM_MIN_IDLE_MIN || 30);
+if (!shouldRunNow(opts.projectRoot, { min_idle_minutes: MIN_IDLE_MIN })) {
+  log(`skip: idle gate <${MIN_IDLE_MIN}min since last run`);
   process.exit(0);
 }
+// Legacy cooldown is now informational only — the new idle gate above is
+// strictly stricter (30 min) than the old 4h. We still consult it as a
+// belt-and-braces signal, but ONLY for visibility in the log; it does not
+// block the run.
+if (isOnCooldown(stateDir)) {
+  log(`note: legacy 4h cooldown also active (host=${opts.host}, reason=${opts.reason}) — proceeding under idle gate`);
+}
 
 log(`start: host=${opts.host}, reason=${opts.reason}, project=${opts.projectRoot}`);
 
@@ -351,14 +364,37 @@ function safeJournalSummary() {
 
 (async () => {
   try {
-    const summary = safeJournalSummary();
-    log(`journal: ${summary.entries} entries across ${summary.sessions} sessions`);
-
-    await runTierPromotion();
-
-    const ok = markCompleted(stateDir);
-    log(`mark-completed: ${ok ? 'ok' : 'failed (non-fatal)'}`);
-    log('end: clean');
+    // M4 hardening: lift each step into a stage-runner stage so a failure
+    // in one stage logs + continues; downstream stages still execute.
+    // State file records each stage's status independently.
+    const summary = await runStages(opts.projectRoot, [
+      {
+        name: 'journal_summary',
+        run: async () => {
+          const s = safeJournalSummary();
+          log(`journal: ${s.entries} entries across ${s.sessions} sessions`);
+          return s;
+        },
+      },
+      {
+        name: 'tier_promotion',
+        run: async () => {
+          const out = await runTierPromotion();
+          return out || { skipped: 'no-op' };
+        },
+      },
+      {
+        name: 'mark_completed_legacy',
+        run: async () => {
+          // Preserve the legacy 4h cooldown marker so any downstream code
+          // still reading .dream-state.json continues to work.
+          const ok = markCompleted(stateDir);
+          log(`mark-completed: ${ok ? 'ok' : 'failed (non-fatal)'}`);
+          return { ok };
+        },
+      },
+    ]);
+    log(`end: completed=${summary.completed.length} failed=${summary.failed.length}`);
   } catch (err) {
     // Defensive: any unexpected throw lands in the log but never
     // surfaces a non-zero exit to the parent hook.