@ijfw/memory-server 1.4.3 → 1.5.0

package/src/dispatch/wave-cli.js

@@ -0,0 +1,323 @@
+/**
+ * dispatch/wave-cli.js — IJFW v1.4.4 / N9 wave-status CLI handlers.
+ *
+ * Frozen export contract (v1.4.3 dispatch module convention):
+ *   export const handlers = { '<subcommand>': async (args, ctx) => ({ ok, output?, error? }) };
+ *   export const subcommandHelp = { '<subcommand>': 'one-line description' };
+ *
+ * Subcommands owned by this module:
+ *   - wave-status [<id>|latest]
+ *   - wave-list
+ *
+ * Reads via mcp-server/src/orchestrator/wave-state.js (W10-A0). Read-only,
+ * snapshot-based per lock-in #31 — no daemon, no subscriptions.
+ */
+
+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-';
+
+function tokenize(args) {
+  if (Array.isArray(args)) return args.filter((x) => x !== undefined && x !== null);
+  if (typeof args !== 'string') return [];
+  return args.split(/\s+/).filter(Boolean);
+}
+
+async function listWaveEntries(projectRoot) {
+  const ijfwDir = join(projectRoot, '.ijfw');
+  let entries = [];
+  try {
+    entries = await readdir(ijfwDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const waves = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory() || !ent.name.startsWith(WAVE_DIR_PREFIX)) continue;
+    const id = ent.name.slice(WAVE_DIR_PREFIX.length);
+    if (!id) continue;
+    const dir = join(ijfwDir, ent.name);
+    let mtimeMs = 0;
+    try {
+      const s = await stat(dir);
+      mtimeMs = s.mtimeMs;
+    } catch {
+      // tolerate vanished dirs
+    }
+    waves.push({ id, dir, mtimeMs });
+  }
+  return waves;
+}
+
+async function resolveLatestWaveId(projectRoot) {
+  const waves = await listWaveEntries(projectRoot);
+  if (waves.length === 0) return null;
+  waves.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return waves[0].id;
+}
+
+function renderStateForTerminal({ waveId, frontmatter, body }) {
+  const lines = [];
+  lines.push(`Wave: ${waveId}`);
+  for (const [key, val] of Object.entries(frontmatter || {})) {
+    if (key === 'wave_id') continue;
+    if (Array.isArray(val)) {
+      lines.push(`${key}: [${val.join(', ')}]`);
+    } else {
+      lines.push(`${key}: ${val}`);
+    }
+  }
+  if (body && body.trim()) {
+    lines.push('');
+    lines.push('--- notes ---');
+    lines.push(body.trim());
+  }
+  return lines.join('\n');
+}
+
+export const handlers = {
+  'wave-status': async (args, ctx) => {
+    const tokens = tokenize(args);
+    const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+    let waveId = tokens[0];
+    if (!waveId || waveId === 'latest') {
+      waveId = await resolveLatestWaveId(projectRoot);
+      if (!waveId) {
+        return { ok: false, output: 'No waves found in .ijfw/wave-*/' };
+      }
+    }
+    const state = await readWaveState(waveId, projectRoot);
+    if (!state) {
+      return { ok: false, output: `Wave ${waveId} not found` };
+    }
+    return {
+      ok: true,
+      output: renderStateForTerminal({
+        waveId,
+        frontmatter: state.frontmatter,
+        body: state.body,
+      }),
+    };
+  },
+
+  'wave-list': async (_args, ctx) => {
+    const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+    const waves = await listWaveEntries(projectRoot);
+    if (waves.length === 0) {
+      return { ok: true, output: '(no waves)' };
+    }
+    waves.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    // 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 ?? '';
+      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.

package/src/dream/stage-runner.js

@@ -0,0 +1,40 @@
+// IJFW v1.5.0 -- per-stage error-isolated dream runner.
+//
+// Wayland's "best-effort staged" pattern: a failure in one stage logs and
+// continues; downstream stages still execute. The state file records each
+// stage's status so a future run (or operator) can see what actually
+// happened, and which stages need re-execution.
+//
+// Lift from sibling project Wayland:
+// crates/wcore-memory/src/consolidate.rs ConsolidationEngine::run
+
+import {
+  markRunStart, markStageStarted, markStageCompleted,
+  markStageFailed, markRunCompleted,
+} from './state-file.js';
+
+export async function runStages(root, stages) {
+  markRunStart(root);
+  const completed = [];
+  const failed = [];
+  for (const stage of stages) {
+    if (!stage || typeof stage.name !== 'string' || typeof stage.run !== 'function') {
+      failed.push({ name: String(stage?.name), reason: 'invalid_stage_definition' });
+      continue;
+    }
+    markStageStarted(root, stage.name);
+    try {
+      const extras = (await stage.run()) || {};
+      markStageCompleted(root, stage.name, extras);
+      completed.push({ name: stage.name, extras });
+    } catch (e) {
+      markStageFailed(root, stage.name, e?.message || String(e));
+      failed.push({ name: stage.name, reason: e?.message || String(e) });
+      // CONTINUE -- per-stage isolation.
+    }
+  }
+  markRunCompleted(root);
+  return { ok: failed.length === 0, completed, failed };
+}
+
+export default { runStages };