session-orchestrator 5.11.0 → 5.13.0

package/scripts/sweep-expired-learnings.mjs

@@ -139,6 +139,7 @@ import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { emitEvolveCompleted } from './lib/learnings/evolve-telemetry.mjs';
+import { resolveLedgerPath, resolveLedgerRoot } from './lib/ledger-path.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
 const DEFAULT_ARCHIVE = '.orchestrator/metrics/learnings-archive.jsonl';
@@ -257,6 +258,7 @@ function parseArgs(argv) {
     generation: null,
     acceptEmbedded: false,
   };
+  let fileExplicit = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--prune') {
@@ -296,6 +298,7 @@ function parseArgs(argv) {
       args.snapshot = pathValue(a, argv[++i]);
     } else if (a === '--file') {
       args.file = pathValue(a, argv[++i]);
+      fileExplicit = true;
     } else if (a === '--archive') {
       args.archive = pathValue(a, argv[++i]);
       args.archiveExplicit = true;
@@ -343,6 +346,12 @@ function parseArgs(argv) {
     }
   }
 
+  // #1722: the DEFAULT store/archive route through the ledger resolver (main
+  // checkout when cwd is a linked worktree that gitignores them); outside one
+  // the relative defaults are kept verbatim. Explicit --file/--archive stay.
+  if (!fileExplicit) args.file = routedDefault(DEFAULT_FILE);
+  if (!args.archiveExplicit) args.archive = routedDefault(DEFAULT_ARCHIVE);
+
   // Mode/flag mismatches are usage errors, never silent no-ops: a `--grace-days`
   // that the prune path ignores would read as "the grace window applied" in a
   // transcript, and an `--entries` the sweep ignores would read as "my next
@@ -381,7 +390,7 @@ function parseArgs(argv) {
       // (macOS /var → /private/var) refused a store inside it. The file goes
       // through resolveLedger (realpath when it exists), because
       // canonicalizeRoot realpaths only the root.
-      if (!validatePathInsideProject(resolveLedger(args.file), args.repoRoot, { canonicalizeRoot: true }).ok) {
+      if (ledgerRootOf(args.file, args.repoRoot) === null) {
         usageError(`--file ${args.file} lies outside --repo-root ${args.repoRoot} — nothing written`);
       }
     }
@@ -441,7 +450,9 @@ async function runSweep(args) {
   } else {
     process.stdout.write(
       `sweep-expired-learnings: scanned=${summary.scanned} kept=${summary.kept} ` +
-        `archived=${summary.archived} dry_run=${summary.dryRun} archive=${summary.archivePath}\n`
+        `archived=${summary.archived} dry_run=${summary.dryRun} archive=${summary.archivePath}` +
+        // An inbox-role apply (#1516) wrote nothing; say so, as --json does.
+        `${summary.skipped ? ` skipped=${summary.skipped}` : ''}\n`
     );
   }
 }
@@ -609,6 +620,39 @@ function resolveLedger(p) {
   }
 }
 
