session-orchestrator 3.23.0 → 3.24.0

package/scripts/lib/wave-transcript-tail.mjs

@@ -60,6 +60,7 @@ import { pathToFileURL } from 'node:url';
 import { emitEvent, sessionAttribution } from './events.mjs';
 import { tryAcquireFileLock, releaseFileLock } from './file-lock.mjs';
 import { readLock, isLockLive } from './session-lock.mjs';
+import { resolveSubagentSidecar } from '../../hooks/_lib/subagent-paths.mjs';
 
 const DEFAULT_INTERVAL_S = 2;
 const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
@@ -606,13 +607,32 @@ function mayCarrySignal(line) {
 }
 
 /**
- * @param {string} subagentsDir
+ * Read the agent TYPE from the sidecar `agent-<id>.meta.json` the harness
+ * writes next to the subagent transcript. `agentId` here comes from a
+ * `readdirSync()` filename match (tailLoop below), not from untrusted stdin —
+ * but it is validated through the SAME consolidated derivation (#1196) as the
+ * hook-side copies for consistency: an id readdirSync happened to list that
+ * fails `{1,64}`/charset/`'unknown'` short-circuits to the honest `'unknown'`
+ * return, same as any other lookup failure.
+ *
+ * `projectsDir`/`sessionId` reconstruct the PARENT transcript path
+ * (`<projectsDir>/<sessionId>.jsonl`) that `resolveSubagentSidecar()` expects —
+ * the real on-disk location of the coordinator's own transcript, sibling of
+ * the `subagents/` directory this function reads from.
+ *
+ * @param {string} projectsDir
+ * @param {string} sessionId
  * @param {string} agentId
  * @returns {string}
  */
-function readAgentType(subagentsDir, agentId) {
+function readAgentType(projectsDir, sessionId, agentId) {
+  const sidecar = resolveSubagentSidecar({
+    transcriptPath: join(projectsDir, `${sessionId}.jsonl`),
+    agentId,
+  });
+  if (sidecar === null) return 'unknown';
   try {
-    const meta = JSON.parse(readFileSync(join(subagentsDir, `agent-${agentId}.meta.json`), 'utf8'));
+    const meta = JSON.parse(readFileSync(sidecar.meta, 'utf8'));
     const t = meta?.agentType;
     return typeof t === 'string' && t ? t : 'unknown';
   } catch {
@@ -705,7 +725,7 @@ async function tailLoop({ intervalS }) {
       offsets.set(file, tick.offset);
       if (tick.lines.length === 0) continue;
       const agentId = file.slice('agent-'.length, -'.jsonl'.length);
-      if (!agentTypes.has(agentId)) agentTypes.set(agentId, readAgentType(subagentsDir, agentId));
+      if (!agentTypes.has(agentId)) agentTypes.set(agentId, readAgentType(projectsDir, sessionId, agentId));
       for (const line of tick.lines) {
         if (!mayCarrySignal(line)) continue;
         let rec;

package/scripts/materialize-wave-scope.mjs

@@ -13,12 +13,20 @@
  * After the aggregate is published, per-agent declarations left behind by an
  * earlier materialization of the SAME wave are reconciled away (#1103) — but
  * only against a proven session owner. See {@link reconcileOrphans}.
+ *
+ * PEER RECORDS (`peer-session-*`, #1195) get NO per-agent file: shape (a) is
+ * `$AGENT_FILESCOPE_JSON`, addressed by an agent id at dispatch time, and no
+ * agent is ever dispatched for a peer session — nothing reads it. They are
+ * still written into the aggregate, where `--assert-disjoint` and
+ * `hooks/post-bash-write-verify.mjs` do read them; `--union` excludes them so
+ * `allowedPaths` never grants a peer's territory to this wave's agents.
  */
 
 import { readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeJsonAtomicSync } from './lib/io.mjs';
+import { isPeerRecordId } from './lib/scope-gate.mjs';
 
 const HELP = `Usage: node scripts/materialize-wave-scope.mjs --state-dir <dir> --wave <positive-int> [--json]
 
@@ -50,6 +58,9 @@ Examples:
 
 Writes:
   <state-dir>/filescopes/wave-N/<id>.json       Bare string[] for each record
+                      EXCEPT a peer-session-* record (#1195), which is
+                      aggregate-only: no agent is dispatched for it, so nothing
+                      would read its per-agent file.
   <state-dir>/filescopes/wave-N.scopes.json     Aggregate [{id, files}, ...]
 
 Removes (only with a proven owner — see --session):
@@ -368,7 +379,12 @@ export function materializeWaveScope(records, {
 }) {
   const scopeDir = resolve(stateDir, 'filescopes', `wave-${wave}`);
   const aggregatePath = resolve(stateDir, 'filescopes', `wave-${wave}.scopes.json`);
-  const perAgentPaths = records.map(({ id }) => resolve(scopeDir, `${id}.json`));
+  // #1195 — peer records are aggregate-only (see the header note): no reader
+  // exists for a per-agent file that no dispatch will ever address. Excluding
+  // them from `keepIds` below also lets a stale `peer-session-*.json` written
+  // before this rule be reconciled away like any other orphan.
+  const agentRecords = records.filter((r) => !isPeerRecordId(r.id));
+  const perAgentPaths = agentRecords.map(({ id }) => resolve(scopeDir, `${id}.json`));
 
   try {
     unlinkSync(aggregatePath);
@@ -378,8 +394,8 @@ export function materializeWaveScope(records, {
     }
   }
 
-  for (let index = 0; index < records.length; index++) {
-    const result = writeJson(perAgentPaths[index], records[index].files, { tmpPrefix: '.materialize-wave-scope' });
+  for (let index = 0; index < agentRecords.length; index++) {
+    const result = writeJson(perAgentPaths[index], agentRecords[index].files, { tmpPrefix: '.materialize-wave-scope' });
     if (!result?.ok) {
       throw new WriteError(`cannot write per-agent declaration ${perAgentPaths[index]}: ${result?.error ?? 'unknown write failure'}`);
     }
@@ -396,7 +412,7 @@ export function materializeWaveScope(records, {
   // no aggregate at all — deleting coverage that nothing replaced.
   const { removed, retained } = reconcileOrphans({
     scopeDir,
-    keepIds: records.map(({ id }) => id),
+    keepIds: agentRecords.map(({ id }) => id),
     ownerIds: manifestSessionIds(stateDir, readFile),
     sessionId: session,
     readDir,

package/scripts/memory-propose.mjs

@@ -46,6 +46,8 @@ import { dirname, join, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { isWaveAgentContext, WAVE_AGENT_ENV_VAR, WAVE_AGENT_ENV_VALUE } from './lib/wave-context.mjs';
+import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
+import { readLockDetailed } from './lib/session-lock.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants & defaults
@@ -259,11 +261,14 @@ const confidence = confidenceVal;
 
 let frontmatter = {};
 let stateMdReadOk = false;
+/** Directory holding STATE.md — the same state-dir the wave manifest lives in (#1166). */
+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());
+  stateDir = dirname(stateMdPath);
 
   if (!existsSync(stateMdPath)) {
     if (!dryRun) {
@@ -352,17 +357,136 @@ if (!dryRun && (currentWaveRaw === undefined || currentWaveRaw === null || curre
 }
 
 // ---------------------------------------------------------------------------
-// Step 3 — Build wave ID from STATE.md current-wave (guaranteed present by 2c
-// when !dryRun; falls back to a 'W-dryrun' placeholder under --dry-run when
-// STATE.md was absent/unparseable/missing the field — #741.3)
+// Step 3 — Build the RUNNING wave ID (#1166)
 // ---------------------------------------------------------------------------
+//
+// #1166 — two writers, two semantics: `skills/wave-executor/wave-loop.md` § 3a
+// writes STATE.md `current-wave` = the JUST-COMPLETED wave, while the
+// coordinator's `<state-dir>/wave-scope.json` carries `wave` = the RUNNING
+// wave. Stamping proposals off `current-wave` verbatim filed every wave-N+1
+// proposal into the W<N> quota bucket. Priority: the manifest ONLY when it is
+// bound to THIS session, else `current-wave + 1`. An UNBOUND manifest is not
+// trusted (#1177 FX1) — since #1123 both writers stamp the binding, so a
+// binding-less manifest is a peer's or a stale artefact.
+//
+// The session binding compares `manifest.semantic_session` — the SEMANTIC label
+// — against the semantic id looked up in `session.lock`, and that lookup is only
+// honoured when this PROCESS's own raw session id equals the lock's raw
+// `session_id` (#1188). STATE.md's `session` field is NOT a witness here: it is
+// written by the lock owner, so under a peer's lock both "sides" name the peer.
+
+/** @returns {string|undefined} */
+function resolveRunningWaveId() {
+  if (stateDir !== null) {
+    try {
+      const manifestPath = join(stateDir, 'wave-scope.json');
+      if (existsSync(manifestPath)) {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        const boundSession = manifest?.semantic_session ?? manifest?.session;
+        const unbound =
+          boundSession === undefined || boundSession === null || boundSession === '';
+        // BOTH sides must be non-empty strings. `undefined === undefined` is
+        // true, so a STATE.md WITHOUT a `session` key previously "matched" any
+        // manifest whose `semantic_session` was also absent-but-present-in-the
+        // -comparison — adopting a foreign coordinator's wave number as its own.
+        const mineSide = manifest?.semantic_session;
+        // #1188 — STATE.md is a working-copy artefact of the LOCK OWNER, not a
+        // process-local witness: when a peer holds the lock the peer wrote BOTH
+        // STATE.md and the manifest, so the two "independent" sides agree about
+        // the PEER. Same class as #1177 FX1; same shape as attributionForRecord
+        // (scripts/lib/events.mjs): the lock is a raw->semantic LOOKUP,
+        // authorised by a process-local match on the RAW id. Measured
+        // 2026-09-02: a wave-agent process carries the COORDINATOR's raw uuid in
+        // CLAUDE_CODE_SESSION_ID and no semantic id at all, so comparing the
+        // process-local id against `semantic_session` directly never matches.
+        // CEILING (BV-004): a harness exporting no session id (Codex CLI,
+        // Cursor) resolves no process-local id -> binding unprovable ->
+        // current-wave + 1 fallback with a stderr line. REVISIT if that fallback
+        // rate is measured non-trivial in events.jsonl.
+        const lock = readLockDetailed({ repoRoot: process.cwd() });
+        const processLocal = readProcessLocalSessionIds();
+        const lockRaw =
+          lock.status === 'ok' ? String(lock.lock.session_id ?? '').trim() : '';
+        const authorised = lockRaw !== '' && processLocal.includes(lockRaw);
+        const oursSide = authorised ? (lock.lock.semantic_session_id ?? '') : '';
+        if (!authorised) {
+          // A SILENT non-match is the exact failure mode this fix exists to make
+          // visible: without this line, a proposal bucketed by the fallback is
+          // indistinguishable from one bucketed by a trusted manifest.
+          process.stderr.write(
+            `⚠ memory-propose: session binding unprovable (session.lock ${lock.status}` +
+              `${lockRaw ? `, raw ${lockRaw}` : ''}; process-local ids: ` +
+              `${processLocal.length > 0 ? processLocal.join(', ') : 'none'}) — ` +
+              'ignoring wave-scope.json, falling back to current-wave + 1\n',
+          );
+        }
+        const mine =
+          typeof mineSide === 'string' && mineSide.length > 0 &&
+          typeof oursSide === 'string' && oursSide.length > 0 &&
+          mineSide === oursSide;
+        // An UNBOUND manifest is NOT trusted (#1177 FX1). It used to be, as
+        // "legacy" — but since #1123 BOTH writers stamp the binding, so a
+        // manifest without one today is a PEER's or a stale artefact, and
+        // trusting it files this session's proposals into a foreign quota
+        // bucket. Unbound → say so once on stderr and fall back.
+        if (unbound) {
+          process.stderr.write(
+            'memory-propose: wave-scope.json unbound (no semantic_session) — ignored\n',
+          );
+        }
+        if (mine) {
+          const raw = manifest?.wave;
+          const num =
+            typeof raw === 'number'
+              ? raw
+              : typeof raw === 'string' && raw.trim() !== ''
+                ? Number(raw)
+                : NaN;
+          if (Number.isInteger(num)) return `W${num}`;
+        }
+      }
+    } catch (err) {
+      // Unreadable / malformed manifest → fall through to the +1 fallback, but
+      // SAY SO. A swallowed parse error makes a wrongly-bucketed proposal look
+      // like ordinary fallback behaviour; the operator then has no signal that
+      // the coordinator's own manifest is corrupt. Diagnostics on stderr keeps
+      // the stdout JSON contract intact (cli-design.md § JSON-First Output).
+      process.stderr.write(
+        `⚠ memory-propose: cannot read ${join(stateDir, 'wave-scope.json')} ` +
+          `(${err?.message ?? String(err)}) — falling back to current-wave + 1\n`,
+      );
+    }
+  }
+
+  if (currentWaveRaw === undefined || currentWaveRaw === null || currentWaveRaw === '') {
+    return undefined;
+  }
+  const completed = Number(currentWaveRaw);
+  if (!Number.isFinite(completed)) return undefined; // never 'WNaN'
+  // CEILING (BV-004): `+1` assumes waves run consecutively and that STATE.md is
+  // maintained — it is WRONG when a wave is skipped, when the plan is adapted
+  // mid-session, or under `persistence: false` where `current-wave` never
+  // advances. It is the fallback precisely because wave-scope.json is the only
+  // artefact that KNOWS the running wave.
+  // REVISIT when a wave-scope.json manifest is present in every dispatch (then
+  // delete the fallback and reject instead), or when a proposal is observed in
+  // the wrong quota bucket while the manifest was readable.
+  return `W${completed + 1}`;
+}
+
+const resolvedWaveId = resolveRunningWaveId();
 
-const frontmatterWaveId =
-  currentWaveRaw !== undefined && currentWaveRaw !== null && currentWaveRaw !== ''
-    ? `W${currentWaveRaw}`
-    : undefined;
+if (!dryRun && resolvedWaveId === undefined) {
+  exit(
+    {
+      status: STATUS.REJECTED_WRONG_CONTEXT,
+      detail: `Cannot resolve the running wave: no usable wave-scope.json and STATE.md 'current-wave' is not numeric (got '${currentWaveRaw}')`,
+    },
+    3,
+  );
+}
 
-const waveId = dryRun ? (frontmatterWaveId ?? 'W-dryrun') : frontmatterWaveId;
+const waveId = dryRun ? (resolvedWaveId ?? 'W-dryrun') : resolvedWaveId;
 
 // ---------------------------------------------------------------------------
 // Step 4 — Read Session Config (quota + floor)

package/scripts/promote-vault-strict.mjs

@@ -23,6 +23,7 @@ import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
+import { expandTilde } from './lib/common.mjs';
 
 const COMMIT_MSG = 'chore(orchestrator): Promote vault-integration to strict mode — refs #305';
 
@@ -53,18 +54,6 @@ const noBaseline = args.includes('--no-baseline');
 const repoIdx = args.indexOf('--repo');
 const singleRepo = repoIdx !== -1 && args[repoIdx + 1] ? args[repoIdx + 1] : null;
 
-// ---------------------------------------------------------------------------
-// Path resolution
-// ---------------------------------------------------------------------------
-
-/** Expand leading ~ to the user's home directory. */
-function expandHome(p) {
-  if (p.startsWith('~/')) {
-    return join(homedir(), p.slice(2));
-  }
-  return p;
-}
-
 // ---------------------------------------------------------------------------
 // Vault-integration mode replacement
 // ---------------------------------------------------------------------------
@@ -424,7 +413,7 @@ async function main() {
 
   if (singleRepo) {
     // Single-repo mode
-    const absRepo = expandHome(singleRepo);
+    const absRepo = expandTilde(singleRepo);
     const singleRoot = getConfinementRoot();
     const singleGuard = validatePathInsideProject(absRepo, singleRoot);
     if (!singleGuard.ok) {
@@ -449,7 +438,7 @@ async function main() {
 
     const batchRoot = getConfinementRoot();
     for (const rawPath of eligibleRepos) {
-      const absRepo = expandHome(rawPath);
+      const absRepo = expandTilde(rawPath);
       const guard = validatePathInsideProject(absRepo, batchRoot);
       if (!guard.ok) {
         process.stderr.write(
@@ -469,7 +458,7 @@ async function main() {
         (p) => p === 'projects-baseline' || p.endsWith('/projects-baseline')
       );
       if (baselineEntry) {
-        const baselineRepoDir = expandHome(
+        const baselineRepoDir = expandTilde(
           baselineEntry.startsWith('~') || baselineEntry.startsWith('/')
             ? baselineEntry
             : `~/Projects/${baselineEntry}`

package/scripts/site-numbers.mjs

@@ -79,6 +79,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
+import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 /** Machine-readable schema tag for the --json envelope. */
 export const SCHEMA = 'site-numbers/1';
@@ -401,10 +402,31 @@ export const METRIC_DEFS = Object.freeze([
     // Gitignored ledger (`.gitignore`: local-only observability data) — absent
     // in every fresh clone, CI checkout and tarball build.
     snapshotFallback: true,
-    source: 'grep -c . .orchestrator/metrics/sessions.jsonl',
+    // #1186: `grep -c` over-counts — sessions.jsonl is append-only, so the same
+    // physical session can carry more than one line (crash-recovery re-appends,
+    // #1068 stub/supersede pairs). readCanonicalSessions collapses those to one
+    // record per session_id before the count; see scripts/lib/sessions-canonical.mjs
+    // for the three collapse rules. `learnings` below stays a raw line count —
+    // that ledger has no session_id-shaped identity to dedupe on.
+    // Measured on THIS repo's own ledger @ 2ccea0f2: raw line count 289 vs
+    // canonical (deduped) count 278 — an over-count of 11 records, which is the
+    // bug's magnitude this migration removes.
+    source: 'grep -c . .orchestrator/metrics/sessions.jsonl   (then deduped per session_id — see readCanonicalSessions, #1186)',
     compute: (root) => {
-      const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', 'sessions.jsonl'));
-      return r === null ? null : fmtCount(r.entries);
+      const file = join(root, '.orchestrator', 'metrics', 'sessions.jsonl');
+      // Same absent/non-file guard as countJsonlEntries, kept explicit here
+      // because readCanonicalSessions returns [] (not null) on a missing ledger
+      // — collapsing that into fmtCount(0) would silently defeat the
+      // snapshotFallback precedence above (a fresh clone would report "0
+      // sessions" instead of falling back to the tracked snapshot).
+      if (!existsSync(file) || !statSync(file).isFile()) return null;
+      // Same reader every other #1186 consumer uses (autopilot.mjs,
+      // build-live-signals.mjs, telemetry/sync.mjs) — a record with no
+      // `session_id` is dropped rather than counted, because it cannot be
+      // identified for dedup. Measured @ 2ccea0f2 on this repo's own ledger:
+      // 0 such rows (raw 289 lines == 289 identified), so the drop is inert
+      // here; it only matters for a future malformed/legacy row.
+      return fmtCount(readCanonicalSessions({ filePath: file }).length);
     },
   },
   {
@@ -623,7 +645,17 @@ export function collect(root) {
   ]) {
     const r = countJsonlEntries(join(root, '.orchestrator', 'metrics', file));
     if (r && r.malformed > 0) {
-      warnings.push(`${file}: ${r.malformed} non-empty line(s) are not valid JSON — the ${name} count includes them`);
+      // #1186: the two ledgers now disagree on what a malformed line DOES to
+      // the published count. `learnings` is still the raw countJsonlEntries
+      // total, which counts a malformed line as an entry regardless of its
+      // content. `sessions` is readCanonicalSessions, whose parse loop skips a
+      // line it cannot JSON.parse — so a malformed session line is silently
+      // ABSENT from the count rather than included in it.
+      const consequence =
+        name === 'sessions'
+          ? `they are DROPPED from the sessions count (readCanonicalSessions skips unparseable lines)`
+          : `the ${name} count includes them`;
+      warnings.push(`${file}: ${r.malformed} non-empty line(s) are not valid JSON — ${consequence}`);
     }
   }
 

package/scripts/validate-plugin.mjs

@@ -318,6 +318,16 @@ runCheck('check-vcs-repo-flag.mjs');
 process.stdout.write('\n');
 runCheck('check-doc-cli-commands.mjs');
 
+// BLOCKING (#1176): a `scripts/**.mjs` path cited in skills/, commands/ or
+// agents/ prose that does not exist. Unlike the WARN-only check above, the
+// oracle is this repository's own filesystem — no version skew of a foreign
+// binary can red an unrelated commit, so a finding is always a real defect.
+// A deliberately absent path is annotated in place:
+// `<!-- path-check: planned #<iid> | historical | example -->`, honoured on the
+// citation's own line or the line immediately above.
+process.stdout.write('\n');
+if (runCheck('check-skill-script-paths.mjs') !== 0) checkFailed = 1;
+
 // WARN-only: a state-mutating `git` call in tests/ that names no target resolves
 // its destination from the ambient cwd (or an inherited GIT_DIR) — the 2026-08-19
 // incident, where fixture commits, a fixture remote and a fixture identity landed
@@ -337,6 +347,22 @@ runCheck('check-doc-cli-commands.mjs');
 process.stdout.write('\n');
 runCheck('check-test-git-config-target.mjs');
 
+// 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
+// unguarded sites are baselined inside the checker itself and report WARN,
+// never FAIL, so this can be blocking-by-default without going red on
+// arrival; only a NEW unguarded site fails the build.
+process.stdout.write('\n');
+if (runCheck('check-hooks-emit-event-guard.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
+// deliberately CLI-only. A checker nobody runs is built work with no effect.
+process.stdout.write('\n');
+if (runCheck('check-validator-registration.mjs') !== 0) checkFailed = 1;
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------

package/scripts/vault-consolidate.mjs

@@ -84,10 +84,9 @@
 
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 import { pathToFileURL } from 'node:url';
 
-import { die, utcTimestamp } from './lib/common.mjs';
+import { die, utcTimestamp, expandTilde } from './lib/common.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import {
   SCRIPT_NAME,
@@ -150,13 +149,6 @@ Exit codes:
   process.stderr.write(usage);
 }
 
-function expandHome(p) {
-  if (typeof p !== 'string' || p.length === 0) return p;
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
 async function isDir(p) {
   try {
     const st = await fs.stat(p);
@@ -222,8 +214,8 @@ async function main() {
   const isDryRun = !isApply;
   const isJson = parsed.values.json === true;
 
-  const sourceRoot = path.resolve(expandHome(parsed.values.source ?? DEFAULT_SOURCE));
-  const canonicalRoot = path.resolve(expandHome(parsed.values.canonical ?? DEFAULT_CANONICAL));
+  const sourceRoot = path.resolve(expandTilde(parsed.values.source ?? DEFAULT_SOURCE));
+  const canonicalRoot = path.resolve(expandTilde(parsed.values.canonical ?? DEFAULT_CANONICAL));
 
   // Parse --resolve flags into a Map<relPath, "src"|"dst"|"skip">
   const resolutions = new Map();

package/scripts/vault-integration-watcher.mjs

@@ -31,11 +31,10 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
 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';
+import { expandTilde } from './lib/common.mjs';
 
 // ── Argument parsing ──────────────────────────────────────────────────────────
 
@@ -332,9 +331,8 @@ async function main() {
   // Load the config-driven repo list before doing any glab work
   const watcherRoot = getConfinementRoot();
   // Home-expand each entry before confinement, matching sibling scripts (W4-Q2 LOW).
-  const expandHome = (p) => (p.startsWith('~/') ? join(homedir(), p.slice(2)) : p);
   const flipRepos = (await getCrossRepoProjects()).filter((r) => {
-    const guard = validatePathInsideProject(expandHome(r), watcherRoot);
+    const guard = validatePathInsideProject(expandTilde(r), watcherRoot);
     if (!guard.ok) {
       process.stderr.write(
         `vault-integration-watcher: WARN rejecting confined-path violation for ${JSON.stringify(r)} (reason: ${guard.reason})\n`