rcf-lite 0.32.5 → 0.33.0

package/rcf/user-stories/us-209.json

@@ -0,0 +1,70 @@
+{
+  "createdAt": "2026-10-07T13:46:54.539Z",
+  "updatedAt": "2026-10-07T13:46:54.539Z",
+  "description": "User story under REQ-002 for the traceability view (discovery sections 4 rank 8, 9 and 12, section 6.5; FBS-208; TAC-4136, ADR-4140). The Readiness tab's Trace sub-tab renders a matrix for a pivot read from entity= in the hash: rows are the stories and criteria under the pivot, columns are suites, cases, build specs and components, cells are filled where the chain reaches and coloured by resolution from coverage. Every id in the readiness tables carries a Trace action and the lookup modal's readiness hits land on the same hash. The client caches per state.version in memory and re-renders after an SSE swap. The per-requirement Mermaid slice on the Requirements tab is retired in the same change; no Mermaid is user-facing on these surfaces.",
+  "asA": "a product owner showing traceability or an engineer checking a requirement's reach",
+  "iWant": "a matrix from the chosen requirement down to its tests, with the unresolved cells visible, reachable from any id on the page",
+  "soThat": "the viewer demonstrates the traceability the method sells without a terminal",
+  "tacIds": [
+    "TAC-4136-view-query-routes"
+  ],
+  "acceptanceCriteria": [
+    {
+      "id": "AC-209-1",
+      "description": "[happy] Given the Trace sub-tab and a pivot id in the hash, when the client fetches \"./trace.json\" for it, then a matrix renders with one TraceMatrixRow per story and criterion under the pivot and columns for suites, cases, build specs and components, each TraceMatrixCell.reached true where the forward trace reaches the column from the row's criterion.",
+      "testable": true,
+      "ownerRef": {
+        "tacId": "TAC-4136-view-query-routes",
+        "field": "interfaces[renderTraceMatrix]"
+      }
+    },
+    {
+      "id": "AC-209-2",
+      "description": "[happy] Given coverage data for the pivot's criteria, when a cell renders, then TraceMatrixCell.resolution is \"resolving\" on the --sv-success token, \"unresolved\" on the --sv-warning token or \"none\" on the --sv-muted token, with no new colour token introduced.",
+      "testable": true,
+      "ownerRef": {
+        "tacId": "TAC-4136-view-query-routes",
+        "field": "interfaces[TraceMatrixCell]"
+      }
+    },
+    {
+      "id": "AC-209-3",
+      "description": "[happy] Given any id rendered in the questions, blocking, thin-requirements or coverage tables, when the row renders, then it carries a \"Trace\" action linking to \"#tab=readiness&sub=trace&entity=<id>\", and a lookup modal hit on a readiness row navigates to the same hash preserving embed and theme.",
+      "testable": true,
+      "ownerRef": {
+        "tacId": "TAC-4136-view-query-routes",
+        "field": "interfaces[wireTraceMatrix]"
+      }
+    },
+    {
+      "id": "AC-209-4",
+      "description": "[edge] Given an SSE tree-update that swaps #rcf-live-content while the Trace sub-tab shows a matrix, when the swap lands, then the matrix is re-rendered from the client cache keyed by state.version and marked stale until the next fetch completes, never dropped.",
+      "testable": true
+    },
+    {
+      "id": "AC-209-5",
+      "description": "[must-not] Given the Requirements tab, when a requirement renders, then no Mermaid slice diagram is rendered for it (the per-requirement slice and its details element are gone) and no Mermaid is rendered anywhere on the Readiness tab.",
+      "testable": true
+    },
+    {
+      "id": "AC-209-6",
+      "description": "[failure] Given a pivot the route reports with found false, when the Trace sub-tab renders, then an empty state names the id and offers the lookup modal, and no partial matrix is drawn.",
+      "testable": true
+    },
+    {
+      "id": "AC-209-7",
+      "description": "[edge] Given a pivot whose forward trace yields more than 200 TraceMatrixRow entries, when the matrix renders, then a row filter by story id or criterion id is shown, the full TraceMatrixRow.cells set is retained in memory and nothing is truncated silently.",
+      "testable": true,
+      "ownerRef": {
+        "tacId": "TAC-4136-view-query-routes",
+        "field": "interfaces[TraceMatrixRow]"
+      }
+    }
+  ],
+  "usId": "US-209",
+  "prdId": "PRD-001",
+  "reqId": "REQ-002",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "the viewer renders a trace matrix for a selected node and offers Trace on every id, retiring the Mermaid slice"
+}

