session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/wave-transcript-tail.mjs

@@ -60,6 +60,7 @@ import { pathToFileURL } from 'node:url';
 import { emitEvent, sessionAttribution } from './events.mjs';
 import { tryAcquireFileLock, releaseFileLock } from './file-lock.mjs';
 import { readLock, isLockLive } from './session-lock.mjs';
+import { resolveSubagentSidecar } from '../../hooks/_lib/subagent-paths.mjs';
 
 const DEFAULT_INTERVAL_S = 2;
 const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
@@ -95,9 +96,107 @@ const RE_EMIT_EVERY = 10;
 
 /**
  * git subcommands that mutate the shared index, the stash stack, or remote
- * history — the PSA-007 prohibition list, verbatim.
+ * history — the PSA-007 prohibition list, verbatim. Matching the subcommand
+ * LITERAL is only the first half: the arguments decide whether the invocation
+ * writes anything at all (#1215).
+ *
+ * Group 1 is the subcommand, group 2 the remaining argument string.
+ *
+ * The global-flag run has TWO alternatives on purpose (W4/F2). A bare
+ * `(?:-[^\s]+\s+)*` cannot absorb a VALUE-taking global flag: in
+ * `git -C /tmp stash` the run eats `-C ` and then meets `/tmp`, which is not a
+ * subcommand, so the whole invocation read as NOT a git write — measured 2026-09-04,
+ * `isGitWrite('git -C /tmp stash')` and `isGitWrite('git -c user.name=x commit -m y')`
+ * both returned false. `-C`/`-c`/`--git-dir`/`--work-tree`/`--namespace`/
+ * `--exec-path`/`--config-env` are the value-taking globals; the space-separated
+ * form is matched first, the `--flag=value` form falls through to the generic
+ * alternative unchanged.
+ *
+ * `command git …` and `env VAR=x git …` prefixes are absorbed too — both are
+ * ordinary agent shapes that hid a write behind one token.
+ *
+ * DELIBERATE — `-C <dir>` is NOT treated as fixture context. `FIXTURE_CONTEXT_RE`
+ * keys on `cd /tmp` / `mktemp`, the shapes agents actually write around a test
+ * fixture; teaching it `-C` would hand back the exact one-token evasion this fix
+ * closes (`git -C /tmp/../<repo> commit`). A genuine `git -C "$TMPDIR" commit`
+ * therefore reports — a false alarm on an advisory detector, never a missed breach.
+ *
+ * CEILING (BV-004): the prefix list is enumerated, not general. `sudo git …`,
+ * `nice -n 5 git …` and any other wrapper still hide the write; and a git write
+ * inside `$(…)` or a quoted string was never detected (see `isGitWrite`).
+ * Revisit if a real PSA-007 breach is ever missed through a wrapper.
  */
