session-orchestrator 4.1.0 → 5.0.0

package/scripts/materialize-wave-scope.mjs

@@ -22,7 +22,7 @@
  * `allowedPaths` never grants a peer's territory to this wave's agents.
  */
 
-import { readdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeJsonAtomicSync } from './lib/io.mjs';
@@ -49,6 +49,12 @@ Options:
                       it, orphans are reported and RETAINED, never deleted.
   --json              Emit {ok, aggregatePath, perAgentPaths, removedOrphans,
                       retainedOrphans} to stdout.
+  --warn-missing      Warn on stderr about absent concrete scope paths, resolved
+                      from the project working directory (not --state-dir).
+                      Glob/prefix grants containing * or ending / are skipped.
+  --new-file <path>   Suppress a missing-path warning for an intended new file.
+                      Repeatable; each path must exactly match a declared scope
+                      path and pass scope validation, even without --warn-missing.
   -h, --help          Show this help and exit 0.
 
 Output:
@@ -85,13 +91,16 @@ class WriteError extends Error {}
 
 /**
  * @param {string[]} argv
- * @returns {{ stateDir: string, wave: number, session: string|null, json: boolean, help: boolean }}
+ * @returns {{ stateDir: string, wave: number, session: string|null, json: boolean,
+ *             warnMissing: boolean, newFiles: string[], help: boolean }}
  */
 export function parseCliArgs(argv) {
   let stateDir;
   let waveRaw;
   let session = null;
   let json = false;
+  let warnMissing = false;
+  const newFiles = [];
   let help = false;
 
   for (let index = 0; index < argv.length; index++) {
@@ -100,16 +109,22 @@ export function parseCliArgs(argv) {
       json = true;
       continue;
     }
+    if (arg === '--warn-missing') {
+      warnMissing = true;
+      continue;
+    }
     if (arg === '--help' || arg === '-h') {
       help = true;
       continue;
     }
-    if (arg === '--state-dir' || arg === '--wave' || arg === '--session') {
+    if (arg === '--state-dir' || arg === '--wave' || arg === '--session' || arg === '--new-file') {
       const value = argv[index + 1];
       if (value === undefined || value.startsWith('--')) {
         throw new InputError(`${arg} requires a value`);
       }
-      if (arg === '--state-dir') {
+      if (arg === '--new-file') {
+        newFiles.push(value);
+      } else if (arg === '--state-dir') {
         if (stateDir !== undefined) throw new InputError('--state-dir may be specified only once');
         stateDir = value;
       } else if (arg === '--session') {
@@ -128,7 +143,7 @@ export function parseCliArgs(argv) {
     throw new InputError(`unknown argument: ${arg}`);
   }
 
-  if (help) return { stateDir: '', wave: 0, session, json, help: true };
+  if (help) return { stateDir: '', wave: 0, session, json, warnMissing, newFiles, 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)) {
@@ -140,7 +155,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, session, json, help: false };
+  return { stateDir, wave, session, json, warnMissing, newFiles, help: false };
 }
 
 /**
@@ -157,18 +172,17 @@ function isRecord(value) {
  * are rejected because no scope consumer can safely interpret them verbatim.
  *
  * @param {unknown} value
- * @param {number} recordIndex
- * @param {number} fileIndex
+ * @param {string} description
  */
-function validateScopePath(value, recordIndex, fileIndex) {
+function validateScopePath(value, description) {
   if (typeof value !== 'string' || value.length === 0 || value.trim().length === 0) {
-    throw new InputError(`record #${recordIndex} files[${fileIndex}] must be a non-empty string`);
+    throw new InputError(`${description} must be a non-empty string`);
   }
   if (/[\0\r\n]/.test(value)) {
-    throw new InputError(`record #${recordIndex} files[${fileIndex}] must not contain NUL or newline characters`);
+    throw new InputError(`${description} must not contain NUL or newline characters`);
   }
   if (value.split(/[\\/]+/).includes('..')) {
-    throw new InputError(`record #${recordIndex} files[${fileIndex}] must not contain path traversal`);
+    throw new InputError(`${description} must not contain path traversal`);
   }
 }
 
@@ -210,7 +224,7 @@ export function validateScopeRecords(value) {
       throw new InputError(`record #${recordIndex} (${record.id}) must have a files string array`);
     }
     for (let fileIndex = 0; fileIndex < record.files.length; fileIndex++) {
-      validateScopePath(record.files[fileIndex], recordIndex, fileIndex);
+      validateScopePath(record.files[fileIndex], `record #${recordIndex} files[${fileIndex}]`);
     }
   }
 
@@ -220,6 +234,42 @@ export function validateScopeRecords(value) {
   return value;
 }
 
+/**
+ * Validate exceptions before any published declarations can be invalidated.
+ * Keep exact spelling: these are diagnostic exceptions, never scope rewrites.
+ *
+ * @param {string[]} newFiles
+ * @param {Array<{id: string, files: string[]}>} records
+ * @returns {Set<string>}
+ */
+function validateNewFiles(newFiles, records) {
+  const declared = new Set(records.flatMap(({ files }) => files));
+  for (const file of newFiles) {
+    validateScopePath(file, '--new-file');
+    if (!declared.has(file)) throw new InputError(`--new-file path is not declared in scope records: ${file}`);
+  }
+  return new Set(newFiles);
+}
+
+/**
+ * Missing-file diagnostics are opt-in and never change scope grants or stdout.
+ * `*` and trailing `/` are the scope consumer's glob/prefix grammar; `?` and
+ * braces are literal names (scripts/lib/scope-gate.mjs isGlobScopeEntry).
+ *
+ * @param {Array<{id: string, files: string[]}>} records
+ * @param {Set<string>} newFiles
+ */
+function warnMissingPaths(records, newFiles) {
+  for (const { id, files } of records) {
+    for (const file of files) {
+      if (newFiles.has(file) || file.includes('*') || file.endsWith('/')) continue;
+      if (!existsSync(resolve(file))) {
+        process.stderr.write(`materialize-wave-scope: WARN ${id}: declared path not found: ${file}\n`);
+      }
+    }
+  }
+}
+
 
 /**
  * Read the session ids the sibling manifest `<state-dir>/wave-scope.json`
@@ -462,14 +512,18 @@ export function main() {
       return;
     }
     const records = validateScopeRecords(readStdinJson());
+    const newFiles = validateNewFiles(args.newFiles, records);
     const { aggregatePath, perAgentPaths, removedOrphans, retainedOrphans } =
       materializeWaveScope(records, args);
 
+    if (args.warnMissing) warnMissingPaths(records, newFiles);
+
     // 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.
+    // orphans IS the success path unless missing-path diagnostics are explicitly
+    // requested above. Both orphan 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`);
     }

package/scripts/mcp-server.sh

@@ -194,8 +194,20 @@ tool_session_metrics() {
   local entries
   entries=$(jq -R -c 'fromjson? | select(.status != "abandoned")' "$metrics_file" 2>/dev/null | tail -n 5) || true
 
+  # Report the stubs the filter above dropped (#1296) — counted over the WHOLE
+  # file, not the tail, with the same torn-line tolerance (`fromjson?`, plus
+  # `.status?` so a non-object line cannot abort the count either). Computed
+  # BEFORE the empty check: a stubs-only ledger is not an empty file.
+  local stub_count
+  stub_count=$(jq -R -n '[inputs | fromjson? | select(.status? == "abandoned")] | length' "$metrics_file" 2>/dev/null) || stub_count=0
+  [[ -z "$stub_count" ]] && stub_count=0
+
   if [[ -z "$entries" ]]; then
-    respond "$id" "$(text_content "No metrics found (file is empty)")"
+    if [[ "$stub_count" -gt 0 ]]; then
+      respond "$id" "$(text_content "No real sessions (abandoned stubs excluded: ${stub_count})")"
+    else
+      respond "$id" "$(text_content "No metrics found (file is empty)")"
+    fi
     return
   fi
 
@@ -229,6 +241,9 @@ tool_session_metrics() {
     ' 2>/dev/null) || token_summary=""
 
   local output
+  entries="${entries}
+
+abandoned stubs excluded: ${stub_count}"
   if [[ -n "$token_summary" ]]; then
     output="${entries}
 

package/scripts/print-applicable-rules.mjs

@@ -11,9 +11,9 @@
  * it to each dispatched agent's prompt.
  *
  * Resolution:
- *   - scopePaths ← `allowedPaths` from `.claude/wave-scope.json`
+ *   - scopePaths ← `allowedPaths` from the active harness wave-scope.json
  *                  (override: --wave-scope <path>)
- *   - mode       ← `session-type:` frontmatter in `.claude/STATE.md`
+ *   - mode       ← `session-type:` frontmatter in the active harness STATE.md
  *                  (override: --mode <m>; unreadable → null = no mode gating)
  *   - hostClass  ← `host_class` from `.orchestrator/host.json` via readHostClass
  *                  (override: --host-class <c>; unreadable → null = no gating)
@@ -103,6 +103,7 @@ import { createHash } from 'node:crypto';
 import { findProjectRoot } from './lib/common.mjs';
 import { loadApplicableRules } from './lib/rule-loader.mjs';
 import { readHostClass } from './lib/autopilot/telemetry.mjs';
+import { resolveStateArtifactPath, resolveStateMdPath } from './lib/state-md.mjs';
 
 // ---------------------------------------------------------------------------
 // EPIPE hardening (regression follow-up on #876)
@@ -136,10 +137,10 @@ as an injectable Markdown block, for the wave-executor to prepend to each
 dispatched agent's prompt (#336 / #694).
 
 Options:
-  --wave-scope <path>   Path to wave-scope.json (default: .claude/wave-scope.json).
+  --wave-scope <path>   Path to wave-scope.json (default: active harness, then legacy).
                         Its "allowedPaths" array is used as scopePaths.
   --mode <m>            Override session mode (default: session-type: from
-                        .claude/STATE.md; unreadable -> no mode gating).
+                        active harness STATE.md; unreadable -> no mode gating).
   --host-class <c>      Override host class (default: host_class from
                         .orchestrator/host.json; unreadable -> no gating).
   --context <c>         Caller context for tier gating: 'wave' | 'coordinator'.
@@ -322,8 +323,8 @@ const repoRoot = findProjectRoot(process.cwd());
 const rulesDir = join(repoRoot, '.claude', 'rules');
 const waveScopePath = opts['wave-scope']
   ? opts['wave-scope']
-  : join(repoRoot, '.claude', 'wave-scope.json');
-const stateMdPath = join(repoRoot, '.claude', 'STATE.md');
+  : resolveStateArtifactPath(repoRoot, 'wave-scope.json');
+const stateMdPath = resolveStateMdPath(repoRoot);
 const hostJsonPath = join(repoRoot, '.orchestrator', 'host.json');
 
 // ---------------------------------------------------------------------------

package/scripts/print-learnings-index.mjs

@@ -101,6 +101,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { findProjectRoot } from './lib/common.mjs';
+import { resolveStateArtifactPath } from './lib/state-md.mjs';
 import {
   CANDIDATE_POOL_SIZE,
   DEFAULT_MAX_GLOBAL,
@@ -141,7 +142,7 @@ Options:
                         agent's declared "Files:" scope. Preferred input.
                         Unreadable or malformed -> exit 1.
   --wave-scope <path>   Fallback scope source; reads "allowedPaths" (default:
-                        .claude/wave-scope.json). An EXPLICIT path that is
+                        active harness, then legacy). An EXPLICIT path that is
                         unreadable/malformed -> exit 1; the DEFAULT path being
                         absent -> stderr diagnostic + empty scope, exit 0.
   --task-text <text>    Optional agent task title/description. Feeds the token
@@ -314,7 +315,7 @@ if (scopePaths.length === 0) {
   const waveScopeExplicit = Boolean(opts['wave-scope']);
   const waveScopePath = waveScopeExplicit
     ? opts['wave-scope']
-    : join(repoRoot, '.claude', 'wave-scope.json');
+    : resolveStateArtifactPath(repoRoot, 'wave-scope.json');
   const doc = readJsonOrNull(waveScopePath, waveScopeExplicit, '--wave-scope');
   if (doc === null) {
     note(`wave-scope not found at ${waveScopePath} — using empty scope`);

package/scripts/release.mjs

@@ -378,8 +378,13 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // (same 2026-09-07 sweep): site/llms-full.txt ("The v4.0.0 release REMOVES public surfaces" — its
 // version SURFACE is checked separately by the SURFACES row, so the sweep on it is redundant),
 // skills/architecture/references/domain-model.md ("Merged here in v4.0.0"), skills/autopilot/SKILL.md
-// ("4.0.0 — see docs/migration-v4.md") and templates/_shared/journey-manifest.md ("Retired … in 4.0.0").
-export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|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|templates\/_shared\/journey-manifest\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|commands\/release\.md)/;
+// ("4.0.0 — see docs/migration-v4.md"). A fifth, templates/_shared/journey-manifest.md ("Retired …
+// in 4.0.0"), was DELETED on 2026-09-12 (replaced by ux-manifest.template.md, Epic #1322) and its
+// allowlist entry went with it — re-add only if a file of that name returns.
+// September 10 campaign snapshot: inputs and receipt reproduce the dated 4.3-planned
+// render made while 4.2.0 was current. Exact files only; neighboring marketing
+// remains checked. Do not bump receipt props without a newly reviewed render.
+export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|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|commands\/release\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */
 export function checkLeakage(lines) {

package/scripts/session-shape.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * session-shape.mjs — the mechanical caller for the session-shape resolution.
+ *
+ * ## Why a CLI
+ *
+ * `scripts/lib/session-shape.mjs` holds the shape AND its telemetry. A library
+ * with no entrypoint is the repo's standing disease (built, not wired): its only
+ * caller would be a fenced code block in a skill file, which no process runs.
+ * Both `sessionType` and `profile` exist only AFTER the session-start Q&A
+ * resolves, and no hook event fires at that moment — so the caller has to be
+ * something the coordinator RUNS with the answers it just received, i.e. this
+ * file. Same shape as its sibling `scripts/express-path.mjs` (#1146).
+ *
+ * ## Usage
+ *
+ *   node scripts/session-shape.mjs --repo-root <path> --session-type <type> \
+ *        [--profile ultradeep] [--known-scope true|false] [--task-count <n>] \
+ *        [--config-file <path>] [--no-event]
+ *
+ * Output: ONE JSON line on stdout — the shape verbatim. Always JSON, so there is
+ * no `--json` flag, matching `express-path.mjs` and `parse-config.mjs`. Human
+ * diagnostics go to stderr.
+ *
+ * Exit codes (`.claude/rules/cli-design.md`):
+ *   0 — the shape RESOLVED. Read it from stdout.
+ *   1 — user/input error: missing/invalid --repo-root, --session-type, --profile,
+ *       --known-scope, --task-count, or an unknown flag.
+ *   2 — config I/O error: an unreadable or unparseable config file.
+ *
+ * `--repo-root` is REQUIRED and is never filled from `SO_PROJECT_DIR`: the
+ * library refuses that fallback for a measured reason (#941 — an ambient
+ * destination put a synthetic record into the operator's real fleet ledger), and
+ * a CLI that quietly supplied one would reinstate exactly what it refuses.
+ *
+ * A config file that EXISTS but cannot be read or parsed exits 2 — it carries
+ * `agents-per-wave`, and guessing past an unreadable cap would publish a shape
+ * with the wrong agent budget. A config file that is simply ABSENT is not an
+ * error: the documented defaults apply and a WARN goes to stderr.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { resolveInstructionFile } from './lib/common.mjs';
+import { parseSessionConfig } from './lib/config.mjs';
+import { resolveAndRecordSessionShape } from './lib/session-shape.mjs';
+
+const USAGE = [
+  'Usage: node scripts/session-shape.mjs --repo-root <path> --session-type <housekeeping|feature|deep>',
+  '                                      [--profile ultradeep] [--known-scope true|false]',
+  '                                      [--task-count <n>] [--config-file <path>] [--no-event]',
+  '',
+  '  --repo-root     REQUIRED  repo receiving the .orchestrator/metrics/events.jsonl record',
+  '  --session-type  REQUIRED  housekeeping | feature | deep',
+  '  --profile       optional  ultradeep (a wave-shape variant on top of --session-type deep)',
+  '  --known-scope   optional  true|false; deep only — true drops the Discovery wave',
+  '  --task-count    optional  agreed issue/task scope (non-negative integer), recorded only',
+  '  --config-file   optional  defaults to SO_CONFIG_FILE, else CLAUDE.md / AGENTS.md under --repo-root',
+  '  --no-event      optional  resolve without writing the ledger record (planning dry-run)',
+  '',
+  'stdout: one JSON line — the resolved shape',
+  'Exit codes: 0 resolved, 1 input error, 2 config I/O error',
+].join('\n');
+
+/** User/input error — usage class. */
+const EXIT_INPUT = 1;
+/** System error — config could not be read or parsed. */
+const EXIT_CONFIG_IO = 2;
+
+/**
+ * Write a diagnostic line to stderr. stdout carries the shape and nothing else
+ * (`cli-design.md` § JSON-First).
+ *
+ * @param {string} message
+ * @returns {void}
+ */
+function warn(message) {
+  process.stderr.write(`session-shape: ${message}\n`);
+}
+
+/**
+ * Fail with a usage-class diagnostic and the given exit code.
+ *
+ * @param {string} message
+ * @param {number} code
+ * @returns {never}
+ */
+function fail(message, code) {
+  warn(message);
+  process.exit(code);
+}
+
+/**
+ * Resolve the config file to read, anchored at `--repo-root`.
+ *
+ * The CLAUDE.md → AGENTS.md walk is `resolveInstructionFile()` in
+ * `scripts/lib/common.mjs` — the SSOT for the instruction-file alias rule — and
+ * is deliberately not re-implemented here. Only the `SO_CONFIG_FILE` override
+ * that `scripts/parse-config.mjs` honours is layered on top, plus an explicit
+ * `--config-file`, which wins outright. Anchoring at `repoRoot` rather than
+ * walking up from cwd keeps a DIFFERENT repo's config out of this shape.
+ *
+ * @param {string} repoRoot
+ * @param {string|undefined} explicit
+ * @returns {string|null}
+ */
+function resolveRepoConfigPath(repoRoot, explicit) {
+  if (explicit) {
+    const abs = resolve(explicit);
+    if (!existsSync(abs)) fail(`config file not found: ${explicit}`, EXIT_CONFIG_IO);
+    return abs;
+  }
+
+  if (process.env.SO_CONFIG_FILE) {
+    const override = join(repoRoot, process.env.SO_CONFIG_FILE);
+    if (existsSync(override)) return override;
+  }
+
+  return resolveInstructionFile(repoRoot)?.path ?? null;
+}
+
+/**
+ * Read and parse the Session Config. Returns `undefined` when no config file
+ * exists, so the library applies its documented defaults.
+ *
+ * @param {string|null} configFile
+ * @returns {object|undefined}
+ */
+function loadConfig(configFile) {
+  if (configFile === null) {
+    warn('no CLAUDE.md / AGENTS.md under --repo-root; applying documented defaults');
+    return undefined;
+  }
+
+  let content;
+  try {
+    content = readFileSync(configFile, 'utf8');
+  } catch (err) {
+    fail(`failed to read ${configFile}: ${err.message}`, EXIT_CONFIG_IO);
+  }
+
+  try {
+    return parseSessionConfig(content);
+  } catch (err) {
+    fail(`failed to parse ${configFile}: ${err.message}`, EXIT_CONFIG_IO);
+  }
+}
+
+/**
+ * Parse a boolean flag value. Strict on purpose: a typo'd `--known-scope yes`
+ * silently meaning `false` would drop or keep a whole Discovery wave.
+ *
+ * @param {string|undefined} raw
+ * @param {string} flag
+ * @returns {boolean|undefined}
+ */
+function parseBoolFlag(raw, flag) {
+  if (raw === undefined) return undefined;
+  const value = String(raw).trim().toLowerCase();
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return fail(`${flag} must be "true" or "false" (got: ${raw})`, EXIT_INPUT);
+}
+
+async function main() {
+  /** @type {{values: Record<string, string|boolean>}} */
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: process.argv.slice(2),
+      options: {
+        'repo-root': { type: 'string' },
+        'session-type': { type: 'string' },
+        profile: { type: 'string' },
+        'known-scope': { type: 'string' },
+        'task-count': { type: 'string' },
+        'config-file': { type: 'string' },
+        'no-event': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+      },
+      allowPositionals: false,
+    });
+  } catch (err) {
+    fail(`${err.message}\n\n${USAGE}`, EXIT_INPUT);
+  }
+
+  const { values } = parsed;
+
+  if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    process.exit(0);
+  }
+
+  const repoRootArg = typeof values['repo-root'] === 'string' ? values['repo-root'].trim() : '';
+  if (repoRootArg === '') {
+    fail(`--repo-root is required (never defaulted from SO_PROJECT_DIR)\n\n${USAGE}`, EXIT_INPUT);
+  }
+  const repoRoot = resolve(repoRootArg);
+  if (!existsSync(repoRoot) || !statSync(repoRoot).isDirectory()) {
+    // A typo'd root would otherwise be CREATED by the emitter's mkdir, leaving
+    // an orphan `.orchestrator/metrics/` tree that answers no question.
+    fail(`--repo-root is not an existing directory: ${repoRootArg}`, EXIT_INPUT);
+  }
+
+  const sessionType =
+    typeof values['session-type'] === 'string' ? values['session-type'].trim() : '';
+  if (sessionType === '') {
+    fail(`--session-type is required\n\n${USAGE}`, EXIT_INPUT);
+  }
+
+  const profileArg = typeof values.profile === 'string' ? values.profile.trim() : '';
+  const profile = profileArg === '' ? null : profileArg;
+
+  const knownScope = parseBoolFlag(
+    typeof values['known-scope'] === 'string' ? values['known-scope'] : undefined,
+    '--known-scope',
+  );
+
+  let taskCount = null;
+  const taskCountRaw = typeof values['task-count'] === 'string' ? values['task-count'].trim() : '';
+  if (taskCountRaw !== '') {
+    taskCount = Number(taskCountRaw);
+    if (!Number.isInteger(taskCount) || taskCount < 0) {
+      fail(`--task-count must be a non-negative integer (got: ${taskCountRaw})`, EXIT_INPUT);
+    }
+  }
+
+  const configFile = resolveRepoConfigPath(
+    repoRoot,
+    typeof values['config-file'] === 'string' ? values['config-file'] : undefined,
+  );
+  const config = loadConfig(configFile);
+
+  let shape;
+  try {
+    shape = await resolveAndRecordSessionShape({
+      repoRoot,
+      config,
+      sessionType,
+      profile,
+      knownScope: knownScope === true,
+      taskCount,
+      emit: values['no-event'] !== true,
+    });
+  } catch (err) {
+    // The library throws TypeError on an unknown session type or profile —
+    // that is an INPUT error here, not a crash. Its message already carries the
+    // `session-shape: ` prefix that `warn()` adds, so strip the inner one:
+    // `session-shape: session-shape: unknown sessionType …` reads as a bug in
+    // the tool rather than a typo in the flag.
+    if (err instanceof TypeError) fail(err.message.replace(/^session-shape:\s*/, ''), EXIT_INPUT);
+    throw err;
+  }
+
+  process.stdout.write(`${JSON.stringify(shape)}\n`);
+}
+
+// Entrypoint guard — importing this file must not run it (check-unwired-features S3).
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  main().catch((err) => {
+    process.stderr.write(`session-shape: unexpected error: ${err?.stack ?? err}\n`);
+    process.exit(EXIT_CONFIG_IO);
+  });
+}

package/skills/_shared/config-reading.md

@@ -54,18 +54,22 @@ Store the JSON output as `$CONFIG` for use throughout this skill — extract fie
 
 ### Handling `agents-per-wave` Overrides
 
-`agents-per-wave` may be a plain integer (`6`) or a JSON object with session-type overrides (`{"default": 6, "deep": 18}`). To get the effective value for the current session type:
+`agents-per-wave` may be a plain integer (`6`) or a JSON object with session-type overrides (`{"default": 6, "deep": 18}`). Do NOT resolve it with a hand-written `jq` expression — use `resolveAgentCap(cap, sessionType)` from `scripts/lib/session-shape.mjs`, the one exported resolver:
+
+```js
+import { resolveAgentCap } from './scripts/lib/session-shape.mjs';
+const effective = resolveAgentCap(config['agents-per-wave'], sessionType); // number | null
+```
+
+From a shell, the same answer arrives inside the resolved shape (`waves[].agentCap`):
 
 ```bash
-# Plain integer → use directly. Object → check for session-type override, fall back to .default
-APW=$(echo "$CONFIG" | jq -r '."agents-per-wave"')
-if echo "$APW" | jq -e 'type == "object"' > /dev/null 2>&1; then
-  EFFECTIVE_APW=$(echo "$APW" | jq -r --arg st "$SESSION_TYPE" '.[$st] // .default')
-else
-  EFFECTIVE_APW="$APW"
-fi
+node scripts/session-shape.mjs --repo-root "$PWD" --session-type "$SESSION_TYPE" --no-event \
+  | jq '[.waves[] | {n, role, agentCap}]'
 ```
 
+The **session type picks the override** when the config carries one; `.default` is only the fallback, and it is the more restrictive of the two (an override such as `deep: 18` exists precisely to raise the ceiling above it). A resolver that returns `.default` unconditionally is therefore safe for a resource ceiling but wrong for wave shaping — see the note on the two mode-blind call sites (`wave-resource-gate.mjs`, `resource-probe/evaluate.mjs`) in `docs/session-config-reference.md` § `agents-per-wave`, both of which call the same `resolveAgentCap` but pass a local `MODE_BLIND_SESSION_TYPE` (`undefined`) instead of the real session type.
+
 ## Handling `agent-mapping` Config
 
 `agent-mapping` is an optional JSON object that maps role keys to agent names. If present, session-plan uses these explicit mappings to assign agents to tasks (overriding auto-discovery matching).
@@ -166,7 +170,9 @@ Rule files at `.claude/rules/*.md` may carry an optional `globs:` YAML frontmatt
 
 Parse-error rules carry no meta, so they pass every gate (fail-open: never silently dropped).
 
-**Call shape.** `loadApplicableRules({ rulesDir, scopePaths = [], mode = null, hostClass = null, now = Date.now() })`. The `mode` / `hostClass` / `now` params are strictly optional and default to "no gating", so the original #336 two-key call shape stays 100% backward-compatible. In the wired path, `scripts/print-applicable-rules.mjs` resolves `scopePaths` from `wave-scope.json` `allowedPaths`, `mode` from `session-type:` in `.claude/STATE.md`, and `hostClass` from `.orchestrator/host.json` (`readHostClass`) — each overridable via a CLI flag and each degrading to `null`/`[]` when unreadable.
+**Call shape.** `loadApplicableRules({ rulesDir, scopePaths = [], mode = null, hostClass = null, now = Date.now() })`. The `mode` / `hostClass` / `now` params are strictly optional and default to "no gating", so the original #336 two-key call shape stays 100% backward-compatible. In the wired path, `scripts/print-applicable-rules.mjs` resolves `scopePaths` from `wave-scope.json` `allowedPaths`;
+`mode` from `session-type:` in the active harness's `STATE.md` (state-directory override first, then active-harness and legacy fallback);
+and `hostClass` from `.orchestrator/host.json` (`readHostClass`) — each overridable via a CLI flag and each degrading to `null`/`[]` when unreadable.
 
 **Where in the config-reading flow this hook fires.** After `parse-config.mjs` completes and `$CONFIG` is populated (Phase 2 of session-start / wave-executor pre-wave setup), and after `wave-scope.json` is written, but before the agent prompt for the wave is assembled. The CLI is invoked at the wave boundary so that each wave gets a fresh rule set scoped to its `allowedPaths`. It does NOT run at session-start for the coordinator prompt; the coordinator always receives all always-on rules regardless of scope.