session-orchestrator 5.12.0 → 5.13.0

package/scripts/lib/worktree/lifecycle.mjs

@@ -17,7 +17,7 @@
  *   lifecycle → config.mjs (readConfigFile, parseSessionConfig)
  */
 
-import { $, nothrow, ProcessOutput } from 'zx';
+import { $, nothrow, ProcessOutput } from '../zx.mjs';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';

package/scripts/lib/worktree/listing.mjs

@@ -10,7 +10,7 @@
  * lifecycle import chain (lifecycle imports listing, not the reverse).
  */
 
-import { $ as defaultDollar } from 'zx';
+import { $ as defaultDollar } from '../zx.mjs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 

package/scripts/lib/zx.mjs

@@ -0,0 +1,50 @@
+import { existsSync as fileExistsSync } from 'node:fs';
+import { win32 as path } from 'node:path';
+import { $, quote } from 'zx';
+
+export * from 'zx';
+
+// Windows 11 / Node 24.14 / zx 8.8.5 / Git 2.55, measured 2026-10-14:
+// MSYS halves backslashes in Node's -c command line before bash interprets
+// ANSI-C quoting (\b becomes backspace, \r CR). Doubling zx's escapes gave
+// 14/14 exact argument roundtrips, versus 10/14 with stock quote (#1612).
+// Always start from stock quote, so repeated configuration cannot stack escapes.
+const quoteGitBash = (arg) => quote(arg).replace(/\\/g, '\\\\');
+
+/** Configure the zx singleton; injection also permits Windows checks on POSIX. */
+export function configureZx({
+  platform = process.platform,
+  existsSync = fileExistsSync,
+  target = $,
+  env = process.env,
+} = {}) {
+  if (platform !== 'win32') return;
+
+  const shell = typeof target.shell === 'string' ? path.normalize(target.shell) : '';
+  const wsl = path.join(env.SystemRoot || 'C:\\Windows', 'System32', 'bash.exe');
+  if (!target.shell || shell.toLowerCase() === wsl.toLowerCase()) {
+    const candidates = [env.ProgramFiles, env['ProgramFiles(x86)']]
+      .filter(Boolean).map(dir => path.join(dir, 'Git', 'bin', 'bash.exe'));
+    let bash = candidates.find(candidate => existsSync(candidate));
+    if (!bash) {
+      for (const dir of (env.PATH || '').split(';').filter(Boolean)) {
+        const gitDir = dir.replace(/^"|"$/g, '');
+        if (!existsSync(path.join(gitDir, 'git.exe'))) continue;
+        const candidate = path.resolve(gitDir, '..', 'bin', 'bash.exe');
+        if (existsSync(candidate)) {
+          bash = candidate;
+          break;
+        }
+      }
+    }
+    if (!bash) return;
+    target.shell = bash;
+  }
+
+  if (typeof target.shell === 'string' &&
+      /\\(?:Git\\bin|usr\\bin)\\bash\.exe$/i.test(path.normalize(target.shell))) {
+    target.quote = quoteGitBash;
+  }
+}
+
+configureZx();

package/scripts/mcp-server.mjs