-const GIT_WRITE_RE = /^\s*git\s+(?:-[^\s]+\s+)*(add|commit|stash|push|mv|rm|reset|checkout\s+--)\b/;
+const GIT_WRITE_RE =
+  /^\s*(?:command\s+|env\s+(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)+)*git\s+(?:(?:-C|-c|--git-dir|--work-tree|--namespace|--exec-path|--config-env)\s+\S+\s+|-[^\s]+\s+)*(add|commit|stash|push|mv|rm|reset|checkout)\b(.*)$/;
+
+/**
+ * `git stash` sub-subcommands that actually touch the stash stack. Bare
+ * `git stash` (no sub-subcommand) is `stash push`, so it counts too; anything
+ * else — `list`, `show`, an unknown word — is a read.
+ */
+const STASH_WRITE_SUBS = new Set([
+  'push',
+  'save',
+  'pop',
+  'apply',
+  'drop',
+  'clear',
+  'branch',
+  'create',
+  'store',
+]);
+
+/**
+ * Argument-aware PSA-007 classification. Decision table (#1215):
+ *
+ * | invocation                        | verdict | why                                    |
+ * |-----------------------------------|---------|----------------------------------------|
+ * | `git stash` / `stash push|save`   | write   | pushes onto the shared stash stack     |
+ * | `stash pop|apply|drop|clear`      | write   | mutates / consumes the stack           |
+ * | `stash branch|create|store`       | write   | creates refs from the stack            |
+ * | `git stash list` / `stash show`   | READ    | capability/inspection probe            |
+ * | `--help` / `-h` / `--version`     | READ    | capability probe, any subcommand       |
+ * | `--dry-run` (any subcommand)      | READ    | prints, never writes                   |
+ * | `-n` on add / rm / mv / push      | READ    | `-n` IS `--dry-run` there              |
+ * | `-n` on commit                    | WRITE   | `-n` is `--no-verify` — a REAL commit  |
+ * | `git checkout -- <path>`          | write   | discards sibling work (destructive)    |
+ * | `git checkout <branch>`           | READ    | no index/worktree content destroyed    |
+ * | `git reset` (any form)            | write   | destructive, kept unconditional        |
+ * | `git add|commit|push|mv|rm` else  | write   | the PSA-007 list, verbatim             |
+ *
+ * The `-n` split is measured, not assumed — `git commit -h` prints
+ * `-n, --no-verify` while `git add -h` / `git rm -h` / `git push -h` all print
+ * `-n, --[no-]dry-run` (measured 2026-09-04, git in this repo's PATH).
+ * Treating `commit -n` as a read would blind the detector to
+ * `git commit --no-verify`, which `parallel-sessions.md` § PSA-007 names as an
+ * anti-pattern verbatim.
+ *
+ * Ceiling: flags are matched as whole tokens after quoted spans are stripped,
+ * so `git commit -m "fix -h"` stays a write. Bundled short flags (`-nv`) and
+ * flags hidden in `$(…)` are not decoded — they read as writes, a false alarm,
+ * never a missed breach. Revisit if agents start writing bundled git flags.
+ *
+ * @param {string} sub — the matched git subcommand
+ * @param {string} rawArgs — everything after it in the segment
+ * @returns {boolean}
+ */
+function gitSegmentWrites(sub, rawArgs) {
+  // Strip quoted spans so a commit message can never supply a read flag.
+  const args = String(rawArgs || '').replace(/"[^"]*"|'[^']*'/g, ' ');
+  const tokens = args.split(/\s+/).filter(Boolean);
+
+  for (const t of tokens) {
+    if (t === '--help' || t === '-h' || t === '--version' || t === '--dry-run') return false;
+    if (t === '-n' && sub !== 'commit') return false;
+  }
+
+  if (sub === 'checkout') return tokens.includes('--');
+  if (sub === 'stash') {
+    const first = tokens.find((t) => !t.startsWith('-'));
+    return first === undefined || STASH_WRITE_SUBS.has(first);
+  }
+  return true;
+}
 
 /**
  * STATUS literals that all report as pattern `status-partial`.
@@ -282,9 +381,22 @@ export function classifyErrorClass(text) {
  * `/private/tmp`, `/var/folders`, `$TMPDIR`). A fixture repo created somewhere
  * else is still reported — a false alarm, never a missed breach. Revisit if
  * agents start seeding fixtures outside these paths.
+ *
+ * #1172: the temp path must also match BARE — the reported false alarm was
+ * `cd /tmp && git init && git commit -m x`, where the old pattern required a
+ * trailing `/` after `/tmp` and therefore saw nothing. The terminator class
+ * (`/`, quote, whitespace, `;`, `&`, `|`, end of string) is what keeps
+ * `cd /tmpfoo` — a real directory that is NOT the temp dir — reported.
+ *
+ * The destructive guard's own temp allowlist (`hooks/pre-bash-destructive-guard.mjs`
+ * `isSafeRmTarget`) is deliberately NOT reused: it exports nothing
+ * (`grep -n "^export" hooks/pre-bash-destructive-guard.mjs` → 0 matches,
+ * measured 2026-09-04) and resolves paths on the filesystem against a loaded
+ * policy, whereas this is a lexical test on a transcript string with no repo
+ * context. Same intent, different substrate.
  */
 const FIXTURE_CONTEXT_RE =