+/**
+ * The default ledger for this cwd (#1722): `rel` verbatim unless the resolver
+ * maps it elsewhere (linked worktree that gitignores it), then that absolute path.
+ *
+ * @param {string} rel
+ * @returns {string}
+ */
+function routedDefault(rel) {
+  const routed = resolveLedgerPath(rel, process.cwd());
+  return routed === path.resolve(rel) ? rel : routed;
+}
+
+/**
+ * Which root a store lies inside, canonically (#1500 F4): `repoRoot` itself, or
+ * its ledger root (the main checkout of a linked worktree, #1722) — but only for
+ * a file inside the DIRECTORY of the mapped default store, never anywhere in
+ * that other checkout (a worktree session must not rewrite a foreign tree).
+ * `null` when it lies outside both.
+ *
+ * @param {string} file
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+function ledgerRootOf(file, repoRoot) {
+  const abs = resolveLedger(file);
+  if (validatePathInsideProject(abs, repoRoot, { canonicalizeRoot: true }).ok) return repoRoot;
+  const storeDir = path.dirname(resolveLedgerPath(DEFAULT_FILE, repoRoot));
+  if (validatePathInsideProject(abs, storeDir, { canonicalizeRoot: true }).ok) {
+    return resolveLedgerRoot(DEFAULT_FILE, repoRoot);
+  }
+  return null;
+}
+
 /**
  * Exit 1 when `--snapshot` would replace the store or the archive. The rename
  * lands the header as the store's line 1 with no `.bak` (and drops malformed
@@ -820,7 +864,9 @@ async function runPrune(args) {
   // hand-assembled `--entries` sidecar) never wrote anything, so it must not
   // report a completed run either. Best-effort — never changes this
   // command's exit code or stdout contract.
-  if (!args.dryRun) {
+  // An inbox-role apply (#1516) returns `skipped`: it archived nothing and did
+  // not rewrite the store, so there is no completed store write to report.
+  if (!args.dryRun && !result.skipped) {
     await emitEvolveCompleted({
       repoRoot: args.repoRoot,
       appended: args.appended,
@@ -841,7 +887,7 @@ async function runPrune(args) {
     process.stdout.write(
       `sweep-expired-learnings: prune scanned=${summary.scanned} kept=${summary.kept} ` +
         `archived=${summary.archived} by_reason=${byReason} dry_run=${summary.dryRun} ` +
-        `archive=${summary.archivePath}\n`
+        `archive=${summary.archivePath}${summary.skipped ? ` skipped=${summary.skipped}` : ''}\n`
     );
   }
 }
@@ -858,7 +904,7 @@ async function runPrune(args) {
 async function emitMalformedDropped(args, result) {
   // Both sides canonical, as the parseArgs check judged them: a lexical
   // relative() across /var vs /private/var reads `../../private/...`.
-  const root = resolveLedger(args.repoRoot);
+  const root = resolveLedger(ledgerRootOf(args.file, args.repoRoot) ?? args.repoRoot);
   const rel = (p) => path.relative(root, resolveLedger(p));
   try {
     const { emitEvent, sessionAttribution } = await import('./lib/events.mjs');
@@ -916,7 +962,9 @@ async function runDropMalformed(args) {
     process.exit(2);
   }
 
-  if (!args.dryRun) await emitMalformedDropped(args, result);
+  // An inbox-role host (#1516) returns the dry-run probe with `skipped` set:
+  // nothing was dropped, so no event may claim it was.
+  if (!args.dryRun && !result.skipped) await emitMalformedDropped(args, result);
 
   const summary = {
     file: args.file,

package/scripts/sweep-expired-rules.mjs

@@ -105,6 +105,7 @@ export function parseArgs(argv) {
     } else if (a === '--learnings') {
       const raw = argv[++i];
       if (typeof raw !== 'string' || raw.length === 0) usageError('--learnings requires a path');
+      if (path.isAbsolute(raw)) usageError('--learnings requires a repo-relative path');
       args.learnings = raw;
     } else if (a === '--help' || a === '-h') {
       printHelp();
@@ -140,6 +141,7 @@ export function summarize(plan, args, applied) {
     expired_entries: plan.plans.reduce((n, p) => n + p.expiredPairIds.length, 0),
     unresolved_pairs: plan.plans.reduce((n, p) => n + p.unresolvedPairIds.length, 0),
     malformed_lines: plan.malformedLines,
+    archive_malformed_lines: plan.archiveMalformedLines,
     rules_dir_readable: plan.ok,
     skipped: plan.skipped,
     plans: plan.plans.map(({ nextContent: _nextContent, ...rest }) => rest),
@@ -178,7 +180,8 @@ async function main(argv) {
         `(${summary.header_raises} header-raise(s)), ` +
         `${summary.deletes} delete(s), ${summary.expired_entries} expired entr(ies), ` +
         `${summary.unresolved_pairs} unresolved pair(s), ${summary.skipped.length} skipped, ` +
-        `${summary.malformed_lines} malformed learnings line(s)\n`,
+        `${summary.malformed_lines} malformed learnings line(s), ` +
+        `${summary.archive_malformed_lines} malformed archive line(s)\n`,
     );
     for (const s of plan.skipped) process.stdout.write(`  skipped ${s.file}: ${s.reason}\n`);
     for (const p of plan.plans) {

package/scripts/validate-plugin.mjs

@@ -481,6 +481,11 @@ runCheck('check-learning-provenance.mjs');
 process.stdout.write('\n');
 runCheck('check-vcs-repo-flag.mjs');
 
+// Separate advice contract (#1024): name the PR or drop a rejected repo flag.
+// WARN-only, with tool errors surfaced through FAIL lines as in the bare census.
+process.stdout.write('\n');
+runCheck('check-vcs-repo-flag-positional.mjs');
+
 // WARN-only (#1023): a `gh`/`glab` command cited in docs that no released CLI
 // ever had — `glab repo edit --visibility`, `glab group list` — costs an
 // operator a failed command and a re-derivation. The oracle is the CLI's own
@@ -539,6 +544,13 @@ if (runCheck('check-learnings-shell-writes.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 runCheck('check-test-git-config-target.mjs');
 
+// BLOCKING (#1613): a test that spawns `sh`/`bash` by bare name is red on native
+// Windows (no sh on PATH, bash is WSL) — 301 red tests at fd8d3673. It may block
+// because the backlog was drained in the same change: the live census leaves only
+// three files in open MRs, baselined inside the checker as WARN.
+process.stdout.write('\n');
+if (runCheck('check-test-posix-shell.mjs') !== 0) checkFailed = 1;
+
 // BLOCKING (#1183): every `emitEvent()` call site under hooks/**/*.mjs must be
 // try/catch-guarded (emitEvent() throws EventValidationError on a malformed
 // record — an unguarded call aborts the hook process). Five pre-existing
@@ -548,6 +560,16 @@ runCheck('check-test-git-config-target.mjs');
 process.stdout.write('\n');
 if (runCheck('check-hooks-emit-event-guard.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n'); if (runCheck('check-workflow-continue-on-error.mjs') !== 0) checkFailed = 1;
+
+// BLOCKING (#1722): a module under scripts/ or hooks/ that builds a
+// `.orchestrator/metrics` path must route it through resolveLedgerPath()
+// (events/sessions: resolveEventsLedgerRoot()). The ledgers are gitignored, so
+// from a linked worktree an unrouted writer leaves a copy that is lost with the
+// worktree. Deliberately local sites sit on the checker's own ALLOWLIST.
+process.stdout.write('\n');
+if (runCheck('check-metrics-ledger-root.mjs') !== 0) checkFailed = 1;
+
 // BLOCKING (#1184): every scripts/lib/validate/check-*.mjs must be referenced
 // by basename from this file, .husky/pre-commit, or .gitlab-ci.yml — or carry
 // a `// registration: standalone <reason>` header marker declaring itself

package/scripts/vault-integration-watcher.mjs

@@ -31,6 +31,9 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { sep as pathSep } from 'node:path';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { resolveRepoSpec, redactUrlCredentials } from './lib/vcs-repo-spec.mjs';
@@ -278,15 +281,59 @@ function buildTickBody(issueMap, depIds, verdict, streak, date) {
 - Verdict: ${verdict}`;
 }
 
+/**
+ * Canonical spelling of an absolute path: realpath (native) when it exists, else as given.
+ * On macOS the native realpath also returns the on-disk letter case.
+ * @param {string} p
+ * @returns {string}
+ */
+function canonicalPath(p) {
+  try {
+    return realpathSync.native(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Path of `root` relative to the home dir, or null when it is not under home (#1622).
+ *
+ * Both sides go through realpath first, so symlinks and (on macOS) a differently
+ * cased spelling of an existing dir resolve to the same string. A root that does not
+ * exist cannot be canonicalised; on darwin/win32 the default volumes are
+ * case-insensitive, so the prefix compare is case-folded there as a fallback.
+ * Ceiling: a case-sensitive APFS volume could fold two distinct non-existent paths
+ * together; the snippet would then name a dir that is not there either way.
+ * @param {string} root
+ * @returns {string|null} '' when root IS home, the relative rest when inside, else null
+ */
+function homeRelative(root) {
+  const home = canonicalPath(homedir());
+  const canonRoot = canonicalPath(root);
+  const fold = process.platform === 'darwin' || process.platform === 'win32';
+  const cmp = (s) => (fold ? s.toLocaleLowerCase('en-US') : s);
+  if (cmp(canonRoot) === cmp(home)) return '';
+  for (const sep of new Set(['/', pathSep])) {
+    if (cmp(canonRoot).startsWith(cmp(`${home}${sep}`))) return canonRoot.slice(home.length + 1);
+  }
+  return null;
+}
+
 /**
  * Build the flip-ready trigger comment body.
  * @param {string[]} repos
+ * @param {string} root — projects root the repo names resolve against
+ *   (getConfinementRoot(), so the snippet follows `projects-root`, #1567)
  * @returns {string}
  */
-function buildFlipBody(repos) {
+function buildFlipBody(repos, root) {
   // Defense-in-depth: regex+confinement upstream already filter, but shell-quote here
   // makes the embedded bash safe under any future bypass.
   const repoList = repos.map(shellQuote).join(' ');
+  // The body is posted to a GitLab issue: a root under the home dir is written
+  // as "$HOME"/… so the comment never carries the owner's home path (#1490).
+  const rel = homeRelative(root);
+  const rootQ = rel === null ? shellQuote(root) : rel === '' ? '"$HOME"' : `"$HOME"/${shellQuote(rel)}`;
   // The sed/add/commit one-liner targets the project-instruction file. Most
   // ecosystem repos use CLAUDE.md, but Codex-CLI repos use AGENTS.md as a
   // transparent alias — see skills/_shared/instruction-file-resolution.md.
@@ -296,14 +343,15 @@ function buildFlipBody(repos) {
 
 Lokaler Befehl (ein-Liner pro Repo, aber besser per Session orchestriert; CLAUDE.md and AGENTS.md sind Aliase):
 \`\`\`bash
+root=${rootQ}
 for d in ${repoList}; do
   for f in CLAUDE.md AGENTS.md; do
-    [ -s ~/Projects/$d/$f ] || continue
-    sed -i.bak 's/mode: warn }/mode: strict }/' ~/Projects/$d/$f
-    git -C ~/Projects/$d add $f
+    [ -s "$root/$d/$f" ] || continue
+    sed -i.bak 's/mode: warn }/mode: strict }/' "$root/$d/$f"
+    git -C "$root/$d" add "$f"
     break
   done
-  git -C ~/Projects/$d commit -m 'chore(orchestrator): Promote vault-integration to strict mode — closes #305'
+  git -C "$root/$d" commit -m 'chore(orchestrator): Promote vault-integration to strict mode — closes #305'
 done
 \`\`\``;
 }
@@ -402,7 +450,7 @@ async function main() {
   // 7. If streak == 3 (or more), post flip-ready trigger
   if (newStreak >= 3) {
     log(`streak=${newStreak} >= 3 — posting flip-ready trigger`);
-    postComment(TRACKING_ISSUE, buildFlipBody(flipRepos));
+    postComment(TRACKING_ISSUE, buildFlipBody(flipRepos, watcherRoot));
     emit({ action: 'flip-ready-posted', issue: TRACKING_ISSUE });
   }
 

package/scripts/vault-mirror.mjs

@@ -798,6 +798,15 @@ async function main() {
   // into `total` like any other line, so the run partition still holds. A
   // malformed archive line is reported and skipped — the archive is secondary
   // input and must not abort a mirror run that already wrote the live store.
+  //
+  // Boundary (BV-004, #1685): the sibling `learnings-inbox.jsonl` (#1516) is
+  // deliberately NOT a mirror source: the mirror reads only the live store (it
+  // checks no store role, and session-end runs it on every host). An inbox
+  // record gets its note on the first mirror run after it is ingested into the
+  // live store, on whichever host that run happens. Ceiling: an inbox host
+  // never mirrors its inbox-only learnings, and every note for an inbox record
+  // lags one ingest. Revisit when a real inbox host needs vault notes before
+  // ingest.
   if (kind === 'learning' && basename(resolve(source)) === 'learnings.jsonl') {
     const archivePath = join(dirname(resolve(source)), 'learnings-archive.jsonl');
     if (existsSync(archivePath)) {

package/scripts/vault-orphans.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * vault-orphans.mjs - CLI for `findVaultOrphans` (#1563, session-end Phase 3.7e).
+ *
+ * Names the untracked files in the Meta-Vault modified since a given instant
+ * (the session's start). Read-only: it never commits, moves or deletes anything
+ * in the vault. See scripts/lib/session-end/vault-orphans.mjs for the design.
+ *
+ * USAGE
+ *   node scripts/vault-orphans.mjs --since <ISO> [--vault-dir <dir>] [--json]
+ *
+ * EXIT CODES
+ *   0  measured (including zero candidates)
+ *   1  bad arguments
+ *   2  could not measure (no vault dir resolvable, not a git repo, git failed)
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { findVaultOrphans } from './lib/session-end/vault-orphans.mjs';
+import { _parseVaultIntegration } from './lib/config/vault-integration.mjs';
+import { loadHostPaths } from './lib/config/host-paths.mjs';
+import { resolveVaultDir } from './lib/config.mjs';
+import { expandTilde } from './lib/common.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const HELP = `vault-orphans.mjs - name untracked vault files written since a session started (#1563)
+
+USAGE
+  node scripts/vault-orphans.mjs --since <ISO> [--vault-dir <dir>] [--json]
+
+DESCRIPTION
+  Runs the read-only \`git -C <vault-dir> ls-files --others --exclude-standard\`
+  and lists every untracked file whose mtime is at or after --since. Files whose
+  frontmatter names one of this plugin's generators (\`_generator:
+  session-orchestrator-...\`) are left out: their writer owns them.
+
+  The results are CANDIDATES: mtime is a hint, not proof that this session
+  wrote the file. Nothing is committed, moved or deleted.
+
+OPTIONS
+  --since <ISO>       Required. ISO 8601 instant with Z or an offset, e.g. the
+                      STATE.md \`started_at\` (2026-10-11T08:00:00.000Z).
+  --vault-dir <dir>   Vault working tree. Default: the host-local resolution
+                      SO_VAULT_DIR > owner.yaml > committed
+                      vault-integration.vault-dir in ./CLAUDE.md or ./AGENTS.md.
+  --json              Print the result object as JSON on stdout.
+  --help              Show this help.
+  --version           Print the plugin version.
+
+EXIT CODES
+  0  measured, including zero candidates
+  1  bad arguments
+  2  could not measure (no vault dir, not a git repo, git failed)
+
+EXAMPLE
+  node scripts/vault-orphans.mjs --since 2026-10-11T08:00:00.000Z --json
+`;
+
+/** ISO 8601 with an explicit zone - a zone-less value would be read as local time. */
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * Resolve the vault dir like the other vault writers: SO_VAULT_DIR > owner.yaml
+ * `vault-dirs:` cwd match > owner.yaml `paths.vault-dir` > committed value.
+ *
+ * @returns {string|null}
+ */
+function resolveDefaultVaultDir() {
+  let content = '';
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    const p = join(process.cwd(), name);
+    if (existsSync(p)) {
+      try {
+        content = readFileSync(p, 'utf8');
+        break;
+      } catch {
+        /* try the next file */
+      }
+    }
+  }
+  const vi = _parseVaultIntegration(content);
+  const value = resolveVaultDir(vi['vault-dir'], loadHostPaths()).value;
+  return typeof value === 'string' && value.trim() !== '' ? expandTilde(value) : null;
+}
+
+/** @param {{status: 'ok', candidates: Array<{path: string}>, total: number, truncated: boolean, untracked: number}} r */
+function renderHuman(r, since) {
+  const lines = [];
+  if (r.total === 0) {
+    lines.push(`vault-orphans: no untracked vault file modified since ${since} (${r.untracked} untracked in total)`);
+  } else {
+    lines.push(
+      `vault-orphans: ${r.total} untracked vault file(s) modified since ${since} - candidates only, ` +
+        `mtime does not prove this session wrote them (${r.untracked} untracked in total)`,
+    );
+    for (const c of r.candidates) lines.push(`  ${c.path}`);
+    if (r.truncated) lines.push(`  ... showing ${r.candidates.length} of ${r.total}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * CLI entry.
+ *
+ * @param {string[]} [argv]
+ * @param {{stdout: {write: Function}, stderr: {write: Function}}} [io]
+ * @returns {number} exit code
+ */
+export function main(argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        since: { type: 'string' },
+        'vault-dir': { type: 'string' },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', default: false },
+        version: { type: 'boolean', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    io.stderr.write(`vault-orphans: ${err.message}\nRun with --help for usage.\n`);
+    return 1;
+  }
+
+  if (values.help) {
+    io.stdout.write(HELP);
+    return 0;
+  }
+  if (values.version) {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    io.stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+
+  const since = values.since;
+  const sinceMs = typeof since === 'string' && ISO_RE.test(since) ? Date.parse(since) : NaN;
+  if (!Number.isFinite(sinceMs)) {
+    io.stderr.write('vault-orphans: --since <ISO> is required, e.g. 2026-10-11T08:00:00.000Z\n');
+    return 1;
+  }
+  if (values['vault-dir'] !== undefined && values['vault-dir'].trim() === '') {
+    io.stderr.write('vault-orphans: --vault-dir must not be empty\n');
+    return 1;
+  }
+
+  const vaultDir =
+    values['vault-dir'] !== undefined ? expandTilde(values['vault-dir']) : resolveDefaultVaultDir();
+  const result = findVaultOrphans({ vaultDir, sinceMs });
+
+  if (result.status !== 'ok') {
+    io.stderr.write(
+      `vault-orphans: could not measure (${result.reason}${result.detail ? `: ${result.detail}` : ''})\n`,
+    );
+    if (values.json) io.stdout.write(`${JSON.stringify(result)}\n`);
+    return 2;
+  }
+
+  io.stdout.write(values.json ? `${JSON.stringify(result)}\n` : renderHuman(result, since));
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main();
+}