package/releases/releases.yaml

@@ -40,8 +40,17 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.32.5"
+latest: "0.33.0"
 releases:
+  - version: "0.33.0"
+    date: "2026-10-09"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.33.0 makes the viewer's Readiness tab the command page: questions, blocking items, a coverage summary, a stage grid with sub-tabs, delta counts and a trace matrix, backed by three new trace, impact and coverage JSON routes with a per-version memo on the viewer server. `rcf verify run` and `rcf build finalise` gain a deterministic mode so a dispatched worker that cannot spawn the agent CLI can still produce a report and refuse promotion honestly. The live viewer survives write-temp-then-rename saves (vim backupcopy=no, JetBrains safe-write) and never silently drops a change that lands mid-rewalk. The @stravica-ai/rcf-schemas 0.6.3 pin is unchanged."
+      - "For embedders: three new viewer routes (/trace.json, /impact.json, /coverage.json) must be added to the reverse-proxy allow-list for /rcf-viewer/* before the version pin bump. The embed contract and the rcf-view-theme postMessage are unchanged."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.32.5"
     date: "2026-10-07"
     breaking: false

package/src/cli/finalise.js

@@ -30,11 +30,18 @@ import { resolve as resolvePath } from 'node:path';
 import process from 'node:process';
 import { parseArgs } from 'node:util';
 
+import { writeFile } from 'node:fs/promises';
+
 import { isRcfError, rcfError, writeUnexpectedFailure } from '#core/errors';
 import { updateDocument, walkTree } from '#core/store';
 
 import { findProjectRoot } from '../view/index.js';
 import { kindOf } from '../query/index.js';
