session-orchestrator 3.22.0 → 3.24.0

package/scripts/materialize-wave-scope.mjs

@@ -9,12 +9,24 @@
  * each bare `files` array first, then writes the complete record array as the
  * aggregate sidecar consumed by validate-wave-scope's --assert-disjoint and
  * --union modes.
+ *
+ * After the aggregate is published, per-agent declarations left behind by an
+ * earlier materialization of the SAME wave are reconciled away (#1103) — but
+ * only against a proven session owner. See {@link reconcileOrphans}.
+ *
+ * PEER RECORDS (`peer-session-*`, #1195) get NO per-agent file: shape (a) is
+ * `$AGENT_FILESCOPE_JSON`, addressed by an agent id at dispatch time, and no
+ * agent is ever dispatched for a peer session — nothing reads it. They are
+ * still written into the aggregate, where `--assert-disjoint` and
+ * `hooks/post-bash-write-verify.mjs` do read them; `--union` excludes them so
+ * `allowedPaths` never grants a peer's territory to this wave's agents.
  */
 
-import { readFileSync, unlinkSync } from 'node:fs';
+import { readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeJsonAtomicSync } from './lib/io.mjs';
+import { isPeerRecordId } from './lib/scope-gate.mjs';
 
 const HELP = `Usage: node scripts/materialize-wave-scope.mjs --state-dir <dir> --wave <positive-int> [--json]
 
@@ -27,7 +39,12 @@ Required:
                       Positive wave number used in filescopes/wave-N/.
 
 Options:
-  --json              Emit {ok, aggregatePath, perAgentPaths} to stdout.
+  --session <id>      This session's id (session_id or its semantic twin). Used
+                      ONLY to prove ownership before an orphaned per-agent
+                      declaration of the same wave is removed (#1103). Without
+                      it, orphans are reported and RETAINED, never deleted.
+  --json              Emit {ok, aggregatePath, perAgentPaths, removedOrphans,
+                      retainedOrphans} to stdout.
   -h, --help          Show this help and exit 0.
 
 Output:
@@ -41,8 +58,17 @@ Examples:
 
 Writes:
   <state-dir>/filescopes/wave-N/<id>.json       Bare string[] for each record
+                      EXCEPT a peer-session-* record (#1195), which is
+                      aggregate-only: no agent is dispatched for it, so nothing
+                      would read its per-agent file.
   <state-dir>/filescopes/wave-N.scopes.json     Aggregate [{id, files}, ...]
 
+Removes (only with a proven owner — see --session):
+  <state-dir>/filescopes/wave-N/<stale-id>.json Per-agent declarations of this
+                      wave whose id is absent from the new record array. An
+                      orphan that cannot be proven owned is named on stderr and
+                      LEFT IN PLACE; that is a WARN, never a failure.
+
 Exit codes:
   0  All declaration files and the aggregate sidecar were written.
   1  Usage or input validation error; no write was attempted.
@@ -55,11 +81,12 @@ class WriteError extends Error {}
 
 /**
  * @param {string[]} argv
- * @returns {{ stateDir: string, wave: number, json: boolean, help: boolean }}
+ * @returns {{ stateDir: string, wave: number, session: string|null, json: boolean, help: boolean }}
  */
 export function parseCliArgs(argv) {
   let stateDir;
   let waveRaw;
+  let session = null;
   let json = false;
   let help = false;
 
@@ -73,7 +100,7 @@ export function parseCliArgs(argv) {
       help = true;
       continue;
     }
-    if (arg === '--state-dir' || arg === '--wave') {
+    if (arg === '--state-dir' || arg === '--wave' || arg === '--session') {
       const value = argv[index + 1];
       if (value === undefined || value.startsWith('--')) {
         throw new InputError(`${arg} requires a value`);
@@ -81,6 +108,12 @@ export function parseCliArgs(argv) {
       if (arg === '--state-dir') {
         if (stateDir !== undefined) throw new InputError('--state-dir may be specified only once');
         stateDir = value;
+      } else if (arg === '--session') {
+        if (session !== null) throw new InputError('--session may be specified only once');
+        // An empty or whitespace-only id proves nothing and must not be read as
+        // an owner: it would make every orphan deletable by any caller.
+        if (value.trim().length === 0) throw new InputError('--session must be a non-empty id');
+        session = value.trim();
       } else {
         if (waveRaw !== undefined) throw new InputError('--wave may be specified only once');
         waveRaw = value;
@@ -91,7 +124,7 @@ export function parseCliArgs(argv) {
     throw new InputError(`unknown argument: ${arg}`);
   }
 
-  if (help) return { stateDir: '', wave: 0, json, help: true };
+  if (help) return { stateDir: '', wave: 0, session, json, help: true };
   if (stateDir === undefined) throw new InputError('--state-dir is required');
   if (waveRaw === undefined) throw new InputError('--wave is required');
   if (stateDir.length === 0 || /[\0\r\n]/.test(stateDir)) {
@@ -103,7 +136,7 @@ export function parseCliArgs(argv) {
 
   const wave = Number(waveRaw);
   if (!Number.isSafeInteger(wave)) throw new InputError('--wave must be a safe positive integer');
-  return { stateDir, wave, json, help: false };
+  return { stateDir, wave, session, json, help: false };
 }
 
 /**
@@ -183,6 +216,141 @@ export function validateScopeRecords(value) {
   return value;
 }
 
+
+/**
+ * Read the session ids the sibling manifest `<state-dir>/wave-scope.json`
+ * declares for this state directory (#1123 wrote both `session` — the raw
+ * `session_id` — and its human-readable twin `semantic_session`).
+ *
+ * A caller may legitimately hold either spelling, so BOTH are returned and a
+ * match against either proves ownership. Any failure to read or parse the
+ * manifest returns an empty list, which the caller must treat as "ownership NOT
+ * established" — never as "no owner, therefore mine".
+ *
+ * @param {string} stateDir
+ * @param {typeof readFileSync} [readFile]
+ * @returns {string[]}
+ */
+export function manifestSessionIds(stateDir, readFile = readFileSync) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFile(resolve(stateDir, 'wave-scope.json'), 'utf8'));
+  } catch {
+    return [];
+  }
+  if (!isRecord(manifest)) return [];
+  return ['session', 'semantic_session']
+    .map((key) => manifest[key])
+    .filter((value) => typeof value === 'string' && value.trim().length > 0)
+    .map((value) => value.trim());
+}
+
+/**
+ * Reconcile per-agent declarations left behind by an earlier materialization of
+ * the SAME wave (#1103).
+ *
+ * The write loop is a pure upsert over the new id set, so a file whose id was
+ * dropped from the plan survives: it is in no aggregate — `--assert-disjoint`
+ * and `--union` cannot see it — while every by-id consumer (FILE-SCOPE
+ * injection, the Learnings-Index, `--assert-subset`) still reads it. A live
+ * scope claim with zero aggregate coverage.
+ *
+ * ## Why this is NOT a directory wipe
+ *
+ * The wave number is not a session-unique key: two sessions sharing one working
+ * copy both call their first wave `wave-1` and both resolve to
+ * `<state-dir>/filescopes/wave-1/`. Clearing the directory would convert a
+ * stale-read bug into cross-session data loss — the class
+ * `.claude/rules/parallel-sessions.md` PSA-003 forbids by name ("Did I create
+ * this file? If not, it is not mine to touch"). So removal needs a two-part
+ * test, and only the second part is about the file:
+ *
+ *   1. the id is absent from the new record array (it is an orphan), AND
+ *   2. this invocation can PROVE it owns the state directory — `sessionId`
+ *      matches an id the sibling manifest declares.
+ *
+ * Failing (2) is not an error and never blocks: the orphan is returned in
+ * `retained` WITH its reason so the caller can name the file. A silent skip is
+ * the one outcome forbidden here, because it is byte-identical to a clean run.
+ *
+ * ## Named ceiling (BV-004)
+ *
+ * Bounded by WHEN materialization runs, not by what it inspects: a session that
+ * re-materializes wave N *while its own agents are still in flight* would delete
+ * the scope files those agents are reading. That is safe today only because
+ * `skills/wave-executor/wave-loop.md` § Scope Manifest 3.2 places
+ * (re-)materialization strictly PRE-dispatch, so no reader exists yet. REVISIT
+ * TRIGGER: any caller that materializes a wave after its dispatch has begun — a
+ * mid-wave scope amendment, a repair pass reusing the same wave number, or a
+ * dispatch loop that re-runs the materializer per agent. Ownership does not
+ * protect against that case; the ordering does.
+ *
+ * @param {object} params
+ * @param {string} params.scopeDir           `<state-dir>/filescopes/wave-N`
+ * @param {string[]} params.keepIds          ids present in the new record array
+ * @param {string[]} params.ownerIds         session ids the manifest declares
+ * @param {string|null} params.sessionId     this invocation's session id
+ * @param {typeof readdirSync} [params.readDir]
+ * @param {typeof unlinkSync} [params.removeFile]
+ * @returns {{removed: string[], retained: Array<{file: string, reason: string}>}}
+ */
+export function reconcileOrphans({
+  scopeDir,
+  keepIds,
+  ownerIds,
+  sessionId,
+  readDir = readdirSync,
+  removeFile = unlinkSync,
+}) {
+  let entries;
+  try {
+    entries = readDir(scopeDir, { withFileTypes: true });
+  } catch {
+    // No directory yet (first materialization) or unreadable — nothing to
+    // reconcile. Not a failure: the aggregate is already published.
+    return { removed: [], retained: [] };
+  }
+
+  // Case-INSENSITIVE keep set. validateScopeRecords already rejects two ids that
+  // differ only in case within one input, so this cannot hide a real orphan —
+  // but on a case-insensitive filesystem `A2.json` and `a2.json` are ONE file,
+  // and deleting the "orphan" would delete the declaration just written.
+  const keep = new Set(keepIds.map((id) => `${id}.json`.toLowerCase()));
+  const orphans = [];
+  for (const entry of entries) {
+    if (typeof entry?.isFile === 'function' && !entry.isFile()) continue;
+    const name = typeof entry === 'string' ? entry : entry?.name;
+    if (typeof name !== 'string' || !name.endsWith('.json')) continue;
+    if (keep.has(name.toLowerCase())) continue;
+    orphans.push(name);
+  }
+  if (orphans.length === 0) return { removed: [], retained: [] };
+
+  const proven = typeof sessionId === 'string' && sessionId.length > 0 && ownerIds.includes(sessionId);
+  if (!proven) {
+    const reason = sessionId === null || sessionId === undefined
+      ? 'no --session given, so this state directory has no provable owner'
+      : ownerIds.length === 0
+        ? 'wave-scope.json declares no session, so ownership cannot be established'
+        : `wave-scope.json is owned by a different session (${ownerIds.join(' / ')})`;
+    return { removed: [], retained: orphans.map((file) => ({ file, reason })) };
+  }
+
+  const removed = [];
+  const retained = [];
+  for (const file of orphans) {
+    try {
+      removeFile(resolve(scopeDir, file));
+      removed.push(file);
+    } catch (error) {
+      // A failed unlink leaves a live orphan behind — report it, never throw:
+      // the aggregate is already published and the materialization succeeded.
+      retained.push({ file, reason: `could not remove: ${error instanceof Error ? error.message : String(error)}` });
+    }
+  }
+  return { removed, retained };
+}
+
 /**
  * Materialize validated declarations in their required write order.
  *
@@ -193,13 +361,30 @@ export function validateScopeRecords(value) {
  * has succeeded.
  *
  * @param {Array<{id: string, files: string[]}>} records
- * @param {{ stateDir: string, wave: number, writeJson?: typeof writeJsonAtomicSync }} options
- * @returns {{ aggregatePath: string, perAgentPaths: string[] }}
+ * @param {{ stateDir: string, wave: number, session?: string|null,
+ *          writeJson?: typeof writeJsonAtomicSync,
+ *          readDir?: typeof readdirSync, removeFile?: typeof unlinkSync,
+ *          readFile?: typeof readFileSync }} options
+ * @returns {{ aggregatePath: string, perAgentPaths: string[],
+ *             removedOrphans: string[], retainedOrphans: Array<{file: string, reason: string}> }}
  */
-export function materializeWaveScope(records, { stateDir, wave, writeJson = writeJsonAtomicSync }) {
+export function materializeWaveScope(records, {
+  stateDir,
+  wave,
+  session = null,
+  writeJson = writeJsonAtomicSync,
+  readDir = readdirSync,
+  removeFile = unlinkSync,
+  readFile = readFileSync,
+}) {
   const scopeDir = resolve(stateDir, 'filescopes', `wave-${wave}`);
   const aggregatePath = resolve(stateDir, 'filescopes', `wave-${wave}.scopes.json`);
-  const perAgentPaths = records.map(({ id }) => resolve(scopeDir, `${id}.json`));
+  // #1195 — peer records are aggregate-only (see the header note): no reader
+  // exists for a per-agent file that no dispatch will ever address. Excluding
+  // them from `keepIds` below also lets a stale `peer-session-*.json` written
+  // before this rule be reconciled away like any other orphan.
+  const agentRecords = records.filter((r) => !isPeerRecordId(r.id));
+  const perAgentPaths = agentRecords.map(({ id }) => resolve(scopeDir, `${id}.json`));
 
   try {
     unlinkSync(aggregatePath);
@@ -209,8 +394,8 @@ export function materializeWaveScope(records, { stateDir, wave, writeJson = writ
     }
   }
 
-  for (let index = 0; index < records.length; index++) {
-    const result = writeJson(perAgentPaths[index], records[index].files, { tmpPrefix: '.materialize-wave-scope' });
+  for (let index = 0; index < agentRecords.length; index++) {
+    const result = writeJson(perAgentPaths[index], agentRecords[index].files, { tmpPrefix: '.materialize-wave-scope' });
     if (!result?.ok) {
       throw new WriteError(`cannot write per-agent declaration ${perAgentPaths[index]}: ${result?.error ?? 'unknown write failure'}`);
     }
@@ -220,7 +405,21 @@ export function materializeWaveScope(records, { stateDir, wave, writeJson = writ
   if (!aggregateResult?.ok) {
     throw new WriteError(`cannot write aggregate declaration ${aggregatePath}: ${aggregateResult?.error ?? 'unknown write failure'}`);
   }
-  return { aggregatePath, perAgentPaths };
+
+  // #1103 — strictly AFTER the aggregate write. The aggregate is this command's
+  // publication marker (see the write-order note above), so reconciling before
+  // it would remove a live declaration while the run could still fail and leave
+  // no aggregate at all — deleting coverage that nothing replaced.
+  const { removed, retained } = reconcileOrphans({
+    scopeDir,
+    keepIds: agentRecords.map(({ id }) => id),
+    ownerIds: manifestSessionIds(stateDir, readFile),
+    sessionId: session,
+    readDir,
+    removeFile,
+  });
+
+  return { aggregatePath, perAgentPaths, removedOrphans: removed, retainedOrphans: retained };
 }
 
 /**
@@ -256,10 +455,24 @@ export function main() {
       return;
     }
     const records = validateScopeRecords(readStdinJson());
-    const { aggregatePath, perAgentPaths } = materializeWaveScope(records, args);
+    const { aggregatePath, perAgentPaths, removedOrphans, retainedOrphans } =
+      materializeWaveScope(records, args);
+
+    // stderr carries ONLY the anomalous cases. Measured constraint, not taste:
+    // the corpus pins byte-empty stderr on this command's success path
+    // (tests/scripts/materialize-wave-scope.test.mjs and
+    // tests/integration/wave-scope-producer.test.mjs), and a wave with no
+    // orphans IS the success path. Both lists always reach --json.
+    for (const file of removedOrphans) {
+      process.stderr.write(`materialize-wave-scope: removed orphaned declaration ${file} (id absent from this wave's records)\n`);
+    }
+    for (const { file, reason } of retainedOrphans) {
+      process.stderr.write(`materialize-wave-scope: WARN orphaned declaration ${file} RETAINED — ${reason}\n`);
+    }
+
     process.stdout.write(
       args.json
-        ? `${JSON.stringify({ ok: true, aggregatePath, perAgentPaths })}\n`
+        ? `${JSON.stringify({ ok: true, aggregatePath, perAgentPaths, removedOrphans, retainedOrphans })}\n`
         : `${aggregatePath}\n`,
     );
   } catch (error) {

package/scripts/mcp-server.sh

@@ -40,9 +40,18 @@ text_content() {
 # ---------------------------------------------------------------------------
 # Verify jq is available (fatal — we cannot parse JSON without it)
 # ---------------------------------------------------------------------------
+# The diagnostic goes to STDERR, never stdout. A `{"id":null,"error":...}` line
+# on stdout is NOT a valid `initialize` response, so the client reports the same
+# opaque "connection closed: initialize response" it reports when the script
+# cannot be found at all — the two failure modes were indistinguishable
+# (GH Kanevry/session-orchestrator#64). A named, actionable stderr line keeps
+# them apart. Same shape as hooks/run-node.sh's Node-missing diagnostic.
 if ! command -v jq >/dev/null 2>&1; then
-  # Emit a single error and exit; without jq we cannot operate
-  printf '{"jsonrpc":"2.0","id":null,"error":{"code":-32603,"message":"jq is required but not found in PATH"}}\n'
+  {
+    echo "session-orchestrator: 'jq' not found in PATH — the MCP server did not start."
+    echo "  Fix: install jq (macOS: brew install jq · Debian/Ubuntu: apt-get install jq), then restart the client."
+    echo "  (MCP server shells do not source ~/.zshrc, so a jq that works in your terminal can still be invisible here.)"
+  } >&2
   exit 1
 fi
 

package/scripts/memory-propose.mjs

@@ -46,6 +46,8 @@ import { dirname, join, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { isWaveAgentContext, WAVE_AGENT_ENV_VAR, WAVE_AGENT_ENV_VALUE } from './lib/wave-context.mjs';
+import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
+import { readLockDetailed } from './lib/session-lock.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants & defaults
@@ -259,11 +261,14 @@ const confidence = confidenceVal;
 
 let frontmatter = {};
 let stateMdReadOk = false;
+/** Directory holding STATE.md — the same state-dir the wave manifest lives in (#1166). */
+let stateDir = null;
 
 try {
   // resolveStateMdPath from state-md.mjs: falls back to .claude/STATE.md
   const stateMdMod = await import('./lib/state-md.mjs');
   const stateMdPath = stateMdMod.resolveStateMdPath(process.cwd());
+  stateDir = dirname(stateMdPath);
 
   if (!existsSync(stateMdPath)) {
     if (!dryRun) {
@@ -352,17 +357,136 @@ if (!dryRun && (currentWaveRaw === undefined || currentWaveRaw === null || curre
 }
 
 // ---------------------------------------------------------------------------
-// Step 3 — Build wave ID from STATE.md current-wave (guaranteed present by 2c
-// when !dryRun; falls back to a 'W-dryrun' placeholder under --dry-run when
-// STATE.md was absent/unparseable/missing the field — #741.3)
+// Step 3 — Build the RUNNING wave ID (#1166)
 // ---------------------------------------------------------------------------
+//
+// #1166 — two writers, two semantics: `skills/wave-executor/wave-loop.md` § 3a
+// writes STATE.md `current-wave` = the JUST-COMPLETED wave, while the
+// coordinator's `<state-dir>/wave-scope.json` carries `wave` = the RUNNING
+// wave. Stamping proposals off `current-wave` verbatim filed every wave-N+1
+// proposal into the W<N> quota bucket. Priority: the manifest ONLY when it is
+// bound to THIS session, else `current-wave + 1`. An UNBOUND manifest is not
+// trusted (#1177 FX1) — since #1123 both writers stamp the binding, so a
+// binding-less manifest is a peer's or a stale artefact.
+//
+// The session binding compares `manifest.semantic_session` — the SEMANTIC label
+// — against the semantic id looked up in `session.lock`, and that lookup is only
+// honoured when this PROCESS's own raw session id equals the lock's raw
+// `session_id` (#1188). STATE.md's `session` field is NOT a witness here: it is
+// written by the lock owner, so under a peer's lock both "sides" name the peer.
+
+/** @returns {string|undefined} */
+function resolveRunningWaveId() {
+  if (stateDir !== null) {
+    try {
+      const manifestPath = join(stateDir, 'wave-scope.json');
+      if (existsSync(manifestPath)) {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        const boundSession = manifest?.semantic_session ?? manifest?.session;
+        const unbound =
+          boundSession === undefined || boundSession === null || boundSession === '';
+        // BOTH sides must be non-empty strings. `undefined === undefined` is
+        // true, so a STATE.md WITHOUT a `session` key previously "matched" any
+        // manifest whose `semantic_session` was also absent-but-present-in-the
+        // -comparison — adopting a foreign coordinator's wave number as its own.
+        const mineSide = manifest?.semantic_session;
+        // #1188 — STATE.md is a working-copy artefact of the LOCK OWNER, not a
+        // process-local witness: when a peer holds the lock the peer wrote BOTH
+        // STATE.md and the manifest, so the two "independent" sides agree about
+        // the PEER. Same class as #1177 FX1; same shape as attributionForRecord
+        // (scripts/lib/events.mjs): the lock is a raw->semantic LOOKUP,
+        // authorised by a process-local match on the RAW id. Measured
+        // 2026-09-02: a wave-agent process carries the COORDINATOR's raw uuid in
+        // CLAUDE_CODE_SESSION_ID and no semantic id at all, so comparing the
+        // process-local id against `semantic_session` directly never matches.
+        // CEILING (BV-004): a harness exporting no session id (Codex CLI,
+        // Cursor) resolves no process-local id -> binding unprovable ->
+        // current-wave + 1 fallback with a stderr line. REVISIT if that fallback
+        // rate is measured non-trivial in events.jsonl.
+        const lock = readLockDetailed({ repoRoot: process.cwd() });
+        const processLocal = readProcessLocalSessionIds();
+        const lockRaw =
+          lock.status === 'ok' ? String(lock.lock.session_id ?? '').trim() : '';
+        const authorised = lockRaw !== '' && processLocal.includes(lockRaw);
+        const oursSide = authorised ? (lock.lock.semantic_session_id ?? '') : '';
+        if (!authorised) {
+          // A SILENT non-match is the exact failure mode this fix exists to make
+          // visible: without this line, a proposal bucketed by the fallback is
+          // indistinguishable from one bucketed by a trusted manifest.
+          process.stderr.write(
+            `⚠ memory-propose: session binding unprovable (session.lock ${lock.status}` +
+              `${lockRaw ? `, raw ${lockRaw}` : ''}; process-local ids: ` +
+              `${processLocal.length > 0 ? processLocal.join(', ') : 'none'}) — ` +
+              'ignoring wave-scope.json, falling back to current-wave + 1\n',
+          );
+        }
+        const mine =
+          typeof mineSide === 'string' && mineSide.length > 0 &&
+          typeof oursSide === 'string' && oursSide.length > 0 &&
+          mineSide === oursSide;
+        // An UNBOUND manifest is NOT trusted (#1177 FX1). It used to be, as
+        // "legacy" — but since #1123 BOTH writers stamp the binding, so a
+        // manifest without one today is a PEER's or a stale artefact, and
+        // trusting it files this session's proposals into a foreign quota
+        // bucket. Unbound → say so once on stderr and fall back.
+        if (unbound) {
+          process.stderr.write(
+            'memory-propose: wave-scope.json unbound (no semantic_session) — ignored\n',
+          );
+        }
+        if (mine) {
+          const raw = manifest?.wave;
+          const num =
+            typeof raw === 'number'
+              ? raw
+              : typeof raw === 'string' && raw.trim() !== ''
+                ? Number(raw)
+                : NaN;
+          if (Number.isInteger(num)) return `W${num}`;
+        }
+      }
+    } catch (err) {
+      // Unreadable / malformed manifest → fall through to the +1 fallback, but
+      // SAY SO. A swallowed parse error makes a wrongly-bucketed proposal look
+      // like ordinary fallback behaviour; the operator then has no signal that
+      // the coordinator's own manifest is corrupt. Diagnostics on stderr keeps
+      // the stdout JSON contract intact (cli-design.md § JSON-First Output).
+      process.stderr.write(
+        `⚠ memory-propose: cannot read ${join(stateDir, 'wave-scope.json')} ` +
+          `(${err?.message ?? String(err)}) — falling back to current-wave + 1\n`,
+      );
+    }
+  }
+
+  if (currentWaveRaw === undefined || currentWaveRaw === null || currentWaveRaw === '') {
+    return undefined;
+  }
+  const completed = Number(currentWaveRaw);
+  if (!Number.isFinite(completed)) return undefined; // never 'WNaN'
+  // CEILING (BV-004): `+1` assumes waves run consecutively and that STATE.md is
+  // maintained — it is WRONG when a wave is skipped, when the plan is adapted
+  // mid-session, or under `persistence: false` where `current-wave` never
+  // advances. It is the fallback precisely because wave-scope.json is the only
+  // artefact that KNOWS the running wave.
+  // REVISIT when a wave-scope.json manifest is present in every dispatch (then
+  // delete the fallback and reject instead), or when a proposal is observed in
+  // the wrong quota bucket while the manifest was readable.
+  return `W${completed + 1}`;
+}
+
+const resolvedWaveId = resolveRunningWaveId();
 
-const frontmatterWaveId =
-  currentWaveRaw !== undefined && currentWaveRaw !== null && currentWaveRaw !== ''
-    ? `W${currentWaveRaw}`
-    : undefined;
+if (!dryRun && resolvedWaveId === undefined) {
+  exit(
+    {
+      status: STATUS.REJECTED_WRONG_CONTEXT,
+      detail: `Cannot resolve the running wave: no usable wave-scope.json and STATE.md 'current-wave' is not numeric (got '${currentWaveRaw}')`,
+    },
+    3,
+  );
+}
 
-const waveId = dryRun ? (frontmatterWaveId ?? 'W-dryrun') : frontmatterWaveId;
+const waveId = dryRun ? (resolvedWaveId ?? 'W-dryrun') : resolvedWaveId;
 
 // ---------------------------------------------------------------------------
 // Step 4 — Read Session Config (quota + floor)

package/scripts/parse-config.mjs

@@ -9,6 +9,11 @@
  * Output: Single JSON object to stdout with ALL config fields (defaults applied).
  * Exit codes: 0 success, 1 error (message to stderr)
  *
+ * Unparsable lines inside `## Session Config` (#1097) are reported per line on
+ * stderr under `enforcement: warn` (the default) and refuse the run under
+ * `enforcement: strict`; `off` is silent. stdout is unchanged for any
+ * well-formed block — a warning never alters the emitted JSON.
+ *
  * Environment:
  *   SO_CONFIG_FILE             — override filename (e.g. "AGENTS.md") resolved from project root
  *   SO_SKIP_CONFIG_VALIDATION  — set to "1" to bypass validate-config.mjs
@@ -19,6 +24,8 @@ import { spawnSync } from 'node:child_process';
 import { join, dirname, resolve, parse as parsePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseSessionConfig } from './lib/config.mjs';
+import { collectUnparsableLines } from './lib/config/section-extractor.mjs';
+import { ENFORCEMENT_VALUES } from './lib/config-schema.mjs';
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -108,6 +115,64 @@ try {
   process.exit(1);
 }
 
+// ---------------------------------------------------------------------------
+// Unparsable-line gate (#1097) — never a silent default
+// ---------------------------------------------------------------------------
+//
+// A line inside `## Session Config` that no parser can read is simply absent
+// from the KV map, and every consumer then applies its own default — `false`
+// for the booleans. A broken key therefore reads exactly like a deliberately
+// disabled feature, in every log, forever. This gate is the only place that
+// difference is ever stated out loud.
+//
+// It runs BEFORE the validator so a malformed block is reported in terms of the
+// FILE (line number + text) rather than in terms of the defaults it silently
+// produced. `off` stays silent by definition — that is what turning enforcement
+// off means; `warn` (the default) reports and proceeds; `strict` refuses.
+
+const unparsableLines = collectUnparsableLines(content);
+
+if (unparsableLines.length > 0) {
+  // Belt-and-braces, not a live branch: `parseSessionConfig` already REFUSES
+  // an out-of-vocabulary enforcement value above (measured: `enforcement:
+  // banana` exits 1 with "must be strict|warn|off" and never reaches here), so
+  // `config.enforcement` is one of the three by the time this line runs. The
+  // fallback exists for the direction that matters if that ever loosens — an
+  // unknown value must degrade to `warn`, never arm the `strict` refusal.
+  const enforcement = ENFORCEMENT_VALUES.has(config.enforcement) ? config.enforcement : 'warn';
+
+  if (enforcement !== 'off') {
+    // Ceiling: 20 named lines. A whole prose section pasted into the block is
+    // one defect, not 200, and the strict path below exits immediately after
+    // writing — Node's stderr is async on a pipe, so an unbounded list is the
+    // write-then-exit truncation class this repo has already paid for once.
+    // Revisit if a legitimate config block ever carries >20 broken lines.
+    const SHOWN = 20;
+    for (const { line, text } of unparsableLines.slice(0, SHOWN)) {
+      process.stderr.write(
+        `parse-config.mjs: WARN unparsable Session Config line ${line}: ${text}\n`,
+      );
+    }
+    if (unparsableLines.length > SHOWN) {
+      process.stderr.write(
+        `parse-config.mjs: WARN … and ${unparsableLines.length - SHOWN} more unparsable line(s)\n`,
+      );
+    }
+    process.stderr.write(
+      `parse-config.mjs: ${unparsableLines.length} unparsable line(s) in ${configFile} — ` +
+        'those keys fall back to their defaults, which for booleans is `false`.\n',
+    );
+  }
+
+  if (enforcement === 'strict') {
+    process.stderr.write(
+      'parse-config.mjs: enforcement: strict — refusing to emit config parsed from an ' +
+        'unparsable Session Config block.\n',
+    );
+    process.exit(1);
+  }
+}
+
 // jq -n produces pretty-printed JSON without a trailing newline — match that format
 const assembledJson = JSON.stringify(config, null, 2);