session-orchestrator 5.4.0 → 5.6.0

package/hooks/wave-scope-commit-guard.mjs

@@ -22,26 +22,49 @@
 //   agent's fence — i.e. another agent's intent to stage that path.
 //
 // Behavior summary
-//   - No .orchestrator/wave-scope.json → exit 0 (no active wave; sub-mode B
-//     short-circuits). Sub-mode C still runs if a fence directory exists.
-//   - Allowed paths violation → exit 1 with restore hint.
+//   - No wave-scope.json → exit 0 (no active wave; sub-mode B short-circuits).
+//     Sub-mode C still runs if a fence directory exists.
+//   - Sub-mode B, in order (#1493.1): a manifest bound to ANOTHER session is
+//     not this commit's scope (stand down, one stderr note); `enforcement:
+//     "off"` skips.
+//   - Non-empty allowedPaths: a staged path outside it BLOCKS (exit 1) under
+//     every enforcement level, `warn` included. Deliberately not tied to
+//     `enforcement`: in a warn-mode wave enforce-scope lets out-of-scope writes
+//     through, so this guard is the only hard PSA-004 stop left for a
+//     lint-staged sweep — softening it would weaken detection for the very
+//     class it exists to catch.
+//   - EMPTY allowedPaths is no longer a silent pass: a Discovery (read-only)
+//     manifest means no agent is committing, i.e. a coordinator commit between
+//     waves → allow with a note; a manifest older than the newest session
+//     clock may be a leftover or a parallel session's live one → report,
+//     never block; any other role means the `--union` step never completed →
+//     `strict` (the default when the field is absent, as in enforce-scope)
+//     blocks, `warn` reports and lets the commit through. Only this new
+//     verdict follows `enforcement`: it judges the coordinator's own
+//     bookkeeping, not a staged foreign file.
 //   - Cross-agent fence overlap → exit 1 with "staging-fence: cross-agent
 //     overlap" stderr.
 //   - --no-verify bypass: this hook is invoked as a git pre-commit hook;
 //     `git commit --no-verify` skips it entirely (operator opts out by name).
 
 import { execSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
 
 // Re-use existing helpers from scripts/lib/hardening.mjs.
 // IMPORTANT: import is resolved relative to THIS file's location (the hook
 // ships with the session-orchestrator package), NOT relative to the git
 // repo it is protecting. The two diverge when the hook is invoked from a
 // consumer repo or a test tmp-dir.
-import { pathMatchesPattern, findScopeFile } from '../scripts/lib/hardening.mjs';
+import { pathMatchesPattern } from '../scripts/lib/hardening.mjs';
 import { withStagingFenceLock } from '../scripts/lib/session-lock.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
+import { resolveSessionRoot } from '../scripts/lib/platform.mjs';
+import { classifyEmptyScope, findOwnScopeFile, sessionAgeMs } from '../scripts/lib/scope-gate.mjs';
+import {
+  classifyManifestSession,
+  readProcessLocalSessionIds,
+} from '../scripts/lib/session-identity/own-session.mjs';
 
 // Resolve the "current" agent id from SO_WAVE_AGENT_ID (when set by the
 // caller) or fall back to a PID-derived marker. The fence files themselves
@@ -56,19 +79,6 @@ const ownAgentId = process.env.SO_WAVE_AGENT_ID ?? null;
  */
 const ALL_PATHS_MARKER = '*';
 
-/**
- * Build a regex that finds a staged path inside a `git add` command string.
- * Word-boundary on both sides so `src/foo.ts` does not match `src/foo.ts.bak`.
- * The path is escaped so glob metacharacters (`*`, `?`) and shell metas
- * cannot be reinterpreted.
- *
- * LEGACY PATH ONLY since #1404 — see the fallback branch in findOverlaps.
- */
-function pathRegex(p) {
-  const escaped = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  return new RegExp(`(?:^|[\\s'"])${escaped}(?:$|[\\s'"])`);
-}
-
 /**
  * Normalise a path token so reader and writer compare the same spelling.
  *
@@ -107,19 +117,13 @@ function pathsOverlap(fencePath, ourPath) {
  * Walk a single sibling fence file and return the staged paths a sibling
  * agent also recorded an intent to stage.
  *
- * Two entry shapes are accepted:
- *  - #1404 shape `{ paths, command_hash, timestamp }` — path LISTS compared
- *    against our staged set.
- *  - LEGACY shape `{ command, timestamp }` — a fence file written by a
- *    pre-#1404 hook version. Live sessions on this host may hold such files
- *    RIGHT NOW, and dropping them would read as "no overlap" — silently
- *    weaker than before the change. So the old raw-command regex still runs
- *    for an entry that has `command` and no `paths`.
- *    NAMED CEILING (BV-004): this fallback exists only to span the sessions
- *    running across the upgrade. REVISIT TRIGGER — remove it one minor
- *    release after 5.3.0 (i.e. in 5.4.0), by which point no process started
- *    before the upgrade can still be writing fence files. The command text it
- *    reads is never PRINTED (issue #1404) — only the fact of the match is.
+ * One entry shape is read: the #1404 `{ paths, command_hash, timestamp }`,
+ * whose path LIST is compared against our staged set. An entry without a
+ * `paths` array is skipped — that includes the pre-#1404 `{ command }` shape,
+ * whose raw-command regex fallback was removed in 5.4.x as its own revisit
+ * trigger demanded (#1487 point 16): the only fence writer,
+ * hooks/pre-bash-staging-fence.mjs, has written `paths` + `command_hash` and
+ * never `command` since 5.3.0, and no other hook or bridge writes fence files.
  */
 function findOverlaps(fenceJsonPath, ourStaged) {
   let body;
@@ -135,36 +139,159 @@ function findOverlaps(fenceJsonPath, ourStaged) {
   const siblingAgent = body.agent_id ?? '<unknown>';
   const matches = [];
   for (const entry of body.staged_paths) {
-    if (Array.isArray(entry?.paths)) {
-      const hash = typeof entry.command_hash === 'string' ? entry.command_hash : '<no-hash>';
-      for (const raw of entry.paths) {
-        if (typeof raw !== 'string') continue;
-        const fencePath = normalizeStagedPath(raw);
-        for (const ours of ourStaged) {
-          if (pathsOverlap(fencePath, normalizeStagedPath(ours))) {
-            matches.push({ ourPath: ours, siblingAgent, fencePath, hash });
-          }
+    if (!Array.isArray(entry?.paths)) continue;
+    const hash = typeof entry.command_hash === 'string' ? entry.command_hash : '<no-hash>';
+    for (const raw of entry.paths) {
+      if (typeof raw !== 'string') continue;
+      const fencePath = normalizeStagedPath(raw);
+      for (const ours of ourStaged) {
+        if (pathsOverlap(fencePath, normalizeStagedPath(ours))) {
+          matches.push({ ourPath: ours, siblingAgent, fencePath, hash });
         }
       }
-      continue;
-    }
-
-    const cmd = entry?.command;
-    if (typeof cmd !== 'string') continue;
-    for (const ours of ourStaged) {
-      if (pathRegex(ours).test(cmd)) {
-        matches.push({
-          ourPath: ours,
-          siblingAgent,
-          fencePath: '<legacy entry, pre-#1404>',
-          hash: '<legacy entry, pre-#1404>',
-        });
-      }
     }
   }
   return matches;
 }
 
+/** mtime of a file in ms, or `null` when it cannot be stat'ed. */
+function mtimeMsOf(file) {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sub-mode B's decision, pure: which lines to print and whether to block.
+ *
+ * Until #1493.1 an empty `allowedPaths` skipped the check outright, the
+ * manifest's `role` and `enforcement: "off"` were never read, and a PEER
+ * session's manifest governed this session's commits. Each rung below closes
+ * one of those; the order is load-bearing — ownership first (a foreign
+ * manifest's enforcement level is not ours to honour), then `off`, then the
+ * verdict. `warn` softens ONLY the empty-union verdict; a non-empty violation
+ * blocks at every level (header § Behavior summary).
+ *
+ * @param {object} p
+ * @param {Record<string, unknown>} p.scope parsed manifest
+ * @param {string[]} p.stagedFiles  repo-relative, as `git diff --cached` prints them
+ * @param {(f: string) => string|null} [p.scopePathOf]  a staged path as the
+ *   manifest names it — relative to the SESSION root; identity when that is the
+ *   repo root. `null` = the path lies OUTSIDE the session root: a violation
+ *   without pattern matching, since a `../`-prefixed path would match a glob
+ *   like `**\/*.mjs` and enforce-scope denies every write outside its root
+ *   (REQ-04).
+ * @param {string} p.scopeRel manifest path for messages, repo-relative
+ * @param {Set<string>} p.ownIds this process's session ids
+ * @param {number|null} p.scopeMtimeMs
+ * @param {number|null} p.sessionAge ms since the newest session clock
+ * @returns {{action: 'pass'|'report'|'block', lines: string[]}}
+ */
+function scopeCommitVerdict({ scope, stagedFiles, scopePathOf = (f) => f, scopeRel, ownIds, scopeMtimeMs, sessionAge }) {
+  if (stagedFiles.length === 0) return { action: 'pass', lines: [] };
+
+  // Same classifier and same disposition as enforce-scope Gate 3b: only a
+  // PROVABLY foreign manifest stands down; unknown ownership enforces.
+  if (classifyManifestSession(scope, ownIds).verdict === 'foreign') {
+    return {
+      action: 'pass',
+      lines: [`wave-scope-commit-guard: ${scopeRel} belongs to another session — its allowedPaths do not apply to this commit.`],
+    };
+  }
+
+  const enforcement = scope.enforcement ?? 'strict';
+  if (enforcement === 'off') return { action: 'pass', lines: [] };
+
+  const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
+  if (allowedPaths.length > 0) {
+    const violations = stagedFiles.filter(
+      (f) => {
+        const scoped = scopePathOf(f);
+        return scoped === null || !allowedPaths.some((pattern) => pathMatchesPattern(scoped, pattern));
+      },
+    );
+    if (violations.length === 0) return { action: 'pass', lines: [] };
+    // Blocks under `warn` too — see the header: in a warn-mode wave this is
+    // the only hard stop a lint-staged sweep meets before the commit exists.
+    return {
+      action: 'block',
+      lines: [
+        '✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:',
+        ...violations.map((v) => `  - ${v}`),
+        '',
+        'These files were likely added by lint-staged eslint --fix / prettier --write.',
+        'To proceed:',
+        '  1) git restore --staged <path>   # for each foreign path',
+        '  2) git commit                    # retry',
+      ],
+    };
+  }
+
+  // From here on the verdict judges the coordinator's own bookkeeping (an empty
+  // union), not a staged foreign file — only this part follows `enforcement`.
+  const failAction = enforcement === 'strict' ? 'block' : 'report';
+
+  const role = typeof scope.role === 'string' ? scope.role.trim() : '';
+  const reason = classifyEmptyScope({
+    role,
+    parseOk: true,
+    scopeMtimeMs,
+    sessionStartMs: typeof sessionAge === 'number' ? Date.now() - sessionAge : null,
+  });
+  if (reason === 'read-only-role') {
+    // No wave agent commits (PSA-007), so a commit under a read-only manifest
+    // is the coordinator's own, between waves.
+    return {
+      action: 'pass',
+      lines: [`wave-scope-commit-guard: ${scopeRel} is a ${role} (read-only) manifest — treated as a coordinator commit between waves; allowedPaths not checked.`],
+    };
+  }
+  if (reason === 'stale-manifest') {
+    // Older than the newest session clock of this working copy: a leftover OR a
+    // parallel session's live manifest, which the clocks cannot tell apart
+    // (scope-gate.mjs § "…and the reader may not be the OWNER") — so it is
+    // never grounds to block this commit.
+    return {
+      action: 'report',
+      lines: [`⚠ wave-scope-commit-guard: ${scopeRel} grants no paths and predates the newest session start in this working copy — a leftover or a parallel session's live manifest; allowedPaths not checked for this commit.`],
+    };
+  }
+  return {
+    action: failAction,
+    lines: [
+      `${failAction === 'block' ? '✗' : '⚠'} wave-scope-commit-guard: ${scopeRel} grants no paths${role ? ` for role \`${role}\`` : ''} — the coordinator's \`--union\` step did not complete, so none of the ${stagedFiles.length} staged path(s) can be checked against this wave's scope.`,
+      'Re-run the union step (skills/wave-executor/references/wave-loop-scope-manifest.md § 3.3), then retry the commit; do not hand-edit allowedPaths.',
+      ...(failAction === 'block' ? [] : ['(enforcement: warn — reported, the commit proceeds)']),
+    ],
+  };
+}
+
+/**
+ * The session root a commit at `repoRoot` is judged against when it lies
+ * STRICTLY inside the repo, else `null` (judge at `repoRoot`, as before) — see
+ * the call site in `main()` (#1511 point d). Both sides realpath-resolved, so
+ * macOS `/var` vs `/private/var` cannot split one directory in two.
+ *
+ * @param {string} repoRoot  `git rev-parse --show-toplevel`
+ * @returns {{sessionRoot: string, realRepoRoot: string}|null}
+ */
+function subdirSessionRoot(repoRoot) {
+  const canon = (p) => {
+    // `.native` canonicalises letter case on case-insensitive APFS (as
+    // enforce-scope's clamp does since #1504 pt 8); the JS realpath keeps a
+    // case-different CLAUDE_PROJECT_DIR verbatim, which relativises to `../..`
+    // against the git toplevel and switches the subdirectory mode off silently.
+    try { return realpathSync.native(p); } catch { return p; }
+  };
+  const realRepoRoot = canon(repoRoot);
+  const sessionRoot = canon(resolveSessionRoot(repoRoot, repoRoot));
+  const rel = relative(realRepoRoot, sessionRoot);
+  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
+  return { sessionRoot, realRepoRoot };
+}
+
 /**
  * Both sub-modes, in the order the pre-commit hook needs them. Every statement
  * here used to sit at module top level, which meant a bare `import()` of this
@@ -181,7 +308,42 @@ async function main() {
   // skills/wave-executor/wave-loop.md), so this guard never fired. findScopeFile
   // returns null when no scope file exists at any precedence dir, preserving
   // the "no active wave → exit 0" semantics below.
-  const scopePath = findScopeFile(repoRoot);
+  //
+  // #1504 point 6: the first manifest that is not provably a peer's, so a
+  // peer's higher-precedence manifest no longer hides this session's own one;
+  // when every candidate is foreign the first comes back and
+  // `scopeCommitVerdict` passes it as before. The git process inherits the
+  // committing session's env; there is no hook payload here, so the env tier is
+  // the only process-local identity.
+  const ownIds = new Set(readProcessLocalSessionIds());
+
+  // #1511 point d — ALSO read the manifest at the SESSION root the scope guards
+  // resolve (`resolveSessionRoot`, enforce-scope.mjs): a session launched in a
+  // repo SUBDIRECTORY keeps its manifest there, so the repo root held none and
+  // sub-mode B never ran for it. git runs this hook at the worktree top level
+  // and the committing session's env (the launch dir) is inherited, so the
+  // toplevel stands in for the payload `cwd` the Edit/Write guards get. Only a
+  // root STRICTLY inside the repo is adopted: the one rung that answers above it
+  // (a harness `agent-<hex>` worktree lifted to its launch checkout) would judge
+  // this repo's staged paths against another tree's manifest.
+  //
+  // The repo-root manifest is ALWAYS judged exactly as before #1511 d, and the
+  // subdirectory manifest is judged IN ADDITION, each against its own path
+  // mapping; either one blocking blocks. So the verdict is never laxer than the
+  // repo-root-only guard it extends — choosing ONE of the two manifests let an
+  // unbound or `enforcement: off` subdirectory manifest silence a repo-root wave
+  // that blocked the same commit (second review, MED-1).
+  const subdir = subdirSessionRoot(repoRoot);
+  const judgements = [{ root: repoRoot, scopePathOf: (f) => f }];
+  if (subdir !== null) {
+    judgements.push({
+      root: subdir.sessionRoot,
+      scopePathOf: (f) => {
+        const rel = relative(subdir.sessionRoot, join(subdir.realRepoRoot, f));
+        return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) ? null : rel;
+      },
+    });
+  }
   const fenceDir = join(repoRoot, '.orchestrator', 'staging-fence');
 
   // -------------------------------------------------------------------------
@@ -191,7 +353,11 @@ async function main() {
   const stagedOutput = execSync('git diff --cached --name-only', { encoding: 'utf8' });
   const stagedFiles = stagedOutput.split('\n').filter(Boolean);
 
-  if (scopePath) {
+  let blocked = false;
+  for (const { root, scopePathOf } of judgements) {
+    const located = findOwnScopeFile(root, ownIds, classifyManifestSession);
+    const scopePath = located.path ?? located.foreignPath;
+    if (!scopePath) continue;
     let scope;
     try {
       scope = JSON.parse(readFileSync(scopePath, 'utf8'));
@@ -200,23 +366,19 @@ async function main() {
       process.exit(1);
     }
 
-    const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
-    if (allowedPaths.length > 0) {
-      const violations = stagedFiles.filter(
-        (f) => !allowedPaths.some((pattern) => pathMatchesPattern(f, pattern)),
-      );
-
-      if (violations.length > 0) {
-        process.stderr.write('✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:\n');
-        for (const v of violations) process.stderr.write(`  - ${v}\n`);
-        process.stderr.write('\nThese files were likely added by lint-staged eslint --fix / prettier --write.\n');
-        process.stderr.write('To proceed:\n');
-        process.stderr.write('  1) git restore --staged <path>   # for each foreign path\n');
-        process.stderr.write('  2) git commit                    # retry\n');
-        process.exit(1);
-      }
-    }
+    const verdict = scopeCommitVerdict({
+      scope: scope !== null && typeof scope === 'object' ? scope : {},
+      stagedFiles,
+      scopePathOf,
+      scopeRel: relative(repoRoot, scopePath) || scopePath,
+      ownIds,
+      scopeMtimeMs: mtimeMsOf(scopePath),
+      sessionAge: sessionAgeMs(root),
+    });
+    for (const line of verdict.lines) process.stderr.write(`${line}\n`);
+    if (verdict.action === 'block') blocked = true;
   }
+  if (blocked) process.exit(1);
 
   // -------------------------------------------------------------------------
   // Sub-mode C — cross-agent staging-fence reconciliation (issue #552)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "session-orchestrator",
-  "version": "5.4.0",
-  "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
+  "version": "5.6.0",
+  "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementation wave, /close runs the full gate, verifies, commits and files the rest as issues. Scope and destructive-command guards, crash-safe resume, learnings you approve. For Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
   "keywords": [
@@ -16,7 +16,12 @@
     "orchestration",
     "developer-tools",
     "mcp",
-    "llm"
+    "llm",
+    "workflow",
+    "quality-gates",
+    "ai-coding",
+    "gitlab",
+    "github"
   ],
   "engines": {
     "node": ">=24.0.0"
@@ -54,6 +59,7 @@
     "!**/.DS_Store"
   ],
   "scripts": {
+    "update:local": "node scripts/self-update.mjs",
     "test": "node scripts/check-package-manager.mjs && vitest --run",
     "test:coverage": "node scripts/check-package-manager.mjs && vitest --run --coverage",
     "test:watch": "node scripts/check-package-manager.mjs && vitest",
@@ -92,11 +98,6 @@
     "prettier": "^3.0.0",
     "vitest": "^4.1.11"
   },
-  "overrides": {
-    "vite": "^8.0.16",
-    "fast-uri": "^3.1.8",
-    "brace-expansion": "^5.0.12"
-  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/apply-session-learnings.mjs

@@ -62,18 +62,22 @@
  * Telemetry: `--apply` emits `orchestrator.learnings.session_write_applied`
  * after the write — its presence is the proof the write ran. Best-effort: a
  * telemetry failure never changes the exit code. Skipped (stderr WARN) when
- * `--file` lies outside `--repo-root`, so the record is never pinned to a repo
+ * `--file` lies outside `--repo-root` after resolving symlinks on both sides,
+ * so the record is never pinned to a repo
  * whose store was not written.
  *
  * Exit codes:
  *   0  Success (including a no-op)
  *   1  Usage/input/validation error — nothing written
- *   2  Library/IO error (unreadable store, malformed store lines on --apply,
- *      a failure inside the prune/rewrite, store lock not acquired)
+ *   2  Library/IO error (unreadable store, a failure inside the
+ *      prune/rewrite, store lock not acquired). Unparseable store lines are
+ *      NOT an error: they are kept verbatim, counted as `malformed` in the
+ *      summary, and WARNed on stderr with their line numbers.
  */
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
+import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { LearningsLockError, readLearnings, withLearningsLock } from './lib/learnings/io.mjs';
 import { pruneLearnings } from './lib/learnings/expiry-sweep.mjs';
 import {
@@ -310,9 +314,29 @@ export function buildNextGeneration({ current, updates, newLearnings, decayRate,
   return { next, confirmed, contradicted, appended: newIds.size, decayed, undecayable };
 }
 
+/**
+ * A path resolved through symlinks when it exists, else absolute as given.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function canonicalPath(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
 async function emitSessionWriteApplied({ repoRoot, filePath, payload }) {
-  const rel = path.relative(repoRoot, filePath);
-  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+  // Canonical, not lexical (#1506.4b; same check as sweep-expired-learnings
+  // --drop-malformed, #1500 F4): a store reached through a symlinked directory
+  // inside the repo but living outside it is refused, and a root spelled
+  // through a symlink (macOS /var → /private/var) still accepts the store
+  // inside it. Runs after the write, so the store exists and resolves.
+  const file = canonicalPath(filePath);
+  const rel = path.relative(canonicalPath(repoRoot), file);
+  if (!validatePathInsideProject(file, repoRoot, { canonicalizeRoot: true }).ok) {
     process.stderr.write(
       `apply-session-learnings: skipped ${SESSION_WRITE_EVENT} — ${filePath} lies outside ` +
         `--repo-root ${repoRoot}\n`,
@@ -377,14 +401,11 @@ async function main(argv) {
       process.stderr.write(`apply-session-learnings: cannot read ${filePath}: ${err.message}\n`);
       return { code: 2 };
     }
-    if (opts.apply && read.malformed.length > 0) {
-      // pruneLearnings rewrites from parsed entries only — a malformed line
-      // would vanish without an archive record.
-      process.stderr.write(
-        `apply-session-learnings: refusing to rewrite — ${read.malformed.length} malformed line(s) in ${filePath}\n`,
-      );
-      return { code: 2 };
-    }
+    // A malformed store line is no reason to refuse (#1489): pruneLearnings()
+    // keeps it verbatim at the end of the rewritten store, never archives it,
+    // and prints the WARN; the count rides on the summary as `malformed`.
+    // Refusing here blocked the session-end learnings write on every close,
+    // because nothing on the sanctioned write path ever removes such a line.
 
     let built;
     try {

package/scripts/archive-closed-prds.mjs

@@ -44,7 +44,7 @@ import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 
-import { findProjectRoot, resolveInstructionFile, warn } from './lib/common.mjs';
+import { findProjectRoot, redactHomeDir, resolveInstructionFile, warn } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
 import { glabRun as defaultGlabRun } from './lib/vault-backfill/glab.mjs';
 import { archiveFileToVault, titleFromMarkdown } from './lib/vault-archive.mjs';
@@ -381,8 +381,13 @@ EXIT CODES
 }
 
 function printHuman(archived, skipped, isDryRun, vaultDir, vaultSubdir) {
+  // Runs as a custom phase at every session start and end, so this line lands
+  // in every transcript — home dir as `~` (#1490). `--json` keeps the real
+  // `vaultDir`: that field is a machine contract, not a log line. A
+  // `skipped[].reason` is redacted in BOTH outputs — it carries fs error text,
+  // and main() redacts it before it enters the array (8273d97a).
   process.stdout.write(
-    `Doc archive ${isDryRun ? '(dry-run)' : '(apply)'} → ${vaultDir}/${vaultSubdir}\n`,
+    `Doc archive ${isDryRun ? '(dry-run)' : '(apply)'} → ${redactHomeDir(`${vaultDir}/${vaultSubdir}`)}\n`,
   );
   if (archived.length > 0) {
     process.stdout.write(`  ${isDryRun ? 'WOULD ARCHIVE' : 'ARCHIVED'} (${archived.length}):\n`);
@@ -488,19 +493,38 @@ export function main({
   const root = repoRoot ?? findProjectRoot();
   const instr = resolveInstructionFile(root);
   if (!instr) {
-    process.stderr.write(`archive-closed-prds: no CLAUDE.md/AGENTS.md at ${root}.\n`);
+    process.stderr.write(`archive-closed-prds: no CLAUDE.md/AGENTS.md at ${redactHomeDir(root)}.\n`);
     return { code: 1, archived: [], skipped: [] };
   }
 
   let vaultDir;
+  let vaultIntegration;
   try {
     const content = readFileSync(instr.path, 'utf8');
     const config = parseSessionConfig(content, hostPaths ? { hostPaths } : undefined);
-    vaultDir = config?.['vault-integration']?.['vault-dir'];
+    vaultIntegration = config?.['vault-integration'];
+    vaultDir = vaultIntegration?.['vault-dir'];
   } catch (err) {
-    process.stderr.write(`archive-closed-prds: failed to parse Session Config: ${err.message}\n`);
+    process.stderr.write(`archive-closed-prds: failed to parse Session Config: ${redactHomeDir(err.message)}\n`);
     return { code: 2, archived: [], skipped: [] };
   }
+  // The switch every vault writer obeys (board-writer, narrative-mirror): off
+  // → nothing archived, exit 0. parseSessionConfig has already applied the
+  // host-local lowering (resolveVaultIntegrationHost: env SO_VAULT_INTEGRATION
+  // > owner.yaml > committed). This runs with --apply at every session start
+  // and end, so ignoring it wrote PRDs into the vault and git-rm'd them (#1496).
+  if (vaultIntegration?.enabled !== true) {
+    const override = vaultIntegration?.['host-override'];
+    const disabled = `vault-integration is ${override ? `switched off by ${override}` : 'not enabled'} — nothing archived`;
+    if (json) {
+      process.stdout.write(
+        JSON.stringify({ dryRun: isDryRun, vaultDir: null, vaultSubdir, archived: [], skipped: [], disabled }, null, 2) + '\n',
+      );
+    } else {
+      process.stdout.write(`Doc archive: ${disabled}\n`);
+    }
+    return { code: 0, archived: [], skipped: [] };
+  }
   if (!vaultDir || typeof vaultDir !== 'string' || vaultDir.trim() === '') {
     process.stderr.write(
       'archive-closed-prds: vault-integration.vault-dir is not configured — cannot archive.\n',
@@ -534,8 +558,10 @@ export function main({
     try {
       header = readHeaderRegion(abs);
     } catch (err) {
-      skipped.push({ source: rel, reason: `unreadable: ${err.message}` });
-      warn(`archive-closed-prds: cannot read ${rel}: ${err.message}`);
+      // fs errors name the ABSOLUTE path they failed on (#1490).
+      const msg = redactHomeDir(err.message);
+      skipped.push({ source: rel, reason: `unreadable: ${msg}` });
+      warn(`archive-closed-prds: cannot read ${rel}: ${msg}`);
       continue;
     }
 
@@ -603,8 +629,9 @@ export function main({
         title: titleFromMarkdown(header),
       });
     } catch (err) {
-      skipped.push({ source: rel, reason: `archive-failed: ${err.message}`, iid, via, ownership });
-      warn(`archive-closed-prds: failed to archive ${rel}: ${err.message}`);
+      const msg = redactHomeDir(err.message);
+      skipped.push({ source: rel, reason: `archive-failed: ${msg}`, iid, via, ownership });
+      warn(`archive-closed-prds: failed to archive ${rel}: ${msg}`);
       continue;
     }
     entry.iid = iid;
@@ -614,7 +641,7 @@ export function main({
     if (!isDryRun) {
       const rm = gitRunFn(['-C', root, 'rm', '--', rel]);
       entry.removed = rm.ok;
-      if (!rm.ok) warn(`archive-closed-prds: 'git rm ${rel}' failed: ${rm.stderr.trim()}`);
+      if (!rm.ok) warn(`archive-closed-prds: 'git rm ${rel}' failed: ${redactHomeDir(rm.stderr.trim())}`);
     }
 
     archived.push(entry);
@@ -641,7 +668,7 @@ if (isMainModule(import.meta.url)) {
     const { code } = main();
     process.exit(code ?? 0);
   } catch (err) {
-    process.stderr.write(`archive-closed-prds: unexpected error: ${err?.stack ?? err}\n`);
+    process.stderr.write(`archive-closed-prds: unexpected error: ${redactHomeDir(String(err?.stack ?? err))}\n`);
     process.exit(2);
   }
 }

package/scripts/autopilot.mjs

@@ -400,12 +400,19 @@ async function main() {
   });
 
   const sessionIds = state.sessions.join(', ') || '(none)';
+  // #1498: `tokens_unknown_sessions` (#1487 Pkt 4) reached state, return value
+  // and autopilot.jsonl, but no report showed it — so the token total read as
+  // the whole sum. Printed only when non-zero: then the total is a lower bound.
+  const unknownTokens = state.tokens_unknown_sessions > 0
+    ? ` tokens_unknown_sessions=${state.tokens_unknown_sessions} (the token total is a lower bound)`
+    : '';
   const summary =
     `${state.autopilot_run_id} ` +
     `kill_switch=${state.kill_switch ?? 'none'} ` +
     `iterations=${state.iterations_completed} ` +
     `sessions=[${sessionIds}] ` +
-    `duration=${state.duration_seconds}s`;
+    `duration=${state.duration_seconds}s ` +
+    `tokens=${state.total_tokens_used}${unknownTokens}`;
   process.stdout.write(summary + '\n');
 
   if (state.kill_switch === KILL_SWITCHES.FAILED_WAVE) {