+import {
+  DEFAULT_VERIFY_MODE,
+  VERIFY_MODES,
+  isVerifyMode,
+} from '../verify/engine/deterministic.js';
 import {
   buildVerifyArgs,
   composeShipWithoutVerifiedRecord,
@@ -111,6 +118,12 @@ const OPTION_SPEC = {
   // deploy), the check is skipped and a warn line records that
   // finalise could not resolve the branch state.
   'allow-pre-merge': { type: 'boolean' },
+  // Issue 330 (2026-10-08): verify mode passed through to the fresh
+  // `rcf verify run` subprocess. Default is agentScreenshotCritique (the
+  // parent-session mode). A dispatched worker runs --mode deterministic
+  // because the harness refuses to let a worker spawn `claude` as a
+  // subagent, which agentScreenshotCritique requires.
+  mode: { type: 'string' },
   quiet: { type: 'boolean' },
   help: { type: 'boolean' },
 };
@@ -176,6 +189,18 @@ Options:
                             dev-loop dry runs; the decision is logged
                             on stdout. Absent a git checkout the check
                             degrades to a warn line.
+  --mode <mode>             Verify mode (default: agentScreenshotCritique):
+                              agentScreenshotCritique  parent-session mode
+                                 (spawns the agent CLI as a subagent); only
+                                 runs from a session that may invoke the
+                                 agent CLI.
+                              deterministic  model-free, in-process mode a
+                                 dispatched worker can run. Produces the
+                                 same report schema with a per-AC skip
+                                 ledger; the finalise gate refuses
+                                 promotion on a deterministic run that
+                                 skipped any AC (ADR-4112 verified
+                                 invariant).
   --quiet                   Suppress non-error confirmations
   --help                    Print this help
 
@@ -292,6 +317,14 @@ export async function main(argv, deps = {}) {
   if (typeof flags.provision === 'string' && flags.provision.startsWith('-')) {
     return usage('--provision takes a file path, not a flag or inline value (credentials are never accepted inline)');
   }
+  // Issue 330: resolve --mode. Unknown value refuses exit 2 so a typo
+  // ("--mode determinstic") does not silently fall through to the
+  // default agent mode a dispatched worker cannot run.
+  const modeFlag = flags.mode;
+  if (modeFlag !== undefined && !isVerifyMode(modeFlag)) {
+    return usage(`--mode must be one of ${VERIFY_MODES.join(' | ')} (got "${modeFlag}")`);
+  }
+  const mode = modeFlag ?? DEFAULT_VERIFY_MODE;
 
   const projectRoot = await findProjectRoot(cwd);
   if (!projectRoot) {
@@ -361,10 +394,48 @@ export async function main(argv, deps = {}) {
     provision: flags.provision,
     chain: flags.chain,
     persona: flags.persona,
+    mode,
   });
 
+  // Issue 330 partial-report preseed. Verify is a fresh subprocess and
+  // may fail to start (ENOENT, blocked by harness), be killed, or exit
+  // non-zero before it has had the chance to write its own report. In
+  // every one of those cases the ingest step below would otherwise read
+  // ENOENT and finalise would print "could not read the verify report"
+  // with no clue about what the mode or the reason was. Preseeding the
+  // report path with a `{ status: "aborted" }` stub guarantees ingest
+  // always has something to read; a successful verify run overwrites
+  // the stub with its real report in the same path.
+  const finaliseStartedAt = new Date().toISOString();
+  const partialStub = {
+    schemaVersion: '1',
+    verdict: 'LAUNCH-FAILURE',
+    verdictAuthority: null,
+    run: {
+      profile,
+      url: flags.url,
+      startedAt: finaliseStartedAt,
+      finishedAt: null,
+      runStats: { mode, status: 'pending', reason: 'verify not yet started' },
+    },
+    findings: [],
+    blockedAcs: [],
+    launchFailure: {
+      message: 'rcf verify did not write a report (process was killed, errored before write, or did not start)',
+      status: 'aborted',
+      reason: 'preseed',
+    },
+  };
+  const writer = deps.writeFile ?? writeFile;
+  try {
+    await writer(outPath, `${JSON.stringify(partialStub, null, 2)}\n`, 'utf8');
+  } catch (err) {
+    stderr.write(`[finalise] could not preseed partial report at ${outPath}: ${err.message}\n`);
+    return 1;
+  }
+
   if (!quiet) {
-    stdout.write(`[finalise] launching rcf verify run (fresh subprocess) against ${flags.url} [profile=${profile}]...\n`);
+    stdout.write(`[finalise] launching rcf verify run (fresh subprocess) against ${flags.url} [profile=${profile}, mode=${mode}]...\n`);
   }
 
   let spawnResult;
@@ -398,7 +469,13 @@ export async function main(argv, deps = {}) {
     // §9 independence guarantee). An unreadable report on a pass is treated as a
     // HOLD, never a silent promotion (mirrors ingest's "unreadable is not a pass").
     const passLoaded = await (deps.loadReport ? deps.loadReport(outPath, deps) : loadReport(outPath, deps));
-    const authority = passLoaded.ok ? passLoaded.report.verdictAuthority : undefined;
+    // Issue 330: a passing exit code with ONLY the preseed stub on disk
+    // means verify exited 0 without writing its own report; treat
+    // that as unreadable (never a silent promotion). Mirrors the
+    // "unreadable is not a pass" NIT-3 contract.
+    const passPreseedOnly = passLoaded.ok
+      && passLoaded.report?.launchFailure?.reason === 'preseed';
+    const authority = (passLoaded.ok && !passPreseedOnly) ? passLoaded.report.verdictAuthority : undefined;
     if (authority !== 'ship') {
       stderr.write(`[finalise] HOLD: rcf verify passed but this run carries '${authority ?? 'unknown'}' authority, `
         + `not 'ship'; ${fbsId} left '${currentStatus}'.\n`);
@@ -406,8 +483,32 @@ export async function main(argv, deps = {}) {
         + 'runtime is edge-identical to prod - carries ship authority and can promote to verified. '
         + `Report: ${outPath}\n`);
       if (!passLoaded.ok) stderr.write(`[finalise] (the verify report could not be read: ${passLoaded.reason})\n`);
+      else if (passPreseedOnly) stderr.write('[finalise] (the verify report could not be read: verify exited 0 without replacing the preseed stub)\n');
       return 4;
     }
+    // Issue 330 (2026-10-08) deterministic-mode refusal, keyed off the
+    // ADR-4112 verified invariant. A deterministic-mode run never
+    // actively exercises a critique-only AC (every testable AC is
+    // recorded on blockedAcs[] with reason `critique-only`). Promoting
+    // to `verified` off such a run would quietly contradict the ADR
+    // promise. Refuse with a clear counts line; the operator either
+    // re-runs the gate under agentScreenshotCritique from a parent
+    // session, or extends the chain with a per-AC probe shape the
+    // deterministic mode can judge.
+    if (passLoaded.ok) {
+      const runStats = passLoaded.report?.run?.runStats
+        ?? passLoaded.report?.runStats
+        ?? null;
+      if (runStats && runStats.mode === 'deterministic') {
+        const counts = runStats.counts ?? { verified: 0, failed: 0, skipped: 0, total: 0 };
+        if ((counts.skipped ?? 0) > 0 || (counts.verified ?? 0) < (counts.total ?? 0)) {
+          stderr.write(`[finalise] gate NOT promoted: deterministic mode verified ${counts.verified ?? 0} of ${counts.total ?? 0} ACs (skipped ${counts.skipped ?? 0} critique-only); critique mode required to promote ${fbsId} to 'verified'. ADR-4112 verified invariant.\n`);
+          stderr.write("Re-run from a parent session that may spawn the agent CLI ('rcf build finalise ... --mode agentScreenshotCritique'), or extend the chain so every AC carries a deterministic probe shape.\n");
+          stderr.write(`Report: ${outPath}\n`);
+          return 4;
+        }
+      }
+    }
     // 0.7.0 verification-integrity §5.2: the finalise gate reads the
     // verify report's per-AC verdicts and refuses to promote to
     // 'verified' on MOCK-ONLY-DECLARED / BLOCKED-BY-DECLARATION unless
@@ -583,9 +684,47 @@ export async function main(argv, deps = {}) {
   // Gate NOT passed. The FBS stays put; surface the findings from the report
   // (the §5.4 verify -> fix -> re-verify seam), then fail non-zero.
   stderr.write(`[finalise] gate NOT passed (rcf verify exit ${spawnResult.code}); ${fbsId} left '${currentStatus}'.\n`);
+  // Issue 330: if the subprocess exited without replacing the preseed
+  // partial-report stub, overwrite it with an `aborted` record naming
+  // the mode and the exit code so a reader sees why there is no
+  // verdict, not an ENOENT.
   const loaded = await (deps.loadReport ? deps.loadReport(outPath, deps) : loadReport(outPath, deps));
+  const finishedAtAborted = new Date().toISOString();
+  if (loaded.ok && loaded.report?.launchFailure?.reason === 'preseed') {
+    const abortedReport = {
+      ...loaded.report,
+      verdict: 'LAUNCH-FAILURE',
+      verdictAuthority: null,
+      run: {
+        ...(loaded.report.run ?? {}),
+        finishedAt: finishedAtAborted,
+        runStats: {
+          ...((loaded.report.run && loaded.report.run.runStats) || {}),
+          mode,
+          status: 'aborted',
+          reason: `rcf verify exited ${spawnResult.code} without writing a report`,
+          exitCode: spawnResult.code,
+        },
+      },
+      launchFailure: {
+        message: `rcf verify exited ${spawnResult.code} without writing a report (mode=${mode})`,
+        status: 'aborted',
+        reason: `rcf verify exited ${spawnResult.code} without writing a report`,
+      },
+    };
+    try {
+      await writer(outPath, `${JSON.stringify(abortedReport, null, 2)}\n`, 'utf8');
+      loaded.report = abortedReport;
+    } catch (err) {
+      stderr.write(`[finalise] could not overwrite preseed stub at ${outPath}: ${err.message}\n`);
+    }
+  }
   if (loaded.ok) {
     stderr.write(summariseReport(loaded.report));
+    const abortStats = loaded.report?.run?.runStats ?? loaded.report?.runStats ?? null;
+    if (abortStats && abortStats.status === 'aborted') {
+      stderr.write(`[finalise] mode=${abortStats.mode ?? mode}: ${abortStats.reason ?? 'verify produced no report'}\n`);
+    }
     stderr.write(`Full report (build-lite ingestible, chain-node-addressed): ${outPath}\n`);
   } else {
     stderr.write(`[finalise] could not read the verify report: ${loaded.reason}\n`);

package/src/cli/view.js

@@ -272,6 +272,10 @@ export async function main(argv, deps = {}) {
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
   const onSignal = deps.onSignal ?? ((sig, handler) => process.on(sig, handler));
+  // Issue #333 item 2: tests inject a `startServerImpl` to observe the
+  // sinks the CLI wires without racing a real walker; the default is
+  // the real `startServer`.
+  const startServerImpl = deps.startServerImpl ?? startServer;
 
   // Track C+D §9: subverb routing. When the first argv token is
   // `start | status | stop | logs`, dispatch to the lifecycle handler
@@ -315,13 +319,21 @@ export async function main(argv, deps = {}) {
   }
 
   const logSink = opts.verbose ? (line) => stderr.write(`${line}\n`) : () => {};
+  // Issue #333 item 2: a host that spawns `rcf audit view` as a
+  // supervised child without --verbose still needs to see fatal watcher
+  // and walker exceptions, otherwise the viewer looks alive while
+  // live-updates have silently stopped. `logError` is unconditional;
+  // the chatty per-event lines keep flowing through `log` only when
+  // --verbose is on.
+  const logErrorSink = (line) => stderr.write(`${line}\n`);
 
   let server;
   try {
-    server = await startServer({
+    server = await startServerImpl({
       projectRoot,
       port: resolvedPort,
       log: logSink,
+      logError: logErrorSink,
       testHost: resolveTestHost(opts.testHost, env),
     });
   } catch (err) {

package/src/finalise/spawn.js

@@ -31,6 +31,7 @@ import { isolationEnv } from '#core/isolation';
  * @param {string} [opts.provision] - provisioning FILE path
  * @param {string} [opts.chain] - PRD/chain ref
  * @param {string} [opts.persona]
+ * @param {string} [opts.mode] - verify mode (issue 330): agentScreenshotCritique | deterministic
  * @returns {string[]}
  */
 export function buildVerifyArgs(opts) {
@@ -47,6 +48,7 @@ export function buildVerifyArgs(opts) {
   if (opts.parityEnv) args.push('--parity-env');
   if (opts.provision) args.push('--provision', opts.provision);
   if (opts.persona) args.push('--persona', opts.persona);
+  if (opts.mode) args.push('--mode', opts.mode);
   return args;
 }
 

package/src/server/index.js

@@ -4,7 +4,7 @@
 // (D11); EADDRINUSE is a hard failure (D10).
 //
 // Public surface:
-//   startServer({ projectRoot, port, host, log, heartbeatMs, watchImpl })
+//   startServer({ projectRoot, port, host, log, logError, heartbeatMs, watchImpl, renderImpl })
 //     -> Promise<{ url, port, close, hub, currentState }>
 // close() drains SSE with a `shutdown` event and releases the port. The
 // caller (bin/rcf-view.js) is responsible for the 2s force-exit budget
@@ -27,8 +27,16 @@ import { createSseHub } from './sse.js';
  * @property {string} [host='127.0.0.1']
  * @property {number} [heartbeatMs=30000]
  * @property {number} [debounceMs=50]
- * @property {(line: string) => void} [log] - stderr sink
+ * @property {(line: string) => void} [log] - verbose-gated chatty sink;
+ *   defaults to a noop so a caller that does not want chatter can omit it.
+ * @property {(line: string) => void} [logError] - fatal-error sink that is
+ *   always written to, independent of `log`. Issue #333 item 2: the CLI
+ *   wires this to stderr unconditionally so a host that spawned
+ *   `rcf audit view` without --verbose still sees a dead watcher or a
+ *   failed walker. Defaults to `log` for back-compat.
  * @property {typeof defaultWatch} [watchImpl] - injectable watch primitive for tests
+ * @property {typeof renderModelToPage} [renderImpl] - injectable walker
+ *   for tests; defaults to the real `renderModelToPage`.
  * @property {boolean} [testHost=false] - viewer UI refresh PR 9 (TAC-4134,
  *   ADR-4136): when true, mount the wespa host fixture at /test-host.html
  *   plus its embed-client script at /test-host.js. Off by default so
@@ -73,54 +81,96 @@ export async function startServer(args) {
   const heartbeatMs = typeof args.heartbeatMs === 'number' ? args.heartbeatMs : 30000;
   const debounceMs = typeof args.debounceMs === 'number' ? args.debounceMs : 50;
   const log = typeof args.log === 'function' ? args.log : () => {};
+  // Issue #333 item 2: fatal watcher/walker exceptions always surface to
+  // stderr regardless of --verbose; chatty per-event lines stay gated on
+  // `log`. Callers that pass only `log` keep the pre-fix behaviour (one
+  // sink for both chatty and fatal), which the back-compat test asserts.
+  const logError = typeof args.logError === 'function' ? args.logError : log;
   const watchImpl = typeof args.watchImpl === 'function' ? args.watchImpl : defaultWatch;
+  // Issue #333 item 1: tests inject a controllable render promise to
+  // observe the trailing-rewalk coalescing without racing a real walk.
+  const renderImpl = typeof args.renderImpl === 'function' ? args.renderImpl : renderModelToPage;
   const testHost = args.testHost === true;
 
-  /** @type {{ version: number, fullPageHtml: string, contentHtml: string, errors: import('#core/errors').RcfError[] } | null} */
+  /** @type {{ version: number, fullPageHtml: string, contentHtml: string, errors: import('#core/errors').RcfError[], tree?: import('#core/store/walker.js').TreeModel, testPointers?: Map<string, import('#core/store/tp-resolve.js').TestPointerResolution> } | null} */
   let state = null;
   let version = 0;
   let rewalkInFlight = null;
+  // Issue #333 item 1: a change that arrives while a walk is in flight
+  // queues exactly one trailing walk so the post-in-flight on-disk state
+  // is picked up; any number of changes during the in-flight walk collapse
+  // onto that single trailing walk (never dropped, never re-run per call).
+  let rewalkTrailing = false;
   let closed = false;
 
   const sse = createSseHub({ heartbeatMs, log });
 
-  async function rewalk() {
-    if (closed) return;
+  // FBS-207 (TAC-4136 queryCache + AC-208-6): per-version memo for the
+  // three JSON query routes keyed by `${version}:${route}:${pivot}:${d
+  // irection|scope}`. Replaced wholesale on every rewalk so a new tree
+  // never serves stale compute. One compute per key per version; never
+  // persisted; never written under rcf/. Page-lifetime: a reconnected
+  // client sees a fresh cache.
+  /** @type {Map<string, string>} */
+  let queryCache = new Map();
+
+  async function runWalk() {
+    try {
+      const result = await renderImpl({ projectRoot });
+      if (closed) return;
+      version += 1;
+      state = {
+        version,
+        fullPageHtml: result.fullPageHtml,
+        contentHtml: result.contentHtml,
+        errors: result.errors,
+        pmPartials: result.pmPartials,
+        // Viewer UI refresh PR 7 (TAC-4132, ADR-4134): the ID lookup
+        // index is built once per rewalk and snapshotted on `state`
+        // so `GET /index.json` serves from memory and the SSE
+        // `tree-update` version lets the client invalidate its cache.
+        indexJson: result.indexJson,
+        // FBS-207 (TAC-4136, AC-208-6): the walked tree and resolved
+        // test-pointer map snapshotted on state so /trace.json,
+        // /impact.json and /coverage.json compute from the same tree
+        // the page was rendered from. `tree` was already produced by
+        // renderModelToPage; the server now carries it onto state.
+        tree: result.tree,
+        testPointers: result.testPointers,
+      };
+      // FBS-207 (AC-208-6): a new version drops every previous
+      // version's compute entries wholesale, as TAC-4136 specifies.
+      queryCache = new Map();
+      sse.broadcast('tree-update', { version, contentHtml: result.contentHtml });
+      if (result.errors && result.errors.length > 0) {
+        sse.broadcast('walker-error', { errors: result.errors });
+      }
+    } catch (err) {
+      // Fatal walker exception: always to stderr via `logError` so a
+      // host spawning `rcf audit view` without --verbose still sees it
+      // (issue #333 item 2).
+      logError(`[server] walker failed: ${/** @type {Error} */ (err).message}`);
+      sse.broadcast('walker-error', {
+        errors: [{ kind: 'ioFailure', message: /** @type {Error} */ (err).message }],
+      });
+    } finally {
+      const trailing = rewalkTrailing;
+      rewalkTrailing = false;
+      rewalkInFlight = trailing && !closed ? runWalk() : null;
+    }
+  }
+
+  function rewalk() {
+    if (closed) return Promise.resolve();
     if (rewalkInFlight) {
-      // Coalesce concurrent walks. The trailing one will pick up the
-      // final on-disk state; a middle one adds nothing.
-      return rewalkInFlight;
+      // A walk is already running. Flag that a trailing walk is wanted
+      // and return a promise that resolves when the trailing walk (not
+      // the in-flight one) has completed. Any concurrent callers coalesce
+      // onto the same trailing walk - the final on-disk state wins.
+      rewalkTrailing = true;
+      return rewalkInFlight.then(() => rewalkInFlight ?? undefined);
     }
-    rewalkInFlight = (async () => {
-      try {
-        const result = await renderModelToPage({ projectRoot });
-        if (closed) return;
-        version += 1;
-        state = {
-          version,
-          fullPageHtml: result.fullPageHtml,
-          contentHtml: result.contentHtml,
-          errors: result.errors,
-          pmPartials: result.pmPartials,
-          // Viewer UI refresh PR 7 (TAC-4132, ADR-4134): the ID lookup
-          // index is built once per rewalk and snapshotted on `state`
-          // so `GET /index.json` serves from memory and the SSE
-          // `tree-update` version lets the client invalidate its cache.
-          indexJson: result.indexJson,
-        };
-        sse.broadcast('tree-update', { version, contentHtml: result.contentHtml });
-        if (result.errors && result.errors.length > 0) {
-          sse.broadcast('walker-error', { errors: result.errors });
-        }
-      } catch (err) {
-        log(`[server] walker failed: ${/** @type {Error} */ (err).message}`);
-        sse.broadcast('walker-error', {
-          errors: [{ kind: 'ioFailure', message: /** @type {Error} */ (err).message }],
-        });
-      } finally {
-        rewalkInFlight = null;
-      }
-    })();
+    rewalkInFlight = runWalk();
     return rewalkInFlight;
   }
 
@@ -149,6 +199,16 @@ export async function startServer(args) {
   const router = createRouter({
     currentState: () => state,
     sse,
+    // FBS-207 (TAC-4136): the three JSON query routes share one page-
+    // lifetime memo held on the server closure; the router reads and
+    // writes it through this handle. Replaced wholesale on each
+    // rewalk, above.
+    queryCache: {
+      get: (key) => queryCache.get(key),
+      set: (key, value) => { queryCache.set(key, value); },
+      has: (key) => queryCache.has(key),
+      size: () => queryCache.size,
+    },
     // Snapshotted assets take precedence; the legacy path props are
     // still passed so tests that mount the router directly with a
     // path (no asset load) keep working.
@@ -175,7 +235,7 @@ export async function startServer(args) {
     paths: [watchDir],
     onChange: () => { rewalk().catch(() => {}); },
     debounceMs,
-    onError: (err) => { log(`[watch] ${err.message}`); },
+    onError: (err) => { logError(`[watch] ${err.message}`); },
   });
 
   // Bind. EADDRINUSE surfaces as a rejected Promise so the caller can
@@ -236,5 +296,10 @@ export async function startServer(args) {
     currentState: () => state,
     sse,
     rewalk,
+    // FBS-207 (TAC-4136, AC-208-6 test seam): read-only probe on the
+    // page-lifetime memo. Lets the AC-208-6 integration test prove the
+    // rewalk cache SWAP (not just a version-prefixed key change) by
+    // observing size before and after an explicit `rewalk()`.
+    queryCacheSize: () => queryCache.size,
   };
 }