session-orchestrator 5.11.0 → 5.13.0

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);
 

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 { resolveLedgerPath } from './lib/ledger-path.mjs';
 import { eventsFilePath } from './lib/events.mjs';
 import { resolveStateArtifactPath } from './lib/state-md.mjs';
 import {
@@ -154,6 +155,11 @@ Options:
   --max-chars <n>       Hard cap on the rendered index body (default: ${LEARNINGS_INDEX_MAX_CHARS}).
   --pool-size <n>       Active entries pulled before ranking (default: ${CANDIDATE_POOL_SIZE}).
   --learnings <path>    Learnings JSONL (default: .orchestrator/metrics/learnings.jsonl).
+  --evidence-candidates <path>  Opt into a bounded local candidate JSON artifact.
+                        Requires --source-repo and an exact non-empty --task-text.
+                        Invalid/unavailable artifacts keep the baseline output;
+                        provider status/counts go to stderr. No provider is run.
+  --source-repo <id>    Explicit opaque repo ID bound to the candidate artifact.
   --rules-dir <path>    Natively-delivered rule corpus (default: .claude/rules).
                         Learnings already delivered as a rule file there are
                         excluded from the index (#1019). A path that does not
@@ -208,6 +214,8 @@ try {
       'max-chars': { type: 'string' },
       'pool-size': { type: 'string' },
       learnings: { type: 'string' },
+      'evidence-candidates': { type: 'string' },
+      'source-repo': { type: 'string' },
       'rules-dir': { type: 'string' },
       'no-event': { type: 'boolean', default: false },
       json: { type: 'boolean', default: false },
@@ -219,6 +227,14 @@ try {
 }
 
 const opts = parsed.values;
+if (opts['evidence-candidates'] !== undefined &&
+    (!opts['evidence-candidates'] || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(opts['source-repo'] ?? '') ||
+     !opts['task-text']?.trim() || opts['task-text'].length > 4000)) {
+  fail('--evidence-candidates requires a path, --source-repo ID and non-empty --task-text (at most 4000 characters)', 1);
+}
+if (opts['source-repo'] !== undefined && opts['evidence-candidates'] === undefined) {
+  fail('--source-repo requires --evidence-candidates', 1);
+}
 
 /**
  * Parse a `--max-*` value: a non-negative integer. Anything else is a
@@ -249,7 +265,7 @@ const poolSize = parseCap(opts['pool-size'], CANDIDATE_POOL_SIZE, '--pool-size')
 const repoRoot = findProjectRoot(process.cwd());
 const learningsPath = opts.learnings
   ? opts.learnings
-  : join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
+  : resolveLedgerPath('.orchestrator/metrics/learnings.jsonl', repoRoot); // #1722
 const eventsPath = eventsFilePath(repoRoot); // #1514 point 1: the repo's one ledger
 // #1019 — the natively-delivered rule corpus. Every `.claude/rules/*.md` reaches
 // a dispatched agent in FULL through Claude Code's own project-instruction
@@ -338,7 +354,11 @@ try {
   selection = await selectLearningsFromFile(
     learningsPath,
     { file_paths: scopePaths, text: taskText },
-    { maxScoped, maxGlobal, maxChars, poolSize, rulesDir },
+    { maxScoped, maxGlobal, maxChars, poolSize, rulesDir,
+      ...(opts['evidence-candidates'] !== undefined ? {
+        evidenceCandidates: opts['evidence-candidates'], sourceRepo: opts['source-repo'],
+      } : {}),
+    },
   );
 } catch (err) {
   // `selectLearningsFromFile` is contractually total (contract point 1), so this
@@ -350,6 +370,9 @@ try {
 
 const selected = selection.entries;
 const scopeMatched = selection.scopeMatched;
+if (selection.evidence) {
+  process.stderr.write(`[evidence-candidates] ${JSON.stringify(selection.evidence)}\n`);
+}
 
 // ---------------------------------------------------------------------------
 // Render — the WRAPPER only; per-entry lines come from the selector

package/scripts/release-session-lock.mjs

@@ -43,12 +43,15 @@
  */
 
 import { parseArgs } from 'node:util';
+import { existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 
-import { readLockDetailed, loadOwnerProof, release } from './lib/session-lock.mjs';
+import { readLockDetailed, loadOwnerProof, release, writeReleaseMarker } from './lib/session-lock.mjs';
 import { LOCK_RELEASED_EVENT } from './lib/session-transition.mjs';
 import { emitEvent } from './lib/events.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { registrySessionRoot, resolveOwnLockRootFor } from './lib/own-lock-root.mjs';
+import { dotGitAncestor } from './lib/platform.mjs';
 
 /**
  * `caller` value stamped into the breadcrumb, so this fourth release site stays
@@ -69,18 +72,31 @@ WHAT IT DOES
   3. Emits orchestrator.session.lock.released with the ids read BEFORE the
      delete, plus caller="${PHASE_CALLER}".
   4. RE-READS the lock path and exits 0 only when our lock is provably gone.
+  5. Leaves .orchestrator/runtime/lock-released/<raw-id>.json, so a compaction
+     or resume of this session does not re-create the lock (#1651); the
+     session's next deliberate acquire() removes it.
 
 FLAGS
   --session-id <id>   REQUIRED. The RAW (physical) session id that owns the lock
                       — .orchestrator/session.lock "session_id", never STATE.md
                       "session" and never the semantic id. A lock owned by a
                       different id is NEVER released.
-  --repo-root <path>  Repo whose lock is released (default: cwd).
+  --repo-root <path>  Repo whose lock is released. Default: the checkout whose
+                      lock carries --session-id — the host registry's
+                      session_root, the cwd's checkout, its main checkout, or a
+                      registered linked worktree, in that order; with none of
+                      them, the cwd's checkout (#1730). The JSON result names
+                      the root (repo_root) and how it was found (root_source:
+                      flag|registry|cwd|main-checkout|worktree|none).
   --json              Machine-readable result on stdout.
   -h, --help          Show this help and exit 0.
 
 OUTCOMES
   absent        no lock file — nothing released, NO event, exit 0.
+
+  Without --repo-root the #1651 marker (absent and released alike) goes to the
+  lock's root, the cwd's checkout and the registry's session_root, existing
+  checkouts only; release_marker_roots lists each root with its result.
   deleted       our lock was removed and re-read as gone.
   already-gone  ownership matched but the lock had already vanished; the event
                 is still written, because a lock removed by a third party while
@@ -137,6 +153,53 @@ function ourLockIsGone(repoRoot, sessionId) {
   return false;
 }
 
+/** @param {string} p */
+function canonical(p) {
+  try { return realpathSync.native(p); } catch { return path.resolve(p); }
+}
+
+/**
+ * Where the #1651 marker goes (#1730). A later compaction's SessionStart looks
+ * for it at `resolveSessionStartRoot`, which depends on THAT compaction's cwd —
+ * unknown here. So it goes to every root that reader can land on: the lock's
+ * root, the cwd's checkout and the registry's session_root. Only existing
+ * checkouts (a `.git` entry): a stale registry entry must not re-create the
+ * directory tree of a removed worktree. The marker is keyed on this session's
+ * own raw id, so an extra copy changes nothing for another session. With
+ * --repo-root the given root alone, as before.
+ *
+ * @param {{ root: string, source: string }} resolved
+ * @param {string} sessionId
+ * @returns {string[]}
+ */
+function markerRootsFor(resolved, sessionId) {
+  if (resolved.source === 'flag') return [resolved.root];
+  const cwdTop = dotGitAncestor(process.cwd()) || path.resolve(process.cwd());
+  const extra = [cwdTop, registrySessionRoot(sessionId)]
+    .filter((r) => typeof r === 'string' && existsSync(path.join(r, '.git')));
+  return [...new Set([resolved.root, ...extra].map(canonical))];
+}
+
+/**
+ * Write the marker at each root; a failed copy is named on stderr and in the
+ * result, never hidden behind one that was written.
+ *
+ * @param {string[]} roots
+ * @param {string} sessionId
+ * @returns {Array<{ root: string, ok: boolean }>}
+ */
+function writeMarkers(roots, sessionId) {
+  return roots.map((root) => {
+    const marker = writeReleaseMarker({ repoRoot: root, sessionId });
+    if (marker.ok !== true) {
+      process.stderr.write(
+        `release-session-lock: release marker not written at ${root} (${marker.reason}) — a compaction there may re-create the lock\n`,
+      );
+    }
+    return { root, ok: marker.ok === true };
+  });
+}
+
 /**
  * CLI entry point.
  *
@@ -175,11 +238,20 @@ export async function main({ argv = process.argv.slice(2) } = {}) {
     return 1;
   }
 
-  const repoRoot = path.resolve(values['repo-root'] ?? process.cwd());
+  // #1730: `/close` runs this without --repo-root, and its cwd is often not the
+  // checkout holding the lock — a worktree session's lock sits in the main
+  // checkout, or the shell cwd reset to the main checkout while the lock is in
+  // a worktree. Reading at the cwd answered `absent` with exit 0 and the lock
+  // stayed. An explicit --repo-root is taken as given.
+  const resolved = values['repo-root'] !== undefined
+    ? { root: path.resolve(values['repo-root']), source: 'flag' }
+    : resolveOwnLockRootFor({ sessionId, cwd: process.cwd() });
+  const repoRoot = resolved.root;
 
   const emitResult = async (result) => {
-    if (values.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-    else printHuman(result);
+    const located = { ...result, repo_root: repoRoot, root_source: resolved.source };
+    if (values.json) process.stdout.write(JSON.stringify(located, null, 2) + '\n');
+    else printHuman(located);
   };
 
   // -- Step 1: read the lock, and capture the ids BEFORE anything is deleted --
@@ -188,8 +260,14 @@ export async function main({ argv = process.argv.slice(2) } = {}) {
   if (lockDetail.status === 'absent') {
     // Nothing was released, so nothing terminal happened: NO event. Writing one
     // here would put a fictional lifecycle end into the stream — the idempotent
-    // re-run case is not a release.
-    const result = { ok: true, outcome: 'absent', verified: true, session_id: sessionId, event_emitted: false };
+    // re-run case is not a release. The #1651 marker IS written: a session that
+    // closes without a lock (bootstrap fs-error, or an earlier release) must not
+    // get one re-created by a later compaction either (roots: markerRootsFor).
+    const markers = writeMarkers(markerRootsFor(resolved, sessionId), sessionId);
+    const result = {
+      ok: true, outcome: 'absent', verified: true, session_id: sessionId, event_emitted: false,
+      release_marker: markers.every((m) => m.ok), release_marker_roots: markers,
+    };
     await emitResult(result);
     return 0;
   }
@@ -249,6 +327,13 @@ export async function main({ argv = process.argv.slice(2) } = {}) {
   const verified = ourLockIsGone(repoRoot, sessionId);
   const outcome = alreadyGone ? 'already-gone' : 'deleted';
 
+  // #1651: leave "released on purpose" behind, so the SessionStart bootstrap
+  // does not re-create this lock after a compaction or resume of the same raw
+  // session (a headless run may hold the slot by then). Best-effort: a failed
+  // marker write is reported, but the release itself stands.
+  const markers = verified ? writeMarkers(markerRootsFor(resolved, sessionId), sessionId) : [];
+  const markerWritten = verified && markers.every((m) => m.ok);
+
   // -- Step 4: the terminal breadcrumb --------------------------------------
   // The ids are passed EXPLICITLY: the lock is gone by now, so emitEvent's
   // lock-derived correlation would find nothing to attribute this record to.
@@ -275,6 +360,8 @@ export async function main({ argv = process.argv.slice(2) } = {}) {
     ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
     event_emitted: eventEmitted,
     ...(emitError !== null ? { event_error: emitError } : {}),
+    release_marker: markerWritten,
+    release_marker_roots: markers,
   };
   await emitResult(result);