-  /\bmktemp\b|\bcd\s+["']?(?:\/private)?\/(?:tmp|var\/folders)\/|\bcd\s+["']?\$\{?(?:TMPDIR|TMP|SCRATCH)/;
+  /\bmktemp\b|\bcd\s+["']?(?:\/private)?\/(?:tmp|var\/folders)(?:["'\s;&|/]|$)|\bcd\s+["']?\$\{?(?:TMPDIR|TMP|SCRATCH)/;
 
 /**
  * True when the Bash command contains a git INDEX/HISTORY write in ANY
@@ -300,7 +412,10 @@ const FIXTURE_CONTEXT_RE =
 export function isGitWrite(command) {
   const text = String(command || '');
   if (FIXTURE_CONTEXT_RE.test(text)) return false;
-  return text.split(/&&|\|\||;|\||\n/).some((seg) => GIT_WRITE_RE.test(seg));
+  return text.split(/&&|\|\||;|\||\n/).some((seg) => {
+    const m = GIT_WRITE_RE.exec(seg);
+    return m ? gitSegmentWrites(m[1], m[2]) : false;
+  });
 }
 
 /**
@@ -606,13 +721,32 @@ function mayCarrySignal(line) {
 }
 
 /**
- * @param {string} subagentsDir
+ * Read the agent TYPE from the sidecar `agent-<id>.meta.json` the harness
+ * writes next to the subagent transcript. `agentId` here comes from a
+ * `readdirSync()` filename match (tailLoop below), not from untrusted stdin —
+ * but it is validated through the SAME consolidated derivation (#1196) as the
+ * hook-side copies for consistency: an id readdirSync happened to list that
+ * fails `{1,64}`/charset/`'unknown'` short-circuits to the honest `'unknown'`
+ * return, same as any other lookup failure.
+ *
+ * `projectsDir`/`sessionId` reconstruct the PARENT transcript path
+ * (`<projectsDir>/<sessionId>.jsonl`) that `resolveSubagentSidecar()` expects —
+ * the real on-disk location of the coordinator's own transcript, sibling of
+ * the `subagents/` directory this function reads from.
+ *
+ * @param {string} projectsDir
+ * @param {string} sessionId
  * @param {string} agentId
  * @returns {string}
  */
-function readAgentType(subagentsDir, agentId) {
+function readAgentType(projectsDir, sessionId, agentId) {
+  const sidecar = resolveSubagentSidecar({
+    transcriptPath: join(projectsDir, `${sessionId}.jsonl`),
+    agentId,
+  });
+  if (sidecar === null) return 'unknown';
   try {
-    const meta = JSON.parse(readFileSync(join(subagentsDir, `agent-${agentId}.meta.json`), 'utf8'));
+    const meta = JSON.parse(readFileSync(sidecar.meta, 'utf8'));
     const t = meta?.agentType;
     return typeof t === 'string' && t ? t : 'unknown';
   } catch {
@@ -705,7 +839,7 @@ async function tailLoop({ intervalS }) {
       offsets.set(file, tick.offset);
       if (tick.lines.length === 0) continue;
       const agentId = file.slice('agent-'.length, -'.jsonl'.length);
-      if (!agentTypes.has(agentId)) agentTypes.set(agentId, readAgentType(subagentsDir, agentId));
+      if (!agentTypes.has(agentId)) agentTypes.set(agentId, readAgentType(projectsDir, sessionId, agentId));
       for (const line of tick.lines) {
         if (!mayCarrySignal(line)) continue;
         let rec;

package/scripts/materialize-wave-scope.mjs

@@ -13,12 +13,24 @@
  * 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 { 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';
+import {
+  MANIFEST_SESSION_KEYS,
+  manifestSessionBinding,
+} from './lib/session-identity/own-session.mjs';
 
 const HELP = `Usage: node scripts/materialize-wave-scope.mjs --state-dir <dir> --wave <positive-int> [--json]
 
@@ -50,6 +62,9 @@ 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):
@@ -209,7 +224,8 @@ export function validateScopeRecords(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`).
+ * `session_id` — and its human-readable twin `semantic_session_id`; the
+ * pre-#1153 spellings `session` / `semantic_session` are still read).
  *
  * 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
@@ -228,10 +244,12 @@ export function manifestSessionIds(stateDir, readFile = readFileSync) {
     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());
+  // #1153 P2 — the key spellings live in own-session.mjs, which also reads the
+  // pre-#1153 `session`/`semantic_session` names for one transition release.
+  const binding = manifestSessionBinding(manifest);
+  return MANIFEST_SESSION_KEYS.current
+    .map((key) => binding[key])
+    .filter((value) => typeof value === 'string' && value.length > 0);
 }
 
 /**
@@ -368,7 +386,12 @@ export function materializeWaveScope(records, {
 }) {
   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);
@@ -378,8 +401,8 @@ export function materializeWaveScope(records, {
     }
   }
 
-  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'}`);
     }
@@ -396,7 +419,7 @@ export function materializeWaveScope(records, {
   // no aggregate at all — deleting coverage that nothing replaced.
   const { removed, retained } = reconcileOrphans({
     scopeDir,
-    keepIds: records.map(({ id }) => id),
+    keepIds: agentRecords.map(({ id }) => id),
     ownerIds: manifestSessionIds(stateDir, readFile),
     sessionId: session,
     readDir,

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, manifestSessionBinding } 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,150 @@ 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 the manifest's `semantic_session_id` — 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'));
+        // #1153 P2 — key spellings resolved in ONE place (own-session.mjs),
+        // which also reads the pre-#1153 `session` / `semantic_session` names
+        // for one transition release. Absent slots come back as `undefined`.
+        const binding = manifestSessionBinding(manifest);
+        const boundSession = binding.semantic_session_id ?? binding.session_id;
+        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 = binding.semantic_session_id;
+        // #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.
+        //
+        // #1207 — kept hand-rolled rather than calling `attributionForRecord()`
+        // (scripts/lib/events.mjs): that function's contract is `{}`-on-any-
+        // mismatch with no detail, but the stderr diagnostics below (raw id,
+        // lock status, process-local id list) are load-bearing for debugging a
+        // wrongly-bucketed proposal, and attributionForRecord() has no lock-
+        // status channel to source them from (it swallows `readLock()` errors
+        // silently by design). `readLockDetailed()` is used here specifically
+        // for that `.status` field `readLock()` (attributionForRecord's own
+        // primitive) does not return.
+        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_id) — 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/migrate-cold-start-seed.mjs

@@ -143,7 +143,10 @@ if (applyFlag && dryRunFlag) {
   process.exit(1);
 }
 
-// Default is dry-run (matches scripts/migrate-learnings-jsonl.mjs convention).
+// Default is dry-run: a migration script writes only when `--apply` is passed, so an
+// invocation with no flags can never mutate a store. Repo-wide convention for every
+// `scripts/migrate-*` / `scripts/backfill-*` CLI; live example:
+// `scripts/migrate-sessions-jsonl.mjs` (`args.apply = false` default, `--apply` opts in).
 const dryRun = !applyFlag;
 
 // `--repos` is kept as the raw comma-separated string here (split later, at

package/scripts/parse-config.mjs

@@ -3,10 +3,16 @@
  * parse-config.mjs — Parse ## Session Config from CLAUDE.md or AGENTS.md and output validated JSON.
  * Part of Session Orchestrator v3.0.0 (originally parse-config.sh in v2).
  *
- * Usage: node scripts/parse-config.mjs [path/to/CLAUDE.md|AGENTS.md]
+ * Usage: node scripts/parse-config.mjs [--json] [path/to/CLAUDE.md|AGENTS.md]
  *   If no path given, walks up from cwd to find project root and uses its CLAUDE.md (or AGENTS.md).
  *
  * Output: Single JSON object to stdout with ALL config fields (defaults applied).
+ *   `--json` is an explicit NO-OP alias for that default — accepted because
+ *   `docs/session-config-template.md` (lines 13 and 965) documents
+ *   `node scripts/parse-config.mjs --json` as THE validation command, and the
+ *   flag used to be swallowed by the positional-path slot and rejected with
+ *   `File not found: --json` (exit 1). `cli-design.md` § JSON-First Output also
+ *   requires every CLI to accept `--json`.
  * Exit codes: 0 success, 1 error (message to stderr)
  *
  * Unparsable lines inside `## Session Config` (#1097) are reported per line on
@@ -25,6 +31,7 @@ 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 { findUnterminatedComment } from './lib/config/block-preprocess.mjs';
 import { ENFORCEMENT_VALUES } from './lib/config-schema.mjs';
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -93,10 +100,46 @@ function resolveConfigFile(argPath) {
 }
 
 // ---------------------------------------------------------------------------
-// Main
+// Main — argument parsing
 // ---------------------------------------------------------------------------
+//
+// Exactly two recognised flags plus one optional positional path. `--json` is
+// accepted and IGNORED: stdout is already a single JSON object, and the
+// documented validation command passes the flag. Anything else starting with
+// `-` is rejected rather than silently treated as a filename, so a typo cannot
+// masquerade as a missing file.
+
+const HELP_TEXT = `Usage: parse-config.mjs [--json] [path/to/CLAUDE.md|AGENTS.md]
+
+Parse the \`## Session Config\` block from CLAUDE.md (or AGENTS.md) and write
+the validated config to stdout as a single JSON object.
+
+Options:
+  --json     No-op alias for the default output (stdout is always JSON).
+  --help     Show this help and exit 0.
+
+Without a path, walks up from cwd to the project root and uses its CLAUDE.md,
+falling back to AGENTS.md. Exit codes: 0 success, 1 error (message on stderr).
+`;
+
+let argPath = null;
+for (const arg of process.argv.slice(2)) {
+  if (arg === '--help' || arg === '-h') {
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+  } else if (arg === '--json') {
+    // no-op — the default output already IS JSON
+  } else if (arg.startsWith('-')) {
+    process.stderr.write(`parse-config.mjs: Unknown option: ${arg}\n\n${HELP_TEXT}`);
+    process.exit(1);
+  } else if (argPath === null) {
+    argPath = arg;
+  } else {
+    process.stderr.write(`parse-config.mjs: Unexpected extra argument: ${arg}\n\n${HELP_TEXT}`);
+    process.exit(1);
+  }
+}
 
-const argPath = process.argv[2] ?? null;
 const configFile = resolveConfigFile(argPath);
 
 let content;
@@ -107,6 +150,20 @@ try {
   process.exit(1);
 }
 
+// Unterminated-comment gate — ONE line per session, not one per parser.
+// An `<!--` with no `-->` after it would put the shared HTML-comment skipper in
+// the swallowing state for the rest of the document; `stripHtmlCommentBlocks`
+// now fails CLOSED (returns the lines unfiltered) rather than letting every
+// later block disappear into its defaults, but the operator still has to learn
+// that the document has a defect. This is the surface that says so — never
+// fatal, exit code unchanged.
+const unterminatedCommentLine = findUnterminatedComment(content.split(/\r?\n/));
+if (unterminatedCommentLine !== null) {
+  process.stderr.write(
+    `⚠ ${parsePath(configFile).base}: unterminated <!-- at line ${unterminatedCommentLine} — comment stripping disabled for the whole document\n`,
+  );
+}
+
 let config;
 try {
   config = parseSessionConfig(content);

package/scripts/promote-vault-strict.mjs

@@ -23,6 +23,7 @@ import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
+import { expandTilde } from './lib/common.mjs';
 
 const COMMIT_MSG = 'chore(orchestrator): Promote vault-integration to strict mode — refs #305';
 
@@ -53,18 +54,6 @@ const noBaseline = args.includes('--no-baseline');
 const repoIdx = args.indexOf('--repo');
 const singleRepo = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : null;
 
-// ---------------------------------------------------------------------------
-// Path resolution
-// ---------------------------------------------------------------------------
-
-/** Expand leading ~ to the user's home directory. */
-function expandHome(p) {
-  if (p.startsWith('~/')) {
-    return join(homedir(), p.slice(2));
-  }
-  return p;
-}
-
 // ---------------------------------------------------------------------------
 // Vault-integration mode replacement
 // ---------------------------------------------------------------------------
@@ -424,7 +413,7 @@ async function main() {
 
   if (singleRepo) {
     // Single-repo mode
-    const absRepo = expandHome(singleRepo);
+    const absRepo = expandTilde(singleRepo);
     const singleRoot = getConfinementRoot();
     const singleGuard = validatePathInsideProject(absRepo, singleRoot);
     if (!singleGuard.ok) {
@@ -449,7 +438,7 @@ async function main() {
 
     const batchRoot = getConfinementRoot();
     for (const rawPath of eligibleRepos) {
-      const absRepo = expandHome(rawPath);
+      const absRepo = expandTilde(rawPath);
       const guard = validatePathInsideProject(absRepo, batchRoot);
       if (!guard.ok) {
         process.stderr.write(
@@ -469,7 +458,7 @@ async function main() {
         (p) => p === 'projects-baseline' || p.endsWith('/projects-baseline')
       );
       if (baselineEntry) {
-        const baselineRepoDir = expandHome(
+        const baselineRepoDir = expandTilde(
           baselineEntry.startsWith('~') || baselineEntry.startsWith('/')
             ? baselineEntry
             : `~/Projects/${baselineEntry}`