session-orchestrator 3.20.0 → 3.22.0

package/scripts/validate-plugin.mjs

@@ -204,6 +204,16 @@ if (runCheck('check-agents.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-commands.mjs') !== 0) checkFailed = 1;
 
+// FAIL-capable from day one: every rule this check enforces (frontmatter present,
+// parses as YAML, kebab-case name matching the directory, non-empty description)
+// was measured at 0 violations across all 46 SKILL.md files at the commit that
+// added it — so unlike the WARN-only censuses further down, it cannot be red on
+// arrival. It sits next to check-commands.mjs because it shares that check's
+// posture: a real js-yaml parse, not the line-regex approach of check-agents.mjs
+// that let 12 unparseable SKILL.md frontmatter blocks go unnoticed.
+process.stdout.write('\n');
+if (runCheck('check-skills.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runDriftCheck() !== 0) checkFailed = 1;
 
@@ -249,12 +259,23 @@ if (runCheck('check-owner-leakage.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-rules.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runCheck('check-auq-clarity.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-unicode-safety.mjs') !== 0) checkFailed = 1;
 
 process.stdout.write('\n');
 if (runCheck('check-dead-bridge.mjs') !== 0) checkFailed = 1;
 
+// FAIL-capable, unlike the WARN-only censuses below: R2+R4 were measured at
+// 1 hit / 1 TP / 0 FP each against the full test corpus, so this check cannot be
+// red on arrival for anything but a real instance of the class. The alternatives
+// (R1 at 67 FP, R3 at 47 FP) are exactly the shape that gets demoted to WARN and
+// then ignored — see the rule table in the check's header.
+process.stdout.write('\n');
+if (runCheck('check-untracked-test-deps.mjs') !== 0) checkFailed = 1;
+
 // WARN-only (v1): the unwired-config-key census reports but never fails the
 // build — see the rationale in the check's header (a blocking gate on today's
 // inventory would be red from day one and get disabled). Exit code is
@@ -270,6 +291,49 @@ runCheck('check-unwired-features.mjs');
 process.stdout.write('\n');
 runCheck('check-learning-provenance.mjs');
 
+// WARN-only (#971), same rationale as the two censuses above: a `gh`/`glab` call
+// without `--repo`/`-R` resolves its target project from the ambient cwd remote —
+// silently the wrong project in a sibling worktree, an /autopilot child, or a repo
+// whose origin is a fork — and a gate that blocks on a backlog no single pass can
+// drain gets switched off rather than obeyed. What WARN buys is that each newly
+// added bare call site shows up in every validator run while the sweep drains the
+// rest. No headcount is quoted here on purpose: the live number moves with every
+// commit, and only the check's own `--json` summary can state it as of a SHA. The
+// exit code is deliberately ignored; a tool error still surfaces because that path
+// prints FAIL: lines, which runCheck tallies into totalFail.
+process.stdout.write('\n');
+runCheck('check-vcs-repo-flag.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
+// `--help` COMMANDS section, never an exit code (`glab repo <anything> --help`
+// exits 0). WARN rather than FAIL because that oracle is the LOCALLY installed
+// binary: a version skew must not red an unrelated commit, and a missing binary
+// SKIPs. The exit code is deliberately ignored; a tool error still surfaces
+// because that path prints FAIL: lines, which runCheck tallies into totalFail.
+process.stdout.write('\n');
+runCheck('check-doc-cli-commands.mjs');
+
+// 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
+// in the REAL .git and two commits reached both remotes with the wrong author.
+// WARN rather than FAIL is a MEASURED posture, not caution: the v1 rule reported
+// 11 findings against tests/ and all 11 were false positives (`git init <dir>`,
+// whose positional IS the target). After that refinement the live corpus reports
+// 0 findings — i.e. zero measured true positives to weigh against a textual
+// detector's residual false-positive surface (the variable argv arrays it cannot
+// judge; the live count is in its own PASS line, never restated here).
+// check-untracked-test-deps.mjs above earned FAIL-capability on a
+// measured 1 TP / 0 FP; this check has not, and a single FAIL: line here reds the
+// whole validator. Ratchet to FAIL once a live true positive has been observed
+// and the GIT_DIR-inheritance gap (reported as `gitDirInheritable`) is closed
+// centrally. The exit code is deliberately ignored; a tool error still surfaces
+// because that path prints FAIL: lines, which runCheck tallies into totalFail.
+process.stdout.write('\n');
+runCheck('check-test-git-config-target.mjs');
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------

package/scripts/validate-wave-scope.mjs

@@ -9,6 +9,8 @@
  *   node scripts/validate-wave-scope.mjs <path-to-wave-scope.json>
  *   cat wave-scope.json | node scripts/validate-wave-scope.mjs
  *   node scripts/validate-wave-scope.mjs --assert-subset <agent-filescope.json> < wave-scope.json
+ *   node scripts/validate-wave-scope.mjs --assert-disjoint <agent-scopes.json> < wave-scope.json
+ *   node scripts/validate-wave-scope.mjs --union <agent-scopes.json> < wave-scope.json
  *
  * Flags:
  *   --assert-subset <path>  After schema validation passes, read the agent
@@ -26,21 +28,68 @@
  *                           the caller may pass the flag unconditionally on
  *                           every pre-dispatch check. A skip is announced on
  *                           stderr as a WARN.
+ *   --assert-disjoint <p>   #1020. Read the wave's per-agent scope SIDECAR and
+ *                           assert no file is claimed by two agents of the same
+ *                           wave. Fails (exit 1) with one message per collision.
+ *                           `knownFiles` for the glob∩glob stage comes from
+ *                           `git ls-files` — spawned HERE, in the CLI layer,
+ *                           because scripts/lib/scope-gate.mjs is hook-safe and
+ *                           must not spawn a process (see its module header).
+ *   --union <path>          #1020. QUERY MODE. Read the same sidecar, compute
+ *                           `expandTestSiblings(unionFileScopes(scopes), {role})`
+ *                           using the MANIFEST'S OWN `role`, and print the
+ *                           resulting allowedPaths array as JSON on stdout.
+ *                           Mechanical replacement for the "Collect all file
+ *                           paths … Deduplicate entries" prose in
+ *                           skills/wave-executor/wave-loop.md § Scope Manifest #3.
+ *
+ * ## SIDECAR FORMAT (both #1020 flags) — an ARRAY, never an object map
+ *   [{ "id": "W2-C1", "files": ["scripts/a.mjs"] }, { "id": "W2-C4", "files": [...] }]
+ * An object keyed by agent id would swallow a DUPLICATE agent id silently, and a
+ * duplicated id is a real copy-paste failure mode (it hides one agent's scope
+ * from every per-agent check). The array form keeps both records, and
+ * `findScopeCollisions` reports the duplicate as its own finding.
+ *
+ * ## STDOUT CONTRACT (why --union suppresses the manifest echo)
+ * Without `--union` this script writes EXACTLY ONE thing to stdout: the input
+ * manifest, echoed back verbatim. Callers rely on that — `JSON.parse(stdout)`.
+ * `--union` is the first mode that has something else to say, so it is a pure
+ * QUERY MODE: it REPLACES the echo rather than adding to it, and stdout carries
+ * only the computed allowedPaths array. Mixing both on stdout would break every
+ * `JSON.parse(stdout)` caller; writing the union to a second sink would need a
+ * file argument the caller must then read back. One JSON document per run, and
+ * the flag decides which one.
  *
  * Exit codes:
- *   0 — valid (validated JSON echoed to stdout)
- *   1 — invalid input / validation failure (error messages written to stderr)
- *   2 — I/O error (file not found, unreadable stdin, unreadable --assert-subset file)
+ *   0 — valid (validated JSON echoed to stdout; with --union: the union array)
+ *   1 — invalid input / validation failure (error messages written to stderr).
+ *       A scope COLLISION is a validation finding, exactly like the #796 subset
+ *       and #970 test-sibling violations — the collision-vs-subset distinction
+ *       lives in the MESSAGE, not in a new exit code.
+ *   2 — I/O error (file not found, unreadable stdin, unreadable sidecar file)
  */
 
 import path from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { warn } from './lib/common.mjs';
 import {
   assertFileScopeSubset,
   assertTestSiblingCoverage,
   testSiblingExpansionApplies,
   TEST_SIBLING_EXPANSION_ROLES,
+  findScopeCollisions,
+  unionFileScopes,
+  // #1057 — the read-only-role predicate + THE list. Imported rather than
+  // re-listed so the validator and hooks/enforce-scope.mjs cannot disagree about
+  // which roles are allowed to grant zero paths.
+  isReadOnlyWaveRole,
+  READ_ONLY_WAVE_ROLES,
+  // Aliased: `expandTestSiblings` is ALSO the name of the pre-existing
+  // boolean parameter threaded through validate()/assertSubsetOrDie for the
+  // #970 flag. Aliasing the import avoids shadowing that parameter rather than
+  // renaming it — the #970 call path stays byte-identical.
+  expandTestSiblings as expandScopeTestSiblings,
 } from './lib/scope-gate.mjs';
 
 /**
@@ -54,21 +103,58 @@ function die(msg, code = 1) {
   process.exit(code);
 }
 
+/**
+ * Read the value operand of a value-taking flag, REFUSING one that is itself a
+ * flag. Used by the #1020 flags only.
+ *
+ * `--assert-subset` (#796) consumes `argv[i + 1]` BLIND, so
+ * `--assert-subset --assert-disjoint x.json` reads `--assert-disjoint` as its
+ * path value. That behaviour is deliberately left untouched — its no-value
+ * message is pinned byte-for-byte by
+ * tests/scripts/validate-wave-scope.test.mjs — but the flags added here do not
+ * inherit it: a swallowed flag is silent (the mode never runs, and the caller
+ * believes it did), whereas this refusal is loud and one line long.
+ *
+ * An EMPTY value is the same failure class and is refused for the same reason.
+ * `--assert-disjoint ""` is what a failed `$(...)` capture of the materializer's
+ * stdout produces; since the mode is gated on a truthy path, the empty string
+ * silently skipped the collision check and still exited 0 (#1083).
+ *
+ * @param {string[]} argv
+ * @param {number} i - index of the FLAG token
+ * @param {string} flag - the flag name, for the error message
+ * @returns {string}
+ */
+function flagValue(argv, i, flag) {
+  const value = argv[i + 1];
+  if (value === undefined || value === '' || value.startsWith('--')) {
+    die(`${flag} requires a file-path argument`, 1);
+  }
+  return value;
+}
+
 /**
  * Parse CLI flags out of argv, leaving positional args behind.
  *
- * Recognised: `--assert-subset <path>` (#796) and `--expand-test-siblings`
- * (#970). Everything else is treated as a positional argument (the
- * wave-scope.json file path), preserving legacy behaviour where argv[2] is the
- * input file.
+ * Recognised: `--assert-subset <path>` (#796), `--expand-test-siblings` (#970),
+ * `--assert-disjoint <path>` and `--union <path>` (#1020). Everything else is
+ * treated as a positional argument (the wave-scope.json file path), preserving
+ * legacy behaviour where argv[2] is the input file.
+ *
+ * The #1020 branches sit BEFORE the positional fallback, as their own `else if`
+ * arms: routed through the fallback instead, `--assert-disjoint` would be read
+ * as a wave-scope.json path and the mode would never run.
  *
  * @param {string[]} argv - full process.argv
- * @returns {{ assertSubset: string|null, expandTestSiblings: boolean, positionals: string[] }}
+ * @returns {{ assertSubset: string|null, expandTestSiblings: boolean,
+ *             assertDisjoint: string|null, union: string|null, positionals: string[] }}
  */
 function parseArgs(argv) {
   const positionals = [];
   let assertSubset = null;
   let expandTestSiblings = false;
+  let assertDisjoint = null;
+  let union = null;
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--expand-test-siblings') {
@@ -79,11 +165,17 @@ function parseArgs(argv) {
         die('--assert-subset requires a file-path argument', 1);
       }
       i++; // consume the value
+    } else if (a === '--assert-disjoint') {
+      assertDisjoint = flagValue(argv, i, '--assert-disjoint');
+      i++; // consume the value
+    } else if (a === '--union') {
+      union = flagValue(argv, i, '--union');
+      i++; // consume the value
     } else {
       positionals.push(a);
     }
   }
-  return { assertSubset, expandTestSiblings, positionals };
+  return { assertSubset, expandTestSiblings, assertDisjoint, union, positionals };
 }
 
 /**
@@ -259,6 +351,27 @@ function validateAllowedPaths(obj, errors, warnings) {
     errors.push(`allowedPaths must be an array, got type: ${ap === null ? 'null' : typeof ap}`);
     return;
   }
+  // #1057 — an empty union under a WRITABLE role. WARN, never error, and the
+  // distinction is measured rather than stylistic: `skills/wave-executor/wave-loop.md`
+  // § Scope Manifest deliberately feeds a skeleton with `"allowedPaths": []`
+  // through THIS validator in `--assert-disjoint` and `--union` mode, BEFORE the
+  // union exists to be written. An error would break the documented procedure
+  // that produces the very field it complains about.
+  //
+  // Named ceiling (BV-004): the warning therefore also fires on that legitimate
+  // skeleton run — one stderr line on a happy path, accepted because the
+  // alternative is a mode-conditional warning, i.e. a second place that has to
+  // enumerate the modes correctly. Revisit if a third empty-skeleton mode lands.
+  if (ap.length === 0 && typeof obj.role === 'string' && obj.role.trim().length > 0
+      && !isReadOnlyWaveRole(obj.role)) {
+    warnings.push(
+      `allowedPaths is empty for role "${obj.role}" — every write in this wave will be DENIED by ` +
+      `hooks/enforce-scope.mjs. Empty is intentional only for a read-only role ` +
+      `(${READ_ONLY_WAVE_ROLES.join(', ')}); for a writable role it usually means the coordinator's ` +
+      `--union step did not complete. Expected while validating the pre-union skeleton; otherwise ` +
+      `re-run --union and rewrite the manifest.`,
+    );
+  }
   for (const entry of ap) {
     if (typeof entry !== 'string' || entry.length === 0) {
       errors.push('allowedPaths contains empty string');
@@ -414,13 +527,157 @@ function assertSubsetOrDie(obj, fileScopePath, expandTestSiblings = false) {
   }
 }
 
+/**
+ * Read + shape-check the per-agent scope SIDECAR shared by `--assert-disjoint`
+ * and `--union` (#1020). Exits on any defect; returns the records on success.
+ *
+ * Exit codes mirror {@link assertSubsetOrDie} exactly: 2 for I/O (missing, not a
+ * regular file, unreadable), 1 for every content defect.
+ *
+ * ## Why the shape check is STRICTER than the library's tolerance
+ * `findScopeCollisions` / `unionFileScopes` are fail-closed and never throw:
+ * they SKIP a member that is not an object, and treat a missing `files` as `[]`.
+ * That is right for a hook-hot-path primitive and wrong for a CLI. A sidecar
+ * that spells the key `file:` instead of `files:` would then contribute nothing
+ * and both modes would report success on a scope that silently vanished — a
+ * path the operator NAMED and the tool did not honour. The absent-input guard
+ * belongs in the CLI layer (recorded learning, conf 0.80: a tolerant reader
+ * cannot carry a CLI's absent-input guard), so `files` is REQUIRED here.
+ *
+ * `id` is deliberately NOT required: scope-gate's `normalizeAgentScopes` runs a
+ * record with no usable id as `<unnamed#i>` rather than dropping it, precisely
+ * because an unreviewed scope is the one that collides. Requiring it here would
+ * reject exactly the input that contract was written to keep.
+ *
+ * @param {string} sidecarPath
+ * @param {string} flag - the flag name, for error messages
+ * @returns {Array<{id?: string, files: string[]}>}
+ */
+function readAgentScopesOrDie(sidecarPath, flag) {
+  if (!existsSync(sidecarPath) || !statSync(sidecarPath).isFile()) {
+    die(`Cannot read ${flag} file: ${sidecarPath}`, 2);
+  }
+  let raw;
+  try {
+    raw = readFileSync(sidecarPath, 'utf8');
+  } catch (err) {
+    die(`Cannot read ${flag} file ${sidecarPath}: ${err.message}`, 2);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    die(`${flag} file is not valid JSON: ${sidecarPath}`, 1);
+  }
+  if (!Array.isArray(parsed)) {
+    const t = parsed === null ? 'null' : typeof parsed;
+    die(
+      `${flag} file must be a JSON array of {id, files} records, got type: ${t} — an object map would silently swallow a duplicate agent id`,
+      1,
+    );
+  }
+  for (let i = 0; i < parsed.length; i++) {
+    const rec = parsed[i];
+    if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) {
+      die(`${flag} file entry #${i} must be an object with a "files" array`, 1);
+    }
+    if (!Array.isArray(rec.files) || !rec.files.every((f) => typeof f === 'string')) {
+      die(`${flag} file entry #${i} ("${rec.id ?? '<unnamed>'}") must have a "files" string array`, 1);
+    }
+  }
+  return parsed;
+}
+
+/**
+ * The repo's tracked files, for {@link findScopeCollisions}' glob∩glob witness
+ * stage. Spawned HERE and injected as a parameter because
+ * `scripts/lib/scope-gate.mjs` is hook-safe (pure, sync, no I/O, no spawn) and
+ * `hooks/enforce-scope.mjs` reaches it on a hot path.
+ *
+ * An unavailable git (not a repo, git missing, huge output) is NOT an error:
+ * the library documents `knownFiles` as optional — stage 3a simply has fewer
+ * witnesses and the prefix fallback of stage 3b carries the load. Silent by
+ * design: a WARN here would print on the success path of a mode whose contract
+ * is "quiet when clean".
+ *
+ * @returns {string[]}
+ */
+function knownRepoFiles() {
+  const opts = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 };
+  try {
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], opts).trim();
+    if (!root) return [];
+    // -z: NUL-separated. Without it git QUOTES paths containing non-ASCII or
+    // special characters, and a quoted path would never match a scope entry.
+    return execFileSync('git', ['ls-files', '-z'], { ...opts, cwd: root })
+      .split('\0')
+      .filter((f) => f.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Assert that no file is claimed by two agents of the SAME wave (#1020).
+ * Exits 1 with one message per collision (plus one per duplicate agent id);
+ * returns silently when the wave is clean.
+ *
+ * @param {string} sidecarPath
+ */
+function assertDisjointOrDie(sidecarPath) {
+  const agentScopes = readAgentScopesOrDie(sidecarPath, '--assert-disjoint');
+  const { ok, collisions, duplicateIds } = findScopeCollisions(agentScopes, {
+    knownFiles: knownRepoFiles(),
+  });
+  if (ok) return;
+
+  // Duplicate ids FIRST: they are a malformed plan, and a reader who fixes them
+  // may well change which collisions remain.
+  for (const id of duplicateIds) {
+    process.stderr.write(
+      `ERROR: duplicate agent id in ${sidecarPath}: "${id}" — ids must be unique per wave; a copy-paste duplicate hides one agent's scope from every per-agent check\n`,
+    );
+  }
+  for (const c of collisions) {
+    process.stderr.write(
+      `ERROR: wave scope collision (${c.kind}): agents "${c.a}" and "${c.b}" both claim [${c.evidence.join(', ')}]\n`,
+    );
+  }
+  process.stderr.write(
+    `ERROR: ${collisions.length} scope collision(s), ${duplicateIds.length} duplicate id(s) — every file must belong to exactly ONE agent per wave (#1020; .claude/rules/parallel-sessions.md § Decision Tree)\n`,
+  );
+  process.exit(1);
+}
+
+/**
+ * QUERY MODE (#1020): print `expandTestSiblings(unionFileScopes(scopes), {role})`
+ * as JSON on stdout, using the MANIFEST'S own role. Replaces the manifest echo —
+ * see the STDOUT CONTRACT note in the file header.
+ *
+ * @param {Record<string, unknown>} obj - the already schema-validated wave-scope object
+ * @param {string} sidecarPath
+ */
+function emitUnion(obj, sidecarPath) {
+  const agentScopes = readAgentScopesOrDie(sidecarPath, '--union');
+  const allowedPaths = expandScopeTestSiblings(unionFileScopes(agentScopes), { role: obj.role });
+  process.stdout.write(`${JSON.stringify(allowedPaths, null, 2)}\n`);
+}
+
 /**
  * Main validation entry point. Reads input, validates, exits with appropriate code.
  * @param {string} input - raw JSON string
  * @param {string|null} [assertSubsetPath] - optional agent fileScope file for the #796 subset assertion
  * @param {boolean} [expandTestSiblings] - opt-in #970 test-sibling coverage assertion
+ * @param {string|null} [assertDisjointPath] - optional per-agent scope sidecar for the #1020 collision check
+ * @param {string|null} [unionPath] - optional per-agent scope sidecar for the #1020 union query mode
  */
-function validate(input, assertSubsetPath = null, expandTestSiblings = false) {
+function validate(
+  input,
+  assertSubsetPath = null,
+  expandTestSiblings = false,
+  assertDisjointPath = null,
+  unionPath = null,
+) {
   const obj = parseJson(input);
   const errors = [];
   const warnings = [];
@@ -446,9 +703,26 @@ function validate(input, assertSubsetPath = null, expandTestSiblings = false) {
     assertSubsetOrDie(obj, assertSubsetPath, expandTestSiblings);
   }
 
+  // #1020 — collision check runs AFTER the #796/#970 assertions, for the same
+  // reason #970 runs after #796 (see assertSubsetOrDie): a manifest that
+  // violates BOTH the subset relation and disjointness must keep the older,
+  // byte-pinned subset message. Only ever ADDS a failure mode.
+  if (assertDisjointPath) {
+    assertDisjointOrDie(assertDisjointPath);
+  }
+
+  // #1020 QUERY MODE — replaces the echo below; see the STDOUT CONTRACT note in
+  // the file header. Last, so every assertion above still gates it.
+  if (unionPath) {
+    emitUnion(obj, unionPath);
+    return;
+  }
+
   // Echo validated JSON to stdout (trailing newline normalised)
   process.stdout.write(input.endsWith('\n') ? input : input + '\n');
 }
 
-const { assertSubset, expandTestSiblings, positionals } = parseArgs(process.argv);
-validate(readInput(positionals[0]), assertSubset, expandTestSiblings);
+const { assertSubset, expandTestSiblings, assertDisjoint, union, positionals } = parseArgs(
+  process.argv,
+);
+validate(readInput(positionals[0]), assertSubset, expandTestSiblings, assertDisjoint, union);

package/scripts/vault-backfill.mjs

@@ -25,12 +25,12 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
 import { createInterface } from 'node:readline';
 
 import {
   assertGlabExists, setVerbose as setGlabVerbose,
-  listGroupRepos, checkVaultYaml, fetchRepoOwner,
+  listGroupRepos, checkVaultYaml,
 } from './lib/vault-backfill/glab.mjs';
 
 import {
@@ -155,11 +155,25 @@ function createVaultFolderStub(vaultDir, slug) {
 
 // ── Process one repo ──────────────────────────────────────────────────────────
 
+/** Derive the complete parent namespace from a canonical GitLab project path. */
+function parentNamespace(repoPath) {
+  if (typeof repoPath !== 'string') return 'unknown';
+
+  const segments = repoPath.split('/');
+  if (
+    segments.length < 2 ||
+    segments.some((segment) => !segment || segment === '.' || segment === '..')
+  ) {
+    return 'unknown';
+  }
+
+  return segments.slice(0, -1).join('/');
+}
+
 function processRepo(entry, vaultDir, templateContent) {
   const { path: repoPath, slug, tier, visibility, group, id } = entry;
   const humanName = slugToHumanName(slug);
-
-  const owner = applyWrites ? fetchRepoOwner(id) : 'unknown';
+  const owner = parentNamespace(repoPath);
 
   let renderedContent;
   try {
@@ -184,7 +198,20 @@ function processRepo(entry, vaultDir, templateContent) {
   }
 
   // Apply: write to staging directory at <out-dir>/<group>/<repo>/.vault.yaml
-  const writePath = join(outDir, repoPath, '.vault.yaml');
+  const writePath = resolve(outDir, repoPath, '.vault.yaml');
+  const writePathRelativeToOutDir = relative(outDir, writePath);
+  if (
+    writePathRelativeToOutDir === '..' ||
+    writePathRelativeToOutDir.startsWith(`..${sep}`) ||
+    isAbsolute(writePathRelativeToOutDir)
+  ) {
+    const error = 'refusing to write outside staging directory';
+    emitAction('write-failed', '', { error });
+    process.stderr.write(`[vault-backfill] ERROR: ${error}\n`);
+    hadWriteError = true;
+    return;
+  }
+
   try {
     mkdirSync(dirname(writePath), { recursive: true });
     writeFileSync(writePath, renderedContent, 'utf8');

package/scripts/vault-mirror.mjs

@@ -55,7 +55,8 @@ import { createInterface } from 'node:readline';
 import { createReadStream } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 
-import { processLearning, processSession } from './lib/vault-mirror/process.mjs';
+import { processLearning, processSession, getMaskerStats } from './lib/vault-mirror/process.mjs';
+import { emitEvent } from './lib/events.mjs';
 import { autoCommitVaultMirror } from './lib/vault-mirror/auto-commit.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { resolveRepoNamespace } from './lib/vault-mirror/namespace.mjs';
@@ -403,6 +404,30 @@ async function main() {
     }
   }
 
+  // ── Masking telemetry (#1025) ───────────────────────────────────────────────
+  //
+  // Emitted UNCONDITIONALLY, exactly once per channel run, and HERE — at the end
+  // of the run rather than at the lazy build site inside process.mjs. The build
+  // site is only reached once a record is actually processed, so a run over an
+  // empty/fully-skipped source would emit nothing and "the masker never ran" would
+  // be indistinguishable from "this channel has no masker wired". Placed BEFORE
+  // the --strict-schema abort so a failing run still reports its masking posture.
+  //
+  // Counts only — never a needle, never a prefix of one, never masked text.
+  // Best-effort: a telemetry write must never be the reason a mirror run fails.
+  try {
+    const maskerStats = getMaskerStats();
+    await emitEvent('orchestrator.secret_masker.applied', {
+      channel: 'vault-mirror',
+      needle_count: maskerStats.needleCount,
+      records: maskerStats.records,
+      hits: maskerStats.hits,
+      dry_run: dryRun,
+    });
+  } catch {
+    // Silent no-op — see the note above.
+  }
+
   // --strict-schema: abort with exit 1 when any entry was skipped-invalid.
   // Useful in CI to catch producer-side schema drift early (issue #249).
   if (strictSchema && skippedInvalidCount > 0) {

package/skills/_shared/monitor-patterns.md

@@ -36,11 +36,11 @@ the GitHub mirror's main-branch SHA so the operator can confirm parity.
 ```bash
 prev=""
 while true; do
-  s=$(glab ci status --pipeline-id LATEST --output json 2>/dev/null || echo '[]')
-  cur=$(jq -r '.[] | select(.status!="running" and .status!="pending") | "\(.name): \(.status)"' <<<"$s" 2>/dev/null | sort)
+  s=$(glab ci status -R <OWNER>/<REPO> --output json 2>/dev/null || echo '{"jobs":[]}')
+  cur=$(jq -r '.jobs[] | select(.status!="running" and .status!="pending") | "\(.name): \(.status)"' <<<"$s" 2>/dev/null | sort)
   comm -13 <(echo "$prev") <(echo "$cur")
   prev=$cur
-  jq -e 'all(.status=="success" or .status=="failed" or .status=="canceled" or .status=="skipped")' <<<"$s" >/dev/null 2>&1 && {
+  jq -e '(.jobs|length) > 0 and (.jobs | all(.status=="success" or .status=="failed" or .status=="canceled" or .status=="skipped"))' <<<"$s" >/dev/null 2>&1 && {
     sha=$(gh api repos/Kanevry/session-orchestrator/commits/main --jq '.sha' 2>/dev/null || echo "(mirror unreachable)")
     echo "GitHub mirror main: $sha"
     break
@@ -55,8 +55,28 @@ done
 SHA — silence at the end means glab JSON parsing failed (the `||` fallbacks
 prevent the whole loop from dying).
 
+**Probed 2026-08-14 (glab 1.91.0), three corrections — #1022.** The snippet
+above was silence-is-not-success in its own right until that date, and each
+half failed into the next one's fallback:
+
+- `--pipeline-id LATEST` is not a glab flag on any `ci` subcommand
+  (`ERROR Unknown flag`, exit 1), so `$s` was always the `||` fallback. There is
+  no replacement — the argument-less form already selects the current branch's
+  pipeline. Avoid `--branch=<name>` here: it pins a snapshot taken when the
+  monitor was armed.
+- The payload is an OBJECT (`{"jobs":[…],"pipeline":{…}}`), so `.[]` raised
+  `Cannot index array with string "status"` (jq exit 5) on every real response.
+  The accessor is `.jobs[]`.
+- `all(…)` over the empty fallback returns **true**, so the loop broke and
+  printed the mirror SHA on its FIRST iteration whenever glab hiccuped — a
+  transient network error read as "pipeline finished". The `(.jobs|length) > 0`
+  guard is what makes the fallback non-terminal; verified by running the
+  terminal test against `{"jobs":[]}` (exit 1 = keep watching) versus the old
+  form against `[]` (exit 0 = break).
+
 **GitHub-mirror equivalent.** When the pipeline is GitHub-Actions-native (PR
-checks rather than a GitLab pipeline), use `gh pr checks <pr> --watch --fail-fast`
+checks rather than a GitLab pipeline), use
+`gh pr checks -R <OWNER>/<REPO> <pr> --watch --fail-fast`
 as the `command` source — it streams each check transition and exits non-zero on
 the first failure, so the terminal state is never silent.