session-orchestrator 5.5.0 → 5.7.0

package/scripts/lib/vault-mirror/retention.mjs

@@ -0,0 +1,388 @@
+/**
+ * retention.mjs — the retention rules shared by the vault mirror
+ * (`process.mjs`, write side) and the bestand pruner
+ * (`scripts/vault-mirror-prune.mjs`, cleanup side). Issue #1513.
+ *
+ * One module, so the mirror and the pruner cannot disagree about what counts
+ * as narrative, as the same insight, as an archived note, or as a rollup row.
+ * String functions plus one read-only directory probe
+ * ({@link canonicalNamespace}); no clock (callers pass `today`).
+ *
+ * ## The rules (deterministic, documented in skills/vault-mirror/SKILL.md)
+ *
+ * - **Narrative gate (sessions).** A session record earns its own note only
+ *   when its FREE-TEXT fields (`notes`, `narrative`, `summary`; strings, or
+ *   arrays of strings) carry at least `min-narrative-chars` characters after
+ *   whitespace collapse. Tables (waves, agents, files, effectiveness) are not
+ *   narrative: they live in `sessions.jsonl` and in git. Calibrated against the
+ *   Jev audit 2026-10-03 (3.003 notes): free text under 300 chars held 1 of
+ *   2.802 notes scored >= 2.5 "information beyond git"; from 800 chars on, 18 of
+ *   55. A record below the gate becomes ONE row in the month rollup
+ *   `50-sessions/<ns>/_rollup-YYYY-MM.md`.
+ * - **Same insight (learnings).** Two notes carry the same learning when their
+ *   `## Insight` sections are equal after {@link normalizeInsight}.
+ * - **Archived, not deleted.** A note that leaves the active set keeps its
+ *   bytes; only `status:` becomes `archived` and an `archived-reason:` line
+ *   names why. `archived` (not `expired`/`superseded`) because the vault
+ *   frontmatter status enum (SSOT projects-baseline, mirrored in
+ *   skills/vault-sync/validator.mjs) has no such values — a status outside it
+ *   fails vault-sync in every vault whose mirror zones are not excluded.
+ *
+ * @module scripts/lib/vault-mirror/retention
+ */
+
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { subjectToSlug } from './utils.mjs';
+
+/** The generator marker every mirror-written note carries. */
+export const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
+
+/** Reasons a note leaves the active zones. Closed set; the manifest uses it. */
+export const ARCHIVE_REASONS = Object.freeze([
+  'expired',
+  'superseded',
+  'duplicate',
+  'metrics-only-session',
+]);
+
+/** Record fields that carry session free text (narrative), in render order. */
+export const SESSION_NARRATIVE_FIELDS = Object.freeze(['notes', 'narrative', 'summary']);
+
+/** Vault-relative archive root; the zone path is appended verbatim. */
+export const ARCHIVE_ROOT = '90-archive/mirror';
+
+/** Rollup filename prefix — `_` keeps it out of the session-note namespace. */
+export const ROLLUP_PREFIX = '_rollup-';
+
+const collapse = (s) => String(s).replace(/\s+/g, ' ').trim();
+
+/**
+ * Narrative character count of a session RECORD (the gate's measure).
+ *
+ * @param {object} entry sessions.jsonl record
+ * @returns {number}
+ */
+/**
+ * The session free text as it is RENDERED into the note's `## Notes` section:
+ * every narrative field (strings and string-array items), in
+ * {@link SESSION_NARRATIVE_FIELDS} order, blank-line separated. One function
+ * for the renderer and the gate, so a record that passes the gate always
+ * renders a note the pruner measures at least as long (#1513 review H2: the
+ * gate counted `narrative`/`summary`, the renderer printed only `notes`, and
+ * the pruner archived the empty note the mirror then re-created).
+ *
+ * @param {object} entry
+ * @returns {string} '' when the record carries no free text
+ */
+export function sessionNarrativeText(entry) {
+  if (!entry || typeof entry !== 'object') return '';
+  const parts = [];
+  for (const field of SESSION_NARRATIVE_FIELDS) {
+    const v = entry[field];
+    const items = typeof v === 'string' ? [v] : Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+    for (const item of items) if (item.trim()) parts.push(item.trim());
+  }
+  return parts.join('\n\n');
+}
+
+export function sessionNarrativeChars(entry) {
+  if (!entry || typeof entry !== 'object') return 0;
+  let total = 0;
+  for (const field of SESSION_NARRATIVE_FIELDS) {
+    const v = entry[field];
+    if (typeof v === 'string') total += collapse(v).length;
+    else if (Array.isArray(v)) {
+      for (const item of v) if (typeof item === 'string') total += collapse(item).length;
+    }
+  }
+  return total;
+}
+
+/**
+ * Narrative character count of a rendered/on-disk session NOTE: the `## Notes`
+ * section, which is where the renderers put the record's `notes` field. The
+ * pruner uses this; it agrees with {@link sessionNarrativeChars} for every note
+ * the v2/v3 renderers wrote.
+ *
+ * @param {string} content
+ * @returns {number}
+ */
+export function noteNarrativeChars(content) {
+  const text = section(content, 'Notes');
+  return text === null ? 0 : collapse(text).length;
+}
+
+/**
+ * Body of a `## <heading>` section up to the next `## ` heading, trimmed.
+ *
+ * @param {string} content
+ * @param {string} heading
+ * @returns {string|null} null when the heading is absent
+ */
+export function section(content, heading) {
+  const lines = String(content ?? '').split('\n');
+  const start = lines.findIndex((l) => l.trimEnd() === `## ${heading}`);
+  if (start === -1) return null;
+  const out = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (lines[i].startsWith('## ')) break;
+    out.push(lines[i]);
+  }
+  return out.join('\n').trim();
+}
+
+/**
+ * Normalise insight text for equality: case, whitespace, trailing punctuation
+ * and typographic quotes/dashes are not content.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function normalizeInsight(text) {
+  return collapse(
+    String(text ?? '')
+      .toLowerCase()
+      .replace(/[‘’]/g, "'")
+      .replace(/[“”]/g, '"')
+      .replace(/[–—]/g, '-'),
+  ).replace(/[\s.;:!,]+$/, '');
+}
+
+/**
+ * Insight texts that are NOT a learning but a placeholder a tool wrote — equal
+ * placeholders say nothing about two notes carrying the same learning (#1513
+ * review M4). Matched against the normalised text.
+ */
+const PLACEHOLDER_INSIGHTS = Object.freeze([
+  /^\(legacy record\b/,
+  /^\(none recorded\)$/,
+  /insight backfilled during/,
+  /^\(no insight\b/,
+  /^(?:n\/a|tbd|todo|unknown|none)$/,
+]);
+
+/** Shorter normalised insights are too generic to identify one learning. */
+export const MIN_INSIGHT_KEY_CHARS = 40;
+
+/**
+ * The dedupe key of an insight text: normalised, or `''` (= never a
+ * duplicate) for placeholders and texts under {@link MIN_INSIGHT_KEY_CHARS}.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function insightDedupeKey(text) {
+  const key = normalizeInsight(text);
+  if (key.length < MIN_INSIGHT_KEY_CHARS) return '';
+  return PLACEHOLDER_INSIGHTS.some((re) => re.test(key)) ? '' : key;
+}
+
+/** Dedupe key of a learning note's `## Insight`, or `''` (see {@link insightDedupeKey}). */
+export function noteInsightKey(content) {
+  return insightDedupeKey(section(content, 'Insight') ?? '');
+}
+
+const dehyphen = (s) => String(s).replace(/-/g, '');
+const hyphenCount = (s) => (String(s).match(/-/g) || []).length;
+
+/**
+ * The hyphen-alias rule, shared by the mirror and the pruner (#1513 review
+ * M2): among namespace folders that are equal modulo hyphens, the one with the
+ * most hyphens is canonical (ties: lexicographic). The repo-identity fallback
+ * that drops hyphens (`GotzendorferV2` → `gotzendorferv2`) and the
+ * remote-derived name (`gotzendorfer-v2`) thereby land in one folder.
+ *
+ * @param {Iterable<string>} folders namespace folder names present
+ * @param {string} ns
+ * @returns {string} the canonical folder for `ns` (`ns` itself when none)
+ */
+export function canonicalAmong(folders, ns) {
+  if (!ns) return ns;
+  let best = ns;
+  for (const f of folders) {
+    if (f === best || dehyphen(f) !== dehyphen(ns)) continue;
+    const better = hyphenCount(f) > hyphenCount(best) || (hyphenCount(f) === hyphenCount(best) && f < best);
+    if (better) best = f;
+  }
+  return hyphenCount(best) > hyphenCount(ns) ? best : ns;
+}
+
+/**
+ * {@link canonicalAmong} over the namespace folders that exist in the vault's
+ * two mirror zones. Read-only; an unreadable zone contributes nothing.
+ *
+ * @param {string} vaultDir
+ * @param {string} ns
+ * @returns {string}
+ */
+export function canonicalNamespace(vaultDir, ns) {
+  if (!ns) return ns;
+  const folders = new Set();
+  for (const zone of ['40-learnings', '50-sessions']) {
+    try {
+      for (const ent of readdirSync(join(vaultDir, zone), { withFileTypes: true })) {
+        if (ent.isDirectory()) folders.add(ent.name);
+      }
+    } catch {
+      /* zone absent */
+    }
+  }
+  return canonicalAmong(folders, ns);
+}
+
+/**
+ * The pre-#725 slug of a v1 subject: `subjectToSlug` WITHOUT the whitespace →
+ * hyphen pre-map, i.e. every space dropped ("3 parallel impl" → "3parallelimpl").
+ * The mirror wrote this form until #725 D1; the current form hyphenates. Used
+ * only to RECOGNISE an existing note, never to name a new one.
+ *
+ * @param {unknown} subject
+ * @returns {string} '' when the subject yields no slug
+ */
+export function legacyConcatSlug(subject) {
+  if (typeof subject !== 'string' || subject.length === 0) return '';
+  return subjectToSlug(subject);
+}
+
+/**
+ * Set a note's frontmatter to archived with a reason. Idempotent: an already
+ * archived note with the same reason comes back byte-identical. Only the first
+ * frontmatter block is touched; the body stays verbatim.
+ *
+ * @param {string} content
+ * @param {string} reason one of {@link ARCHIVE_REASONS}
+ * @returns {string}
+ */
+export function markArchived(content, reason) {
+  const text = String(content ?? '');
+  if (!text.startsWith('---\n')) return text;
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) return text;
+  const fmLines = text.slice(4, end).split('\n');
+  const rest = text.slice(end);
+  let sawStatus = false;
+  const out = [];
+  for (const line of fmLines) {
+    if (/^archived-reason:/.test(line)) continue;
+    if (/^status:/.test(line)) {
+      out.push('status: archived');
+      out.push(`archived-reason: ${reason}`);
+      sawStatus = true;
+      continue;
+    }
+    if (/^tags:\s*\[/.test(line)) {
+      out.push(line.replace(/\bstatus\/[a-z0-9-]+/, 'status/archived'));
+      continue;
+    }
+    out.push(line);
+  }
+  if (!sawStatus) {
+    const genIdx = out.findIndex((l) => l.startsWith('_generator:'));
+    const at = genIdx === -1 ? out.length : genIdx;
+    out.splice(at, 0, 'status: archived', `archived-reason: ${reason}`);
+  }
+  return `---\n${out.join('\n')}${rest}`;
+}
+
+/**
+ * Archive path for a vault-relative note path: the zone path is kept verbatim
+ * under {@link ARCHIVE_ROOT}, so `git log --follow` and the folder shape match.
+ *
+ * @param {string} relPath e.g. `40-learnings/repo/x.md`
+ * @returns {string}
+ */
+export function archivePathFor(relPath) {
+  return `${ARCHIVE_ROOT}/${relPath}`;
+}
+
+// ── Session month rollup ──────────────────────────────────────────────────────
+
+const ROW_RE = /^\| (\d{4}-\d{2}-\d{2}) \| `([^`]+)` \| ([^|]*) \| ([^|]*) \| ([^|]*) \| ([^|]*) \|$/;
+
+/**
+ * Derive one rollup row from a rendered session note (all three renderer
+ * generations print the same `**Type:**` / `**Waves:**` bullets). Reading the
+ * RENDERED note means the mirror and the pruner share one parser.
+ *
+ * @param {string} content rendered or on-disk session note
+ * @param {{id?: string}} [opts] id override (defaults to frontmatter `id`)
+ * @returns {{date: string, id: string, type: string, waves: string, agents: string, files: string}|null}
+ *   null when the note carries no usable date or id
+ */
+export function rollupRowFromNote(content, opts = {}) {
+  const text = String(content ?? '');
+  const fm = (key) => (text.match(new RegExp(`^${key}:\\s*"?([^"\\n]+)"?\\s*$`, 'm')) || [])[1]?.trim() ?? '';
+  const id = opts.id ?? fm('id');
+  const date = (fm('updated') || fm('created')).slice(0, 10);
+  if (!id || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+  const pick = (re) => ((text.match(re) || [])[1] ?? '?').trim().replace(/\|/g, '/');
+  return {
+    date,
+    id,
+    type: pick(/\*\*Type:\*\*\s*([^·\n]+)/),
+    waves: pick(/\*\*Waves:\*\*\s*([^·\n]+)/),
+    agents: pick(/\*\*Agents:\*\*\s*([^·\n]+)/),
+    files: pick(/\*\*Files changed:\*\*\s*([^·\n]+)/),
+  };
+}
+
+/** Vault-relative rollup path for a namespace (`''` = flat) and a `YYYY-MM`. */
+export function rollupRelPath(ns, month) {
+  return ns ? `50-sessions/${ns}/${ROLLUP_PREFIX}${month}.md` : `50-sessions/${ROLLUP_PREFIX}${month}.md`;
+}
+
+/** Parse the rows of an existing rollup note. */
+export function parseRollupRows(content) {
+  const rows = [];
+  for (const line of String(content ?? '').split('\n')) {
+    const m = ROW_RE.exec(line);
+    if (m) rows.push({ date: m[1], id: m[2], type: m[3].trim(), waves: m[4].trim(), agents: m[5].trim(), files: m[6].trim() });
+  }
+  return rows;
+}
+
+/**
+ * Merge rows into a month rollup and render it. Deterministic in its inputs
+ * (rows sorted by date, then id; created/updated from the row dates), so the
+ * same row set always renders the same bytes — the idempotency the mirror's
+ * no-op check and the pruner's re-run rely on.
+ *
+ * @param {string|null} existing current rollup content, or null
+ * @param {Array<object>} rows rows to add (a row with a known id replaces it)
+ * @param {{ns: string, month: string}} where
+ * @returns {string}
+ */
+export function renderRollup(existing, rows, { ns, month }) {
+  const byId = new Map();
+  for (const r of parseRollupRows(existing)) byId.set(r.id, r);
+  for (const r of rows) byId.set(r.id, r);
+  const all = [...byId.values()].sort((a, b) => (a.date === b.date ? a.id.localeCompare(b.id) : a.date.localeCompare(b.date)));
+  const label = ns || 'unsorted';
+  const idSlug = subjectToSlug(`${label}-sessions-rollup-${month}`) || `sessions-rollup-${month}`;
+  const created = all.length > 0 ? all[0].date : `${month}-01`;
+  const updated = all.length > 0 ? all[all.length - 1].date : `${month}-01`;
+  const body = all
+    .map((r) => `| ${r.date} | \`${r.id}\` | ${r.type} | ${r.waves} | ${r.agents} | ${r.files} |`)
+    .join('\n');
+  return `---
+id: ${idSlug}
+type: session
+title: "Sessions ${month} (${label}, metrics only)"
+status: verified
+created: ${created}
+updated: ${updated}
+tags: [session/rollup]
+${ns ? `source-repo: ${ns}\n` : ''}_generator: ${GENERATOR_MARKER}
+---
+
+# Sessions ${month} (${label}, metrics only)
+
+Sessions without narrative (free text below the vault-mirror narrative gate). The full records live in \`.orchestrator/metrics/sessions.jsonl\` of the repo; archived notes, if any, under \`${ARCHIVE_ROOT}/50-sessions/\`.
+
+| Date | Session | Type | Waves | Agents | Files |
+|---|---|---|---|---|---|
+${body}
+`;
+}

package/scripts/lib/vault-status/board-writer.mjs

@@ -662,12 +662,12 @@ export function writeBoard(opts) {
   // which is precisely the surface the `_overview.md` refusal above protects.
   //
   // `copyFileSync` is forwarded even though `backup: false` makes it inert
-  // today: {@link atomicWriteWithBackup} falls back to the REAL `node:fs` per
-  // MISSING method, so a 4-of-5 adapter would silently route the backup copy
-  // to the real filesystem the moment anyone flips `backup` — a test that
-  // believes itself hermetic would drop `.bak-<ISO>` files into the repo.
-  // Forwarding the fifth method keeps the adapter total over io.mjs's
-  // injectable surface.
+  // today: {@link atomicWriteWithBackup} fails CLOSED under `backup: true` when
+  // an injected adapter lacks `existsSync` or `copyFileSync` (it returns
+  // `{ ok: false, reason: 'fs-error' }` before touching any filesystem), so a
+  // 4-of-5 adapter would turn into a failed board write the moment anyone
+  // flips `backup`. Forwarding the fifth method keeps the adapter total over
+  // io.mjs's injectable surface so that flip stays a one-line change.
   const result = atomicWriteWithBackup(outputPath, content, {
     tmpPrefix: '.active-sessions',
     fs: {

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

@@ -734,12 +734,18 @@ function mayCarrySignal(line) {
  * the real on-disk location of the coordinator's own transcript, sibling of
  * the `subagents/` directory this function reads from.
  *
+ * A missing sidecar (ENOENT) is the normal not-yet-written case and stays
+ * silent; any other failure (malformed JSON, EACCES, EISDIR) is reported via
+ * `note()` so an `'unknown'` agent type is traceable to its cause (#1216).
+ *
+ * Exported for tests only.
+ *
  * @param {string} projectsDir
  * @param {string} sessionId
  * @param {string} agentId
  * @returns {string}
  */
-function readAgentType(projectsDir, sessionId, agentId) {
+export function readAgentType(projectsDir, sessionId, agentId) {
   const sidecar = resolveSubagentSidecar({
     transcriptPath: join(projectsDir, `${sessionId}.jsonl`),
     agentId,
@@ -749,7 +755,10 @@ function readAgentType(projectsDir, sessionId, agentId) {
     const meta = JSON.parse(readFileSync(sidecar.meta, 'utf8'));
     const t = meta?.agentType;
     return typeof t === 'string' && t ? t : 'unknown';
-  } catch {
+  } catch (err) {
+    if (err?.code !== 'ENOENT') {
+      note(`agent-type read failed for ${sidecar.meta}: ${String(err?.message ?? err)}`);
+    }
     return 'unknown';
   }
 }

package/scripts/print-applicable-rules.mjs

@@ -98,9 +98,9 @@
 import { parseArgs } from 'node:util';
 import { readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { createHash } from 'node:crypto';
 
 import { findProjectRoot } from './lib/common.mjs';
+import { deriveFenceToken } from './lib/reconcile/sanitize.mjs';
 import { loadApplicableRules } from './lib/rule-loader.mjs';
 import { readHostClass } from './lib/autopilot/telemetry.mjs';
 import { resolveStateArtifactPath, resolveStateMdPath } from './lib/state-md.mjs';
@@ -218,30 +218,6 @@ function neutraliseWrapperForgeries(text) {
   return out;
 }
 
-/**
- * Derive this block's fence token from its own payload.
- *
- * Deterministic by construction (same input → same token), so the CLI's stdout
- * stays reproducible. The re-derivation loop makes the absence guarantee
- * STRUCTURAL rather than probabilistic: a token that literally occurred in the
- * payload would be forgeable in a closing tag, so we re-hash with a counter
- * until it does not occur. Each iteration is a fresh 32-bit draw against a
- * fixed payload, so termination is immediate in practice; the cap exists only
- * so a pathological input cannot spin, and its fallback (the full 64-hex
- * digest, which no realistic rule body contains) still satisfies the guarantee.
- *
- * @param {string} payload - the concatenated rule bodies this token must fence
- * @returns {string} a hex token provably absent from `payload`
- */
-function deriveFenceToken(payload) {
-  const digest = (salt) => createHash('sha256').update(`${salt}\n${payload}`).digest('hex');
-  for (let salt = 0; salt < 64; salt++) {
-    const token = digest(salt).slice(0, 8);
-    if (!payload.includes(token)) return token;
-  }
-  return digest(64);
-}
-
 /**
  * Render a rule's `src` attribute: repo-relative (an absolute path would print
  * the operator's home directory into every agent prompt) and reduced to a

package/scripts/release.mjs

@@ -387,6 +387,10 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // `scripts/lib/locks/index.mjs` is the one-cycle deprecation shim (5.2.0 CHANGELOG, Changed): its
 // runtime warning names the version it was deprecated IN, so it legitimately carries the previous
 // release literal until its 6.0.0 removal — version history by construction, not drift.
+// `site/_census.json` is deliberately NOT allowlisted: it carries a `"version"` field that
+// `--set-version` re-stamps (scripts/site-numbers.mjs --write, see the post-bump hint in main()),
+// so leaving it under the drift sweep makes the sweep double as its staleness gate — a census
+// not re-stamped after a bump fails `--check` instead of shipping the previous version.
 export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|scripts\/lib\/locks\/index\.mjs|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */

package/scripts/validate-wave-scope.mjs

@@ -10,6 +10,7 @@
  *   cat wave-scope.json | node scripts/validate-wave-scope.mjs
  *   node scripts/validate-wave-scope.mjs --assert-subset <agent-filescope.json> < wave-scope.json
  *   node scripts/validate-wave-scope.mjs --assert-disjoint <agent-scopes.json> < wave-scope.json
+ *   node scripts/validate-wave-scope.mjs --assert-disjoint <agent-scopes.json> --no-manifest
  *   node scripts/validate-wave-scope.mjs --union <agent-scopes.json> < wave-scope.json
  *
  * Flags:
@@ -38,6 +39,17 @@
  *                           Runs even when the manifest fails schema validation
  *                           (#1026.4): it reads only the sidecar, so schema
  *                           errors and collisions are reported together (exit 1).
+ *   --no-manifest           #1510 f. With --assert-disjoint ONLY: check the
+ *                           sidecar alone and read NO manifest (no stdin, no
+ *                           positional file) — `/plan` checks disjointness
+ *                           before any wave-scope.json exists and had to pipe
+ *                           a fabricated dummy. Stdout stays EMPTY (there is no
+ *                           manifest to echo); exit 0 = disjoint, 1 = collision.
+ *                           An explicit flag, never inferred from empty stdin:
+ *                           WITHOUT it, empty/missing stdin stays an error
+ *                           (fail-closed, #1083 class). Rejected (exit 1) with
+ *                           --union / --assert-subset / --expand-test-siblings
+ *                           or a positional path — those need a manifest.
  *   --union <path>          #1020. QUERY MODE. Read the same sidecar, compute
  *                           `expandTestSiblings(unionFileScopes(scopes), {role})`
  *                           using the MANIFEST'S OWN `role`, and print the
@@ -161,7 +173,8 @@ function flagValue(argv, i, flag) {
  *
  * @param {string[]} argv - full process.argv
  * @returns {{ assertSubset: string|null, expandTestSiblings: boolean,
- *             assertDisjoint: string|null, union: string|null, positionals: string[] }}
+ *             assertDisjoint: string|null, union: string|null, noManifest: boolean,
+ *             positionals: string[] }}
  */
 function parseArgs(argv) {
   const positionals = [];
@@ -169,6 +182,7 @@ function parseArgs(argv) {
   let expandTestSiblings = false;
   let assertDisjoint = null;
   let union = null;
+  let noManifest = false;
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--expand-test-siblings') {
@@ -185,11 +199,27 @@ function parseArgs(argv) {
     } else if (a === '--union') {
       union = flagValue(argv, i, '--union');
       i++; // consume the value
+    } else if (a === '--no-manifest') {
+      noManifest = true;
     } else {
       positionals.push(a);
     }
   }
-  return { assertSubset, expandTestSiblings, assertDisjoint, union, positionals };
+  if (noManifest) {
+    // #1510 f — every other mode reads the MANIFEST (`role`, `allowedPaths`), so
+    // combining it with "there is no manifest" is a contradiction, not a no-op.
+    if (assertDisjoint === null) die('--no-manifest requires --assert-disjoint <agent-scopes.json>', 1);
+    const needsManifest = [
+      union !== null && '--union',
+      assertSubset !== null && '--assert-subset',
+      expandTestSiblings && '--expand-test-siblings',
+      positionals.length > 0 && `a wave-scope.json path (${positionals[0]})`,
+    ].filter(Boolean);
+    if (needsManifest.length > 0) {
+      die(`--no-manifest cannot be combined with ${needsManifest.join(', ')}: that mode reads the manifest`, 1);
+    }
+  }
+  return { assertSubset, expandTestSiblings, assertDisjoint, union, noManifest, positionals };
 }
 
 /**
@@ -755,7 +785,12 @@ function validate(
   process.stdout.write(input.endsWith('\n') ? input : input + '\n');
 }
 
-const { assertSubset, expandTestSiblings, assertDisjoint, union, positionals } = parseArgs(
+const { assertSubset, expandTestSiblings, assertDisjoint, union, noManifest, positionals } = parseArgs(
   process.argv,
 );
-validate(readInput(positionals[0]), assertSubset, expandTestSiblings, assertDisjoint, union);
+if (noManifest) {
+  // #1510 f — sidecar-only: stdin is never read, so no dummy manifest is needed.
+  assertDisjointOrDie(assertDisjoint);
+} else {
+  validate(readInput(positionals[0]), assertSubset, expandTestSiblings, assertDisjoint, union);
+}