@@ -6,6 +6,8 @@ import { join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { isSessionConfigHeading } from './lib/config/section-extractor.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { canonicalizeSessions, isMeasuredSession } from './lib/sessions-canonical.mjs';
+import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 
 const SERVER_INFO = { name: 'session-orchestrator', version: '2.0.0' };
 const TOOLS = [
@@ -16,7 +18,7 @@ const TOOLS = [
   },
   {
     name: 'session_metrics',
-    description: 'Reads the last 5 REAL session metrics entries from .orchestrator/metrics/sessions.jsonl (abandoned phantom stubs excluded)',
+    description: 'Reads the last 5 MEASURED session metrics entries from .orchestrator/metrics/sessions.jsonl (unmeasured records excluded)',
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
 ];
@@ -65,24 +67,31 @@ export function readSessionConfig(root) {
   return body.join('\n').replace(/\n+$/, '') || `No '## Session Config' section found in ${file}`;
 }
 
-/** Read the last five real records, with whole-ledger stub count and token coverage. */
+/** Read the last five canonical measured records, with exclusions and token coverage. */
 export function readSessionMetrics(root) {
-  const file = ['.orchestrator', '.claude'].map((dir) => join(root, dir, 'metrics', 'sessions.jsonl'))
+  const file = ['.orchestrator', '.claude'].map((dir) => join(resolveEventsLedgerRoot(root), dir, 'metrics', 'sessions.jsonl'))
     .find((path) => isFile(path));
   if (!file) return 'No metrics found (checked .orchestrator/metrics/ and .claude/metrics/)';
   const entries = [];
   let stubCount = 0;
+  const parsed = [];
   for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
     let record;
     try { record = JSON.parse(line); } catch { continue; }
-    // Torn writes and non-record JSON must not hide subsequent valid sessions.
+    // Preserve torn-write/non-record guards and actionable read errors.
     if (!record || typeof record !== 'object' || Array.isArray(record)) continue;
-    if (record.status === 'abandoned') { stubCount++; continue; }
+    parsed.push(record);
+  }
+  // Keep ID-less legacy measurements and original append order for the window.
+  const canonical = new Set(canonicalizeSessions(parsed, { keepUnidentified: true }));
+  for (const record of parsed) {
+    if (!canonical.has(record)) continue;
+    if (!isMeasuredSession(record)) { stubCount++; continue; }
     entries.push(record);
     if (entries.length > 5) entries.shift();
   }
   if (!entries.length) {
-    return stubCount ? `No real sessions (abandoned stubs excluded: ${stubCount})`
+    return stubCount ? `No measured sessions (unmeasured records excluded: ${stubCount})`
       : 'No metrics found (file is empty)';
   }
   const record = entries.findLast((entry) => (entry.total_token_input !== null && entry.total_token_input !== undefined)
@@ -95,7 +104,7 @@ export function readSessionMetrics(root) {
       + ` [session: ${record.session_id ?? 'unknown'}]`
     : 'tokens: no token data in last 5 sessions (subagent telemetry not yet captured)';
   return entries.map((entry) => JSON.stringify(entry)).join('\n')
-    + `\n\nabandoned stubs excluded: ${stubCount}\n\n--- token summary ---\n${summary}`;
+    + `\n\nunmeasured records excluded: ${stubCount}\n\n--- token summary ---\n${summary}`;
 }
 
 /** Handle one JSON-RPC line. null means a notification or blank line, not a reply. */

package/scripts/mcp-server.sh

@@ -8,8 +8,8 @@ set -euo pipefail
 #   - session_config  — reads Session Config from the project instruction file
 #                       (CLAUDE.md, or AGENTS.md alias on Codex CLI — see
 #                       skills/_shared/instruction-file-resolution.md)
-#   - session_metrics — reads last 5 REAL session metrics entries (#834:
-#                       abandoned phantom stubs are filtered out first)
+#   - session_metrics — reads last 5 canonical MEASURED session metrics entries
+#                       via the shared native reader (#1584)
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -85,7 +85,7 @@ handle_tools_list() {
       },
       {
         "name": "session_metrics",
-        "description": "Reads the last 5 REAL session metrics entries from .orchestrator/metrics/sessions.jsonl (abandoned phantom stubs excluded)",
+        "description": "Reads the last 5 MEASURED session metrics entries from .orchestrator/metrics/sessions.jsonl (unmeasured records excluded)",
         "inputSchema": {"type": "object", "properties": {}, "required": []}
       }
     ]
@@ -171,88 +171,18 @@ tool_session_metrics() {
     return
   }
 
-  local metrics_file="$project_root/.orchestrator/metrics/sessions.jsonl"
-  if [[ ! -f "$metrics_file" ]]; then
-    metrics_file="$project_root/.claude/metrics/sessions.jsonl"
-  fi
-  if [[ ! -f "$metrics_file" ]]; then
-    respond "$id" "$(text_content "No metrics found (checked .orchestrator/metrics/ and .claude/metrics/)")"
-    return
-  fi
-
-  # Filter out phantom `status: 'abandoned'` stubs (#834, session-close-backfill
-  # — 0 waves, seconds of runtime) BEFORE taking the tail, so a recent phantom
-  # cannot displace real session records out of the last-5 window.
-  #
-  # `-R` (raw-input) + `fromjson?` parses each line individually and SKIPS
-  # unparseable ones instead of aborting the whole stream — plain
-  # `jq -c 'select(...)'` aborts at the FIRST malformed line (jq: parse error,
-  # exit 5), which is fatal here because sessions.jsonl is append-only from
-  # multiple writers and a torn write is exactly the case that matters. This
-  # mirrors the per-line try/catch behaviour of the .mjs path
-  # (scripts/lib/session-schema/filters.mjs).
-  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
-    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
+  # Delegate to the same reader as the native transport: canonical identity,
+  # measured-session definition, main-checkout ledger and token summary.
+  local server_dir output
+  server_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+  if ! output=$(node --input-type=module -e '
+    import { pathToFileURL } from "node:url";
+    const { readSessionMetrics } = await import(pathToFileURL(process.argv[2]).href);
+    process.stdout.write(readSessionMetrics(process.argv[3]));
+  ' session-metrics-reader "$server_dir/mcp-server.mjs" "$project_root" </dev/null); then
+    respond_error "$id" -32603 "Unable to read session data"
     return
   fi
-
-  # Derive a token summary from the most-recent record that carries token totals.
-  # Fields total_token_input / total_token_output / subagents_with_tokens are
-  # optional (null when no subagent token data was captured for that session).
-  # Low coverage (subagents_with_tokens == 0 while matched_records > 0) means
-  # the total is PARTIAL — do not read it as "free / zero cost".
-  local token_summary
-  # Use -Rrs (raw-input + slurp + raw-output) so jq receives the multi-line
-  # JSONL block as a single string, can split + parse each line independently,
-  # and outputs plain text (no surrounding JSON quotes on the result string).
-  # The plain -r flag alone does not work for multi-record JSONL piped as one
-  # string — it treats the entire input as a single JSON value.
-  token_summary=$(printf '%s' "$entries" | \
-    jq -Rrs '
-      # Parse each non-empty line as JSON; skip malformed lines.
-      [ split("\n")[] | select(length > 0) | (try fromjson catch null) | select(. != null) ]
-      | reverse
-      | ( map(select( (.total_token_input != null) or (.total_token_output != null) )) | first ) as $rec
-      | if $rec then
-          "tokens: \($rec.total_token_input // "?") in / \($rec.total_token_output // "?") out" +
-          " (coverage: \($rec.subagents_with_tokens // 0) subagents)" +
-          ( if ($rec.subagents_with_tokens // 0) == 0 then
-              " ⚠ partial — subagent token data missing; total is not a reliable cost estimate"
-            else "" end ) +
-          " [session: \($rec.session_id // "unknown")]"
-        else
-          "tokens: no token data in last 5 sessions (subagent telemetry not yet captured)"
-        end
-    ' 2>/dev/null) || token_summary=""
-
-  local output
-  entries="${entries}
-
-abandoned stubs excluded: ${stub_count}"
-  if [[ -n "$token_summary" ]]; then
-    output="${entries}
-
---- token summary ---
-${token_summary}"
-  else
-    output="$entries"
-  fi
-
   respond "$id" "$(text_content "$output")"
 }
 

package/scripts/measure-policy-cache-effectiveness.mjs

@@ -37,7 +37,7 @@ import { spawnSync } from 'node:child_process';
 import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 // ---------------------------------------------------------------------------
 // CLI flags
@@ -57,8 +57,8 @@ const _REPO_ROOT = resolve(flagValue('--repo-root', process.cwd()));
 const JSON_MODE = flagBool('--json');
 
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
-const CACHE_MODULE = join(SCRIPT_DIR, 'lib', 'quality-gates-cache.mjs');
-const POLICY_MODULE = join(SCRIPT_DIR, 'lib', 'quality-gates-policy.mjs');
+const CACHE_MODULE = pathToFileURL(join(SCRIPT_DIR, 'lib', 'quality-gates-cache.mjs')).href;
+const POLICY_MODULE = pathToFileURL(join(SCRIPT_DIR, 'lib', 'quality-gates-policy.mjs')).href;
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -340,11 +340,13 @@ async function main() {
     } else {
       printHumanReport(report);
     }
-
-    process.exit(0);
   } finally {
     teardownTmpRepo(tmpRepo);
   }
+  // Exit only AFTER the finally: process.exit() ends the process on the spot,
+  // so calling it inside the try skipped teardownTmpRepo and leaked one
+  // pce-repo-* dir under os.tmpdir() on every successful run (#1648).
+  process.exit(0);
 }
 
 function deriveRecommendation(cacheSubprocess, cacheInProcess, policySubprocess, _policyInProcess) {

package/scripts/memory-propose.mjs

@@ -278,12 +278,19 @@ let stateMdReadOk = false;
 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());
+  const { resolveStateMdWriteTarget, warnForeignStateMd } = await import(
+    './lib/state-md/frontmatter-mutators.mjs'
+  );
+  // #1636: the write side's ownership rule — another platform's STATE.md not
+  // proven to be this process's takes the "missing" branch. On rejection
+  // `stateMdPath` is this platform's own target, so stateDir (also the wave
+  // manifest's dir) never points into the foreign platform's state dir.
+  const { path: stateMdPath, rejected } = resolveStateMdWriteTarget(process.cwd());
+  if (rejected) warnForeignStateMd('memory-propose', rejected, stateMdPath);
   stateDir = dirname(stateMdPath);
 
-  if (!existsSync(stateMdPath)) {
+  if (rejected || !existsSync(stateMdPath)) {
     if (!dryRun) {
       exit(
         { status: STATUS.REJECTED_WRONG_CONTEXT, detail: 'STATE.md missing or unparseable' },

package/scripts/migrate-cold-start-seed.mjs

@@ -245,6 +245,13 @@ async function processRepo(repo, { apply }) {
 
   // Sessions.jsonl liveness check — even if marker is absent, an active repo
   // should not get a "welcome" banner.
+  // Deliberately THIS path's own ledger, not resolveEventsLedgerRoot(repo)
+  // (#1592): the inputs are main-checkout repo paths by construction
+  // (--repos / dormant-repos), and the marker above is seeded into this same
+  // path — liveness and seed stay one checkout. Ceiling: a linked worktree
+  // passed via --repos is judged by its own (absent) ledger; revisit if
+  // worktree paths ever enter dormant-repos.
+  // ledger-root: deliberate own-path ledger (#1592), see the comment above
   const sessionsPath = join(repo, SESSIONS_REL);
   try {
     if (await sessionsHasContent(sessionsPath)) {

package/scripts/migrate-legacy-learnings.sh

@@ -7,6 +7,28 @@ set -euo pipefail
 ROOT="${1:-$(pwd)}"
 CANONICAL="$ROOT/.orchestrator/metrics/learnings.jsonl"
 TODAY="$(date +%Y-%m-%d)"
+
+# #1516: a host whose learnings-store role is `inbox` never rewrites the
+# canonical store. The role resolver is the JS one (env SO_LEARNINGS_STORE_ROLE
+# > owner.yaml learnings.store-role > writer), imported relative to this script.
+# Fail-closed: if node fails, or the role is `invalid` (set but unusable) or
+# anything other than writer/inbox, nothing is written and the script exits 4.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+STORE_ROLE="$(node --input-type=module -e '
+const { pathToFileURL } = await import("node:url");
+const m = await import(pathToFileURL(process.argv[1]).href);
+process.stdout.write(m.resolveStoreRole().role);
+' "$SCRIPT_DIR/lib/learnings/store-role.mjs" 2>/dev/null)" || STORE_ROLE="unresolved"
+if [ "$STORE_ROLE" = "inbox" ]; then
+  echo "migrate-legacy-learnings: learnings store role is inbox on this host (#1516) — nothing written; run it on the writer host" >&2
+  printf '{"status":"refused_store_role"}\n'
+  exit 3
+fi
+if [ "$STORE_ROLE" != "writer" ]; then
+  echo "migrate-legacy-learnings: learnings store role is ${STORE_ROLE} on this host (#1516) — nothing written; fix owner.yaml learnings.store-role or SO_LEARNINGS_STORE_ROLE" >&2
+  printf '{"status":"refused_store_role_invalid"}\n'
+  exit 4
+fi
 LEGACY_PATHS=("$ROOT/.claude/metrics/learnings.jsonl" "$ROOT/.codex/metrics/learnings.jsonl" "$ROOT/.cursor/metrics/learnings.jsonl")
 
 tmp=""

package/scripts/migrate-sessions-jsonl.mjs

@@ -39,9 +39,10 @@
  */
 
 import { readFileSync, copyFileSync, existsSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { atomicWriteWithBackup, envelopeToError } from './lib/io.mjs';
 import { validateSession, normalizeSession, ValidationError } from './lib/session-schema.mjs';
+import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/sessions.jsonl';
@@ -327,8 +328,21 @@ function processEntry(raw) {
 // CLI
 // ---------------------------------------------------------------------------
 
+/**
+ * Default target: sessions.jsonl of the repo's one ledger root (#1514/#1584,
+ * #1722) — the main checkout when cwd is a linked worktree. Outside one the
+ * relative DEFAULT_FILE is kept verbatim, so paths in output do not change.
+ *
+ * @returns {string}
+ */
+function defaultFile() {
+  const root = resolveEventsLedgerRoot(process.cwd());
+  // ledger-root: `root` is resolveEventsLedgerRoot() of the line above
+  return root === resolve(process.cwd()) ? DEFAULT_FILE : join(root, DEFAULT_FILE);
+}
+
 function parseArgs(argv) {
-  const args = { file: DEFAULT_FILE, apply: false };
+  const args = { file: defaultFile(), apply: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--file') {

package/scripts/migrate-vault-paths.mjs

@@ -3,7 +3,8 @@
  * migrate-vault-paths.mjs — one-shot cross-repo migration for username-drift in vault/project paths.
  *
  * Rewrites a literal "from" username path-segment to a "to" segment across markdown
- * files under ~/Projects/. Only the username path segment changes; the trailing
+ * files under the projects root (getConfinementRoot(): SO_PROJECTS_ROOT >
+ * owner.yaml paths.projects-root > ~/Projects). Only the username path segment changes; the trailing
  * path is preserved.
  *
  * Typical use: a host username change (`/Users/oldname/` → `/Users/newname/`) leaves
@@ -23,7 +24,7 @@
  * Target repo resolution (in priority order):
  *   1. --repos <comma,list>             (explicit CLI override)
  *   2. audited-repos: [...] in the same vault-migration-rules.yaml
- *   3. <none, no --repos> → scan only the auto-discover sweep under ~/Projects/**.
+ *   3. <none, no --repos> → scan only the auto-discover sweep under <projects-root>/**.
  *
  * Flags:
  *   --from SEG       Literal source segment (e.g. '/Users/oldname/'). Required if no config entry.
@@ -61,13 +62,13 @@ import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 import { loadHostPaths, resolveHostPath } from './lib/config/host-paths.mjs';
+import { getConfinementRoot } from './lib/config/cross-repo.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
 const HOME = os.homedir();
-const PROJECTS_ROOT = path.join(HOME, 'Projects');
 
 // Set at startup from CLI args or config. Helpers read these; main() resolves them.
 let OLD_SEGMENT = null;
@@ -221,7 +222,8 @@ function printHelp() {
     `Usage: migrate-vault-paths.mjs --from <old/> --to <new/> [--dry-run|--apply] [--repos <comma,list>] [--json] [--help]
 
 Rewrites a literal "from" path segment to a "to" segment across markdown files
-under ~/Projects/, skipping tests/, fixtures/, .git/, vault-backups, and
+under the projects root (SO_PROJECTS_ROOT / owner.yaml paths.projects-root,
+default ~/Projects), skipping tests/, fixtures/, .git/, vault-backups, and
 historical contexts (decisions.md, history/, archive*).
 
 Both --from and --to are required unless username-rewrites[0] is set in
@@ -236,7 +238,7 @@ Options:
   --apply              Write fixes in-place (atomic: tmp + rename)
   --repos LIST         Comma-separated repo names or paths to scan; falls back
                        to audited-repos: [...] in vault-migration-rules.yaml,
-                       then to ~/Projects/** auto-discovery sweep
+                       then to <projects-root>/** auto-discovery sweep
   --json               Emit JSONL records on stdout (one per hit)
   --help, -h           Show this help
 
@@ -249,8 +251,21 @@ Exit codes:  0 success  1 input error  2 I/O error
 // Repo discovery
 // ---------------------------------------------------------------------------
 
+let _projectsRoot;
+
+/**
+ * Projects root for this run, resolved once (#1622): getConfinementRoot() reads
+ * owner.yaml and WARNs on an invalid SO_PROJECTS_ROOT, so per-repo calls repeated both.
+ * @returns {string}
+ */
+function projectsRoot() {
+  _projectsRoot ??= getConfinementRoot();
+  return _projectsRoot;
+}
+
 /**
- * Resolve a repo name to an absolute path by searching ~/Projects/**.
+ * Resolve a repo name to an absolute path by searching <projects-root>/**
+ * (getConfinementRoot(), #1567).
  * If the input is already an absolute path that exists, returns it as-is.
  * Returns null when no match is found.
  */
@@ -258,10 +273,10 @@ function resolveRepoPath(nameOrPath) {
   if (path.isAbsolute(nameOrPath)) {
     return existsSync(nameOrPath) ? nameOrPath : null;
   }
-  // Search up to 4 levels deep under ~/Projects/
+  // Search up to 4 levels deep under the projects root
   const result = spawnSync(
     'find',
-    [PROJECTS_ROOT, '-maxdepth', '4', '-type', 'd', '-name', nameOrPath],
+    [projectsRoot(), '-maxdepth', '4', '-type', 'd', '-name', nameOrPath],
     { encoding: 'utf8' },
   );
   if (result.status !== 0) return null;
@@ -358,14 +373,15 @@ function findMissingSegmentFiles(roots) {
 }
 
 /**
- * Auto-discover ALL repos under ~/Projects/** that contain the OLD_SEGMENT
+ * Auto-discover ALL repos under <projects-root>/** that contain the OLD_SEGMENT
  * literal OR a missing-segment `vault-dir:` drift. Used in tandem with the
  * default-target list to find drift we don't already know about.
  */
 function discoverAdditionalFiles() {
-  if (!existsSync(PROJECTS_ROOT)) return [];
-  const set = new Set(findCandidateFiles([PROJECTS_ROOT]));
-  for (const f of findMissingSegmentFiles([PROJECTS_ROOT])) set.add(f);
+  const root = projectsRoot();
+  if (!existsSync(root)) return [];
+  const set = new Set(findCandidateFiles([root]));
+  for (const f of findMissingSegmentFiles([root])) set.add(f);
   return [...set];
 }
 
@@ -599,7 +615,7 @@ async function main() {
   let candidateFiles = [...candidateSet];
 
   // If NO explicit repo list was given (neither --repos nor config.audited-repos),
-  // expand scan to discover anything else under ~/Projects/**.
+  // expand scan to discover anything else under <projects-root>/**.
   if (!explicitRepos) {
     const additional = discoverAdditionalFiles();
     const set = new Set(candidateFiles);

package/scripts/parse-config.mjs

@@ -8,11 +8,12 @@
  *
  * 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`.
+ *   `docs/session-config-template.md` ("How to use" and "Validation &
+ *   Bootstrap") 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
@@ -20,6 +21,11 @@
  * `enforcement: strict`; `off` is silent. stdout is unchanged for any
  * well-formed block — a warning never alters the emitted JSON.
  *
+ * Unknown top-level keys (#1562) — a key the plugin's own
+ * `docs/session-config-template.md` does not document, i.e. a typo or a key
+ * from a newer plugin version — are reported per line on stderr under `warn`
+ * AND `strict` (a report, never a refusal); `off` is silent. stdout unchanged.
+ *
  * 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
@@ -30,7 +36,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 { collectUnparsableLines, collectTopLevelKeyLines } from './lib/config/section-extractor.mjs';
+import { knownTemplateKeys } from './lib/config/template-keys.mjs';
 import { findUnterminatedComment } from './lib/config/block-preprocess.mjs';
 import { ENFORCEMENT_VALUES } from './lib/config-schema.mjs';
 
@@ -189,15 +196,15 @@ try {
 
 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';
+// 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 (unparsableLines.length > 0) {
   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
@@ -230,6 +237,56 @@ if (unparsableLines.length > 0) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Unknown-key report (#1562) — a typo'd key is not a silent default either
+// ---------------------------------------------------------------------------
+//
+// A well-formed line with a mis-spelled key (`persistance: true`) parses
+// cleanly, so the gate above never sees it: the key lands in the KV map under a
+// name nothing reads, and the real key keeps its default. The population of
+// known keys is the plugin's OWN template (first + last `## Session Config`
+// block, the population drift-check Check 6 reads) plus every top-level key
+// `parseSessionConfig()` emits, so it moves with the plugin version, never
+// with the repo.
+//
+// A report, never a refusal — even under `strict`: a key from a newer plugin
+// version is not a defect of the repo. Three states stay apart on purpose:
+// measured with findings (one line per key), measured clean (silence), and NOT
+// measured (one line saying why) — "the check could not run" must never read
+// like "no unknown keys".
+
+if (enforcement !== 'off') {
+  const templatePath = join(SCRIPT_DIR, '..', 'docs', 'session-config-template.md');
+  let known = null;
+  let notRunReason = null;
+  try {
+    known = knownTemplateKeys(readFileSync(templatePath, 'utf8'));
+    if (!known) notRunReason = 'it has no distinct starter and opt-in `## Session Config` blocks';
+    // A key the parser itself emits is read, wherever the template documents it:
+    // `skill-evolution` and `dispatcher-autonomy` are parsed from the whole file
+    // (their parity-exempt template blocks sit outside `## Session Config`), so
+    // the same key inside the block is applied and must not read "no effect".
+    else for (const key of Object.keys(config)) known.add(key);
+  } catch (err) {
+    notRunReason = err.code === 'ENOENT' ? 'it was not found' : `it could not be read (${err.code ?? err.message})`;
+  }
+
+  if (notRunReason) {
+    process.stderr.write(
+      `⚠ parse-config.mjs: unknown Session Config key check did not run — ${templatePath}: ${notRunReason}\n`,
+    );
+  } else {
+    const configName = parsePath(configFile).base;
+    for (const { line, key } of collectTopLevelKeyLines(content)) {
+      if (known.has(key)) continue;
+      process.stderr.write(
+        `⚠ ${configName}:${line}: unknown Session Config key '${key}' — not in docs/session-config-template.md ` +
+          '(a typo, or a key from a newer plugin version); it has no effect\n',
+      );
+    }
+  }
+}
+
 // jq -n produces pretty-printed JSON without a trailing newline — match that format
 const assembledJson = JSON.stringify(config, null, 2);