@ijfw/memory-server 1.5.3 → 1.5.5

package/src/orchestrator/state-sdk.js

@@ -44,6 +44,7 @@ import { homedir } from 'node:os';
 import { randomUUID, createHash } from 'node:crypto';
 import { gunzipSync } from 'node:zlib';
 import { execFileSync } from 'node:child_process';
+import { AsyncLocalStorage } from 'node:async_hooks';
 
 import { writeAtomic, readSafe } from '../lib/atomic-io.js';
 import { rotateJsonlIfNeeded } from '../lib/jsonl-rotation.js';
@@ -270,6 +271,54 @@ async function _withLocks(lockTargets, fn, env) {
   return acquireFrom(0);
 }
 
+/**
+ * V155-002 — `state.replay` recovery-side lock-nest helper.
+ *
+ * Recursive nest of `withFsLock` matching `_withLocks`'s acquire-order shape,
+ * BUT lock-only: no journal-begin write, no snapshot capture. Replay is a
+ * recovery path, not a new mutating verb — generating a write-ahead begin
+ * record here would corrupt the journal.
+ *
+ * `targets` MUST be pre-canonicalised by `canonicalLockOrder` AND MUST NOT
+ * include the intent-journal path (already held by the outer
+ * `withFsLock(lockPathFor(journal), …)` in `state.replay`; re-acquiring it
+ * would deadlock against the outer scope — `withFsLock` is non-re-entrant).
+ *
+ * @param {string[]} targets  canonical-sorted, journal-excluded restore paths
+ * @param {() => Promise<void>} fn  the restore-or-delete loop body
+ * @returns {Promise<void>}
+ */
+// TS-002 (v1.5.5 Trident): `withFsLock` is non-re-entrant. If a future code
+// path (e.g. a gate hook firing from inside a restored body) recursively
+// triggers `state.replay`, the nested `_replayRestoreWithLocks` would silently
+// deadlock against itself instead of failing fast. The AsyncLocalStorage
+// sentinel below detects nested entry and throws `state-sdk: replay re-entry
+// detected` rather than hanging — preserves a useful error surface for the
+// next maintainer. Not exploitable today (no such recursion exists); this is
+// the documented latent-defect rail Trident TS-002 asked for.
+const _replayReentryGuard = new AsyncLocalStorage();
+
+async function _replayRestoreWithLocks(targets, fn) {
+  if (_replayReentryGuard.getStore() === true) {
+    throw new Error(
+      'state-sdk: replay re-entry detected — _replayRestoreWithLocks must not be '
+      + 'called recursively (withFsLock is non-re-entrant; nested entry would deadlock).',
+    );
+  }
+  if (!Array.isArray(targets) || targets.length === 0) {
+    return _replayReentryGuard.run(true, () => fn());
+  }
+  const acquireFrom = async (index) => {
+    if (index >= targets.length) return fn();
+    return withFsLock(
+      lockPathFor(targets[index]),
+      async () => acquireFrom(index + 1),
+      LOCK_OPTS,
+    );
+  };
+  return _replayReentryGuard.run(true, () => acquireFrom(0));
+}
+
 /**
  * Relative-path form for a journal `targets[]` entry. Project-scope files are
  * rendered relative to `projectRoot` (the §4 example shape — e.g.
@@ -622,6 +671,44 @@ export function payloadDigest(payload) {
 // is a facade: this matches wave-state.js's on-disk format exactly so a wave
 // written by either surface round-trips through the other.
 
+// V155-023: prototype-pollution defense. Frontmatter is parsed from operator-
+// supplied YAML (and from `wave.advance` payload merges below) — any key whose
+// name is `__proto__`, `constructor`, or `prototype` would mutate the resulting
+// plain-object's [[Prototype]] chain. Refuse those names everywhere keys are
+// assigned from untrusted input.
+const POLLUTING_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function isPollutingKey(k) {
+  return typeof k !== 'string' || POLLUTING_KEYS.has(k);
+}
+
+// TS-003 (v1.5.5 Trident): the top-level `isPollutingKey` filter at the two
+// declared sinks (parseFrontmatter + wave.advance merge) catches only top-level
+// keys. A nested payload like `{foo: {__proto__: {hard_gate: true}}}` would
+// slip past the shallow scan. Today `emitFrontmatter` happens to throw on
+// nested objects so the attack fails at I/O — but that's safety by coincidence,
+// not by design. `containsPollutingKey` walks objects + arrays + the chain and
+// returns true if ANY depth contains a polluting key. Callers reject the whole
+// payload (rather than silently scrubbing) so a malicious shape never reaches
+// disk and the operator gets a clear refusal.
+function containsPollutingKey(value, depth = 0) {
+  if (depth > 16) return false; // bounded walk; cycle-or-bomb defense
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (containsPollutingKey(item, depth + 1)) return true;
+    }
+    return false;
+  }
+  // Object.getOwnPropertyNames + getPrototypeOf check catches a payload
+  // built with `Object.create({hard_gate: true})` even though the chain
+  // doesn't enumerate `for..in` in our shape — defense in depth.
+  for (const k of Object.getOwnPropertyNames(value)) {
+    if (POLLUTING_KEYS.has(k)) return true;
+    if (containsPollutingKey(value[k], depth + 1)) return true;
+  }
+  return false;
+}
+
 function parseFrontmatter(raw) {
   if (!raw.startsWith('---')) {
     throw new Error('state-sdk: STATE.md missing YAML frontmatter');
@@ -630,7 +717,9 @@ function parseFrontmatter(raw) {
   if (end === -1) throw new Error('state-sdk: STATE.md has unclosed frontmatter');
   const block = raw.slice(4, end);
   const body = raw.slice(end + 4).replace(/^\n+/, '');
-  const fm = {};
+  // Object.create(null) — strip the Object.prototype chain so even a key that
+  // sneaks past `isPollutingKey` cannot reach the global prototype.
+  const fm = Object.create(null);
   const lines = block.split('\n');
   for (let i = 0; i < lines.length; i += 1) {
     const line = lines[i];
@@ -640,6 +729,8 @@ function parseFrontmatter(raw) {
     const key = line.slice(0, c).trim();
     const rest = line.slice(c + 1).trim();
     if (!key) continue;
+    // V155-023: refuse prototype-pollution keys regardless of value shape.
+    if (isPollutingKey(key)) continue;
     if (rest === '') {
       // block sequence ("  - item" lines) or empty
       const seq = [];
@@ -913,12 +1004,44 @@ const handlers = {
         updated_at: nowIso(),
       };
       if (payload.frontmatter && typeof payload.frontmatter === 'object') {
-        for (const [k, v] of Object.entries(payload.frontmatter)) fm[k] = v;
+        // V155-023: refuse `__proto__` / `constructor` / `prototype` keys —
+        // an attacker payload of `{ __proto__: { hard_gate: true } }` would
+        // otherwise mutate the [[Prototype]] of `fm` and grant a hard-gate
+        // verdict via the prototype chain on subsequent reads.
+        //
+        // TS-003 (v1.5.5 Trident): top-level isPollutingKey() filter alone is
+        // shallow — a nested value like `{foo: {__proto__: ...}}` would slip
+        // past. `containsPollutingKey` walks the value tree; we refuse the
+        // ENTIRE payload merge if any depth carries a polluting key. Hard
+        // refusal beats silent scrub: the operator gets feedback and the
+        // contract stays simple (no half-merge state).
+        if (containsPollutingKey(payload.frontmatter)) {
+          return {
+            ok: false, refused: true, gate: 'wave-advance-proto-pollution',
+            reason: 'wave.advance payload.frontmatter contains a polluting key '
+              + '(__proto__ / constructor / prototype) at some depth; refusing merge.',
+          };
+        }
+        for (const [k, v] of Object.entries(payload.frontmatter)) {
+          if (isPollutingKey(k)) continue;
+          fm[k] = v;
+        }
       }
       // Persist the hard-gate declaration on the wave's frontmatter so
       // subsequent advance calls honor it without re-passing `hardGate`.
       if (payload?.hardGate === true) fm.hard_gate = true;
-      const wave = writeWaveStateFile(root, waveId, fm, existing?.body ?? '');
+      // V155-014 (HIGH): when the caller supplies `payload.body`, write the
+      // body INSIDE this same `_withLocks` critical section (intent-journal +
+      // waves.json + per-wave STATE.md). The prior pattern had wave-state.js
+      // call `wave.advance` to write the frontmatter (journaled), release ALL
+      // SDK locks, then re-acquire ONLY the per-wave STATE.md lock to write
+      // the body — a #4-only lock with no #1 journal record, leaving replay
+      // unable to roll back a body-write partial. Accepting body here folds
+      // the two writes into one journaled, fully-locked atomic operation.
+      const bodyPayload = (typeof payload?.body === 'string')
+        ? payload.body
+        : (existing?.body ?? '');
+      const wave = writeWaveStateFile(root, waveId, fm, bodyPayload);
       const result = { ok: true, wave };
       if (hardGate && GATE_BYPASS) {
         result.advisory = true;
@@ -999,8 +1122,23 @@ const handlers = {
     try {
       result = _gateFns.validatePlan(planText, { strict: true });
     } catch (e) {
+      // V155-008 (HIGH) — partial fix: contract §4 Model 4 reserves
+      // execution-fail for the ADVISORY verdict (the verb proceeds; the gate
+      // crash never freezes the workflow — see test-verification-gate-strict
+      // T15 phase.plan-check). The audit's concern (an adversary crashing the
+      // gate to disable enforcement) is mitigated here by adding a DISTINCT
+      // `error:'gate-execution-fail'` discriminator alongside `advisory:true`
+      // so downstream dispatchers/audit telemetry can DIFFERENTIATE a clean
+      // pass (`advisory:undefined`) from a bypass (`reason:'IJFW_STATE_GATE_BYPASS=1'`)
+      // from a crash (`error:'gate-execution-fail'`) — three distinct shapes,
+      // same ok-verdict by contract. Future contract revision can promote
+      // this to `ok:false` without re-finding the issue (the error field is
+      // already there to dispatch on).
       process.stderr.write(`[state-sdk] WARN phase.plan-check gate execution-fail: ${e.message}\n`);
-      return { ok: true, advisory: true, gate: 'plan-check', reason: e.message, findings: [] };
+      return {
+        ok: true, advisory: true, gate: 'plan-check',
+        error: 'gate-execution-fail', reason: e.message, findings: [],
+      };
     }
     // v1.5.0 T17 (W1 plan-check hard-BLOCK): structurally REFUSE on any
     // HIGH-tier finding (severity in {BLOCK, HIGH} per `isHighFinding`).
@@ -1271,8 +1409,14 @@ const handlers = {
     try {
       selfCheck = _gateFns.runSelfCheck(reportText, projectRoot);
     } catch (e) {
+      // V155-008 (HIGH) — partial fix: see phase.plan-check above. Contract
+      // §4 keeps the verdict advisory; we add a DISTINCT `error` field so
+      // downstream callers can tell crash from bypass from clean pass.
       process.stderr.write(`[state-sdk] WARN subagent.post-done gate execution-fail: ${e.message}\n`);
-      return { ok: true, advisory: true, gate: 'post-done-self-check', reason: e.message };
+      return {
+        ok: true, advisory: true, gate: 'post-done-self-check',
+        error: 'gate-execution-fail', reason: e.message,
+      };
     }
     // v1.5.1 cleanup C1 — T20 truncation classification. When the caller hands
     // us the subagent's `events` stream and/or intent `journal` on the payload,
@@ -1710,10 +1854,25 @@ const handlers = {
     const root = requireRoot(ctx);
     const journal = paths.intentJournal(root);
     if (!existsSync(journal)) {
-      return { ok: true, replayed: [], skipped: [], rolledBack: [] };
+      return { ok: true, replayed: [], skipped: [], rolledBack: [], sealed: [], conflicts: [] };
     }
     // The replay walk + any rollback restores happen under the intent-journal
     // lock so a concurrent mutating verb cannot interleave with recovery.
+    //
+    // V155-002 (BLOCKER): the recovery path MUST acquire the SAME §3 locks as
+    // the writers it is rolling back/forward. A snapshot's targets can span
+    // multiple §3 tiers (#2 workflow, #3 waves, #4 STATE.md, #8 AGENTS.md,
+    // #11 active-extension, …). Holding only the intent-journal lock (#1)
+    // while restoring those targets meant a concurrent `wave.advance` could
+    // interleave its mutation with `state.replay`'s restore on the SAME
+    // target — torn write. Fix: per-partial, nest acquisitions of every
+    // target's lock in canonicalLockOrder underneath the already-held #1
+    // journal lock before touching the filesystem.
+    //
+    // `_replayRestoreWithLocks` is a local re-implementation of `_withLocks`'s
+    // recursive nest — we cannot call `_withLocks` directly here because it
+    // also runs `_journalBegin` (recovery is NOT a new mutating verb) and we
+    // are ALREADY holding the journal lock so re-acquiring it would deadlock.
     return withFsLock(lockPathFor(journal), async () => {
       const records = readJsonl(journal);
       const sinceVerbId = payload?.sinceVerbId;
@@ -1732,6 +1891,7 @@ const handlers = {
       const skipped = [];
       const rolledBack = [];
       const sealed = [];
+      const conflicts = [];
       for (const [verbId, beginRec] of begins) {
         if (commits.has(verbId)) {
           // begin + commit → durably applied. Re-issuing it would be a no-op,
@@ -1751,17 +1911,85 @@ const handlers = {
         const isAppend = beginRec.kind === 'append'
           || (beginRec.kind === undefined && snap === null);
         if (!isAppend && snap && Array.isArray(snap.targets)) {
-          // Overwrite verb: restore every target from the snapshot sidecar —
-          // restore-or-delete per its pre-begin existence.
+          // Overwrite verb: restore every target from the snapshot sidecar
+          // under the SAME §3 locks the original writer held. Skip the
+          // intent-journal (already held by the outer withFsLock) — only the
+          // real targets need additional locks. Canonicalise so two replay
+          // invocations targeting overlapping snapshots can never deadlock
+          // (matches `_withLocks` ordering exactly).
+          const restoreTargets = canonicalLockOrder(
+            snap.targets
+              .map((t) => (t && typeof t.absPath === 'string') ? t.absPath : null)
+              .filter((p) => p !== null && p !== journal),
+          );
+          // TR-003 (v1.5.5 Trident): before overwriting BODY-BEARING targets
+          // (STATE.md files — the per-wave/per-phase markdown that V155-014
+          // folded into the journaled critical section), compare current
+          // on-disk content against the snapshot's EXPECTED pre-write content.
+          //
+          // Scope is INTENTIONALLY narrow: only STATE.md-shaped paths. Other
+          // snapshot targets (workflow.json, waves.json, AGENTS.md, etc.) are
+          // SDK-managed atomic files — operator/third-party edits to them are
+          // not a supported workflow and replay must still roll them back to
+          // honor §4 atomicity. STATE.md is the file V155-014 promoted to a
+          // body-bearing journaled target, and is the one a future migration
+          // script (or human operator) might reasonably touch between begin
+          // and replay. The fix is narrow on purpose — it protects the new
+          // body-write path V155-014 introduced without weakening the
+          // existing atomic-rollback contract for canonical SDK state files.
+          //
+          // Three observable shapes at replay time for STATE.md targets:
+          //   1. Live == snap.content   → safe restore (no-op write).
+          //   2. Live missing           → restore to snap.content. Safe.
+          //   3. Live != snap.content   → external edit possible. REFUSE,
+          //      surface conflict, leave live content alone, leave the
+          //      sidecar in place so a future replay (after manual triage)
+          //      can still attempt the rollback.
+          const conflictedTargets = [];
           for (const t of snap.targets) {
+            if (!t || typeof t.absPath !== 'string') continue;
+            if (!t.existed) continue; // pre-write didn't exist; partial created it (handled below)
+            // Narrow scope: only body-bearing STATE.md files. basename match
+            // is the canonical V155-014-introduced surface.
+            if (basename(t.absPath) !== 'STATE.md') continue;
             try {
-              if (t.existed) {
-                writeAtomic(t.absPath, t.content ?? '');
-              } else if (existsSync(t.absPath)) {
-                unlinkSync(t.absPath); // the partial created it — undo by delete
+              if (!existsSync(t.absPath)) continue;
+              const live = readFileSync(t.absPath, 'utf8');
+              const expected = t.content ?? '';
+              if (live !== expected) {
+                conflictedTargets.push({ absPath: t.absPath, reason: 'third-party-edit' });
               }
-            } catch { /* a single target restore failing must not abort the walk */ }
+            } catch {
+              // unreadable -> let the restore-or-delete handle it best-effort
+            }
           }
+          if (conflictedTargets.length > 0) {
+            conflicts.push({ verbId, targets: conflictedTargets });
+            process.stderr.write(
+              `[state-sdk] state.replay REFUSING to roll back ${verbId}: `
+              + `${conflictedTargets.length} STATE.md target(s) have on-disk content that differs `
+              + `from the pre-begin snapshot — possible third-party edit. `
+              + `Paths: ${conflictedTargets.map((c) => c.absPath).join(', ')}. `
+              + `Compact the intent-journal after manually resolving, or re-emit the verb.\n`,
+            );
+            // Skip rollback for THIS partial, leave the sidecar in place so a
+            // future operator can inspect it, and continue with the rest of
+            // the journal walk. We do NOT seal the partial — re-running replay
+            // after manual resolution should still attempt the rollback.
+            continue;
+          }
+          // eslint-disable-next-line no-await-in-loop
+          await _replayRestoreWithLocks(restoreTargets, async () => {
+            for (const t of snap.targets) {
+              try {
+                if (t.existed) {
+                  writeAtomic(t.absPath, t.content ?? '');
+                } else if (existsSync(t.absPath)) {
+                  unlinkSync(t.absPath); // the partial created it — undo by delete
+                }
+              } catch { /* a single target restore failing must not abort the walk */ }
+            }
+          });
         }
         // Discard any snapshot sidecar (overwrite verbs only — append verbs
         // never wrote one) and seal the verbId with a synthetic `commit` so a
@@ -1786,7 +2014,7 @@ const handlers = {
         else rolledBack.push(verbId);
       }
       return {
-        ok: true, replayed: [], skipped, rolledBack, sealed,
+        ok: true, replayed: [], skipped, rolledBack, sealed, conflicts,
       };
     }, LOCK_OPTS);
   },

package/src/orchestrator/wave-state.js

@@ -17,16 +17,15 @@
  * representation. `blockers_open` carries the blocker **id** array (machine-
  * consumed); a separate `blockers_open_summary` carries human-readable text.
  *
- * KNOWN SDK GAP (T7-followup-1): the SDK's `wave.advance` verb does NOT
- * accept a `body` field — its handler always preserves the existing body.
- * Until a body-write SDK verb lands, `writeWaveState` does a follow-up raw
- * atomic write to update the body. The body-write itself is still
- * tmp+rename+lock-protected and the SDK frontmatter write already committed
- * via the intent journal — so the worst-case partial state (frontmatter
- * advanced, body stale) is bounded and self-healing on next checkpoint.
+ * SDK GAP CLOSED (v1.5.5 — V155-014): the SDK's `wave.advance` verb now
+ * accepts an optional `body` field — frontmatter + body land inside ONE
+ * journaled critical section (intent-journal #1 + waves.json #3 + per-wave
+ * STATE.md #4). The prior two-write shape (SDK frontmatter, release all
+ * locks, re-acquire only #4 to write the body) is gone — `state.replay`
+ * can now roll back partial body writes via the same begin/commit pair.
  */
 
-import { mkdir, readFile, writeFile, rename, appendFile } from 'node:fs/promises';
+import { mkdir, readFile, appendFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { withFsLock } from '../fs-lock.js';
 import { readBlackboard } from '../blackboard.js';
@@ -167,35 +166,9 @@ function parseYaml(block) {
   return result;
 }
 
-/**
- * Emit a YAML frontmatter block for flat string/number/boolean/string[] values.
- * @param {object} obj
- * @returns {string}  (no leading/trailing `---`)
- */
-function emitYaml(obj) {
-  const lines = [];
-  for (const [key, val] of Object.entries(obj)) {
-    if (val === null || val === undefined) {
-      lines.push(`${key}: null`);
-    } else if (Array.isArray(val)) {
-      if (val.length === 0) {
-        lines.push(`${key}: []`);
-      } else {
-        lines.push(`${key}:`);
-        for (const item of val) lines.push(`  - ${item}`);
-      }
-    } else if (typeof val === 'boolean') {
-      lines.push(`${key}: ${val}`);
-    } else if (typeof val === 'number') {
-      lines.push(`${key}: ${val}`);
-    } else if (typeof val === 'object') {
-      throw new Error(`wave-state: nested YAML objects are not supported (key: "${key}")`);
-    } else {
-      lines.push(`${key}: ${val}`);
-    }
-  }
-  return lines.join('\n');
-}
+// V155-014 (TR-003): emitYaml was previously used to render the wave-state
+// body inline. After folding body writes into the SDK's journaled critical
+// section (state-sdk now owns emit), the helper is unused. Removed.
 
 // ---------------------------------------------------------------------------
 // Path helpers
@@ -282,40 +255,20 @@ export async function writeWaveState(waveId, state, projectRoot) {
   // pass the full requested frontmatter so unrelated keys are overwritten
   // intentionally (writeWaveState semantics: caller supplies the full
   // frontmatter shape they want persisted).
-  await query(
-    'wave.advance',
-    { waveId, status, frontmatter: { ...fm } },
-    { projectRoot },
-  );
-
-  // Body follow-up: SDK-gap T7-followup-1 — wave.advance preserves existing
-  // body and there is no body-write SDK verb yet. Until one lands, do an
-  // atomic in-place body update. Held under the same wave-STATE lock used by
-  // every wave-state writer, so concurrent checkpoints serialise.
+  //
+  // V155-014 (HIGH): body is now passed THROUGH the SDK call so frontmatter +
+  // body land inside ONE journaled critical section holding all three SDK
+  // locks (intent-journal #1, waves.json #3, per-wave STATE.md #4). The prior
+  // shape — call wave.advance for frontmatter, release SDK locks, re-acquire
+  // ONLY the STATE.md lock to write the body — gave a #4-only second
+  // critical section with no #1 journal record, so `state.replay` could not
+  // roll back a body-write partial. The two writes are now atomic and
+  // replay-safe.
+  const sdkPayload = { waveId, status, frontmatter: { ...fm } };
   if (state.body !== undefined && state.body !== null) {
-    const { dir, state: statePath, lock, tmp } = wavePaths(waveId, projectRoot);
-    await withFsLock(lock, async () => {
-      await mkdir(dir, { recursive: true });
-      let frontmatterRaw;
-      try {
-        const raw = await readFile(statePath, 'utf8');
-        const secondDelim = raw.indexOf('\n---', 3);
-        // Defensive: if the SDK-written STATE.md is somehow malformed, fall
-        // back to re-emitting frontmatter from the in-memory shape rather
-        // than refusing the body write.
-        if (raw.startsWith('---') && secondDelim !== -1) {
-          frontmatterRaw = raw.slice(0, secondDelim + 4); // '---\n…\n---\n'
-        } else {
-          frontmatterRaw = `---\n${emitYaml(fm)}\n---\n`;
-        }
-      } catch {
-        frontmatterRaw = `---\n${emitYaml(fm)}\n---\n`;
-      }
-      const payload = `${frontmatterRaw}\n${state.body}`;
-      await writeFile(tmp, payload, 'utf8');
-      await rename(tmp, statePath);
-    });
+    sdkPayload.body = state.body;
   }
+  await query('wave.advance', sdkPayload, { projectRoot });
 }
 
 /**

package/src/recovery/checkpoint.js

@@ -78,8 +78,23 @@ export function recoveryStatus(projectRoot = process.cwd()) {
 
 export function latestCheckpoint(projectRoot = process.cwd()) {
   const paths = checkpointPaths(projectRoot);
-  const latest = readLatest(paths.latest);
-  if (!latest) return { ok: false, error: 'no-checkpoint' };
+  const r = readLatest(paths.latest);
+  if (!r || r.code === 'enoent') {
+    return { ok: false, error: 'no-checkpoint' };
+  }
+  if (r.code === 'parse-fail') {
+    // V155-027 (v1.5.5): distinguish "no checkpoint" from "corrupt checkpoint".
+    // Previously both returned ok:false error:'no-checkpoint'; in-progress
+    // recovery work was silently abandoned on partial-write corruption.
+    return {
+      ok: false,
+      error: 'checkpoint-corrupt',
+      message: r.message,
+      path: paths.latest,
+      hint: `inspect ${paths.dir} for numbered checkpoints to recover from`,
+    };
+  }
+  const latest = r.data;
   let markdown = '';
   try { markdown = readFileSync(latest.mdPath, 'utf8'); } catch { /* optional */ }
   return { ok: true, ...latest, markdown };
@@ -229,12 +244,21 @@ function recommendedNext(team, plan, tasks) {
   return 'Verify completed work or prepare next wave';
 }
 
+/**
+ * V155-027 (v1.5.5): tagged return so callers can distinguish "missing" from
+ * "corrupt". Three shapes:
+ *   - { code: 'enoent' }                — file does not exist
+ *   - { code: 'parse-fail', message }   — file exists but JSON.parse threw
+ *   - { code: 'ok', data }              — clean read
+ * `null` is no longer returned. The legacy caller checked `!latest` against
+ * the prior null — `latestCheckpoint` now switches on `.code`.
+ */
 function readLatest(path) {
+  if (!existsSync(path)) return { code: 'enoent' };
   try {
-    if (!existsSync(path)) return null;
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return null;
+    return { code: 'ok', data: JSON.parse(readFileSync(path, 'utf8')) };
+  } catch (e) {
+    return { code: 'parse-fail', message: e?.message || String(e) };
   }
 }
 

package/src/recovery/code-fixer.js

@@ -223,13 +223,28 @@ export function triage(finding) {
 /* ────────────────────────────── tier 1 — re-read ────────────────────────── */
 
 /**
- * verifyTier1(filePath, newString) — confirm the edit actually landed.
+ * verifyTier1(filePath, newString, intent) — confirm the edit actually landed.
  * Returns { ok: boolean, evidence: string }.
+ *
+ * V155-025: previously `newString === ''` short-circuited to ok:true regardless
+ * of intent — empty-string was always "contained" in any file. Deletion intents
+ * legitimately produce an empty newString (the substring being removed), so
+ * the gate is parameterised by intent: only `'delete'` permits the empty path.
+ * Any other intent supplying an empty newString is treated as unverifiable.
  */
-export async function verifyTier1(filePath, newString) {
+export async function verifyTier1(filePath, newString, intent = 'edit') {
   try {
     const content = await readFile(filePath, 'utf8');
-    if (newString === '' || content.includes(newString)) {
+    if (newString === '') {
+      if (intent === 'delete') {
+        return { ok: true, evidence: 'tier-1: empty newString accepted for delete intent' };
+      }
+      return {
+        ok: false,
+        evidence: 'tier-1: empty newString supplied for non-delete intent — cannot verify',
+      };
+    }
+    if (content.includes(newString)) {
       return { ok: true, evidence: '' };
     }
     return {
@@ -358,10 +373,35 @@ export async function verifyTier3(projectRoot, verifyCmdOverride) {
   // verbatim. Timeout is generous (5 min) because real test suites can be slow.
   return new Promise((resolve) => {
     execFile('sh', ['-c', cmd], { cwd: projectRoot, timeout: 5 * 60_000 }, (err, stdout, stderr) => {
-      if (!err) return resolve({ ok: true, skipped: false });
-      const blob = String(stderr || stdout || err.message || '');
-      const evidence = blob.split('\n').slice(0, 20).join('\n');
-      resolve({ ok: false, evidence: `tier-3 (${cmd}): ${evidence}` });
+      const combined = `${String(stdout || '')}\n${String(stderr || '')}`;
+      if (err) {
+        const evidence = combined.split('\n').slice(0, 20).join('\n');
+        return resolve({ ok: false, evidence: `tier-3 (${cmd}): ${evidence}` });
+      }
+      // V155-029: exit 0 alone is NOT proof of healthy. `npm test --silent`,
+      // `: # noop`, a custom `test` script that just exits 0 — all return 0
+      // without running anything. Require positive evidence: either explicit
+      // pass markers in the output OR non-empty output WITHOUT failure markers.
+      const FAIL_MARKERS = /\b(failing|failed|FAIL|error|✘|✗|fatal)\b/i;
+      const PASS_MARKERS = /\b(pass|passing|passed|ok|✓|✔)\b/i;
+      if (FAIL_MARKERS.test(combined)) {
+        const evidence = combined.split('\n').filter((l) => FAIL_MARKERS.test(l)).slice(0, 20).join('\n');
+        return resolve({ ok: false, evidence: `tier-3 (${cmd}) exit 0 but failure markers present: ${evidence}` });
+      }
+      const trimmed = combined.trim();
+      if (trimmed.length === 0) {
+        return resolve({
+          ok: false,
+          evidence: `tier-3 (${cmd}): exited 0 with no output — silent-success suspected, cannot prove project healthy`,
+        });
+      }
+      if (!PASS_MARKERS.test(combined)) {
+        return resolve({
+          ok: false,
+          evidence: `tier-3 (${cmd}): exited 0 but no pass markers in output — cannot prove tests ran`,
+        });
+      }
+      resolve({ ok: true, skipped: false });
     });
   });
 }
@@ -579,9 +619,14 @@ export async function fixFinding({
   const expectedNewString = typeof fix === 'object' ? fix.new_string : null;
 
   // 4. tier 1 — re-read
+  // V155-025: empty new_string only legitimate when intent is delete (old_string
+  // is being removed). Derive intent from fix shape so the gate can distinguish
+  // honest deletions from "no change supplied → unverifiable".
+  const fixIntent = (typeof fix === 'object' && fix.new_string === '') ? 'delete' : 'edit';
   const t1 = await verifyTier1(
     filePath,
     expectedNewString !== null && expectedNewString !== undefined ? expectedNewString : '',
+    fixIntent,
   );
   if (!t1.ok) {
     await rollback(filePath, originalContent);

package/src/runtime-mediator.js

@@ -231,8 +231,8 @@ export function toolNameToActionTarget(toolName, args) {
       return { action: 'read', target: 'metrics:read' };
     case 'ijfw_update_check':
       return { action: 'read', target: 'update:check' };
-    case 'ijfw_update_apply':
-      return { action: 'write', target: 'update:apply' };
+    // V155-017 (v1.5.5): 'ijfw_update_apply' retired from MCP — see
+    // cross-orchestrator-cli.js for the supported `ijfw update` flow.
     case 'ijfw_prompt_check':
       return { action: 'read', target: 'prompt:check' };
     case 'ijfw_run': {