session-orchestrator 3.19.0 → 3.21.0

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,53 @@ 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.
+ *
+ * @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.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 +160,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 +346,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 +522,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 +698,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-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.
 

package/skills/_shared/state-ownership.md

@@ -219,3 +219,20 @@ Net: `pid` (field notes above) stays forensic-only; `last_heartbeat` freshness i
 ### Schema v1 → v2 backward-compat
 
 Readers (e.g., `readLock()` in `session-lock.mjs`, `discoverActiveSessions()`) MUST tolerate absent `last_heartbeat` and `semantic_session_id` fields (v1 locks written before Epic #583). When `last_heartbeat` is absent, fall back to TTL-based expiry from `started_at`. When `semantic_session_id` is absent, treat as unknown.
+
+#### Schema v1 Sunset — evaluated 2026-08-15, tolerance RETAINED (#595)
+
+The 90-day sunset window from Epic #583 (target 2026-08-25) came due and the removal was evaluated against the live fleet. **Verdict: keep the three reader tolerances; the blocker is not v1 data, it is a second production copy of the rule.**
+
+**Precondition — zero v1 artefacts on disk (measured 2026-08-15, this host):**
+
+- `find ~/Projects ~/.claude ~/.config /tmp/claude-501 -name 'session.lock' -not -path '*/node_modules/*'` → **12 files, 12/12 carry a non-empty `last_heartbeat`** (0 v1).
+- `~/.config/session-orchestrator/sessions/active/*.json` → **3 entries, 3/3 carry the `mode` key** (0 v1).
+- The only co-installed older plugin build (`~/.claude/plugins/cache/session-orchestrator/session-orchestrator/3.13.0`) already writes `last_heartbeat` (`session-lock.mjs:195`) and `mode` (`session-registry.mjs:209`) — **no v1 writer remains on this host.**
+
+**Why the branches stay anyway:**
+
+1. **`parseLock()` / `isLockLive()` — the rule is duplicated.** `scripts/lib/harness-audit/categories/category4.mjs` `lockIsLive()` inlines the same `last_heartbeat ?? started_at` fallback, and `tests/lib/lock-ttl-parity.test.mjs` asserts the mirror and the SSOT return identical verdicts *for a v1 lock*. Dropping it in `session-lock.mjs` alone breaks that parity by construction. A measured removal attempt turned **18 tests red across 4 files** (`session-discovery` 9, `session-discovery-fallback` 6, `lock-ttl-parity` 1, `on-session-start` 2) — all outside the lock/registry module pair, all seeding v1-shaped fixtures.
+2. **`_validEntry()` optional `mode` — removal is a net safety LOSS.** Rejecting a mode-less registry entry drops a **live peer** from `readRegistry()`, making it invisible to the exclusivity matrix. An absent `mode` already degrades to the `parallel-ok` bucket, so strictening buys no detection and costs peer visibility — the wrong direction under `.claude/rules/development.md` § Guard & Threshold Design.
+
+**What a real sunset needs (co-change set, one atomic MR):** `scripts/lib/session-lock.mjs` + `scripts/lib/harness-audit/categories/category4.mjs` (the mirror) + fixture updates in `tests/lib/session-discovery.test.mjs`, `tests/lib/session-discovery-fallback.test.mjs`, `tests/lib/lock-ttl-parity.test.mjs`, `tests/hooks/on-session-start.test.mjs`. Deleting the *mirror* in favour of importing the SSOT is the durable fix — the duplication, not the v1 data, is what keeps this class alive. The registry item should be closed as won't-do per point 2.

package/skills/brainstorm/soul.md

@@ -4,7 +4,7 @@
 
 You are the Design Facilitator — a thinking partner who shapes vague feature ideas into approved designs through Socratic questioning. You don't implement; you clarify. You don't collect wishes; you narrow the design space until one path is clearly better than the others.
 
-You respond in {{owner.language}} when that matches the user's language. You meet people at their abstraction level — product language with stakeholders, technical language with engineers.
+You answer in the operator's language: `owner.language` in `~/.config/session-orchestrator/owner.yaml`, falling back to `en` when that file is missing, unreadable, or the key is absent — and following the operator's own language the moment he writes in another one. You meet people at their abstraction level — product language with stakeholders, technical language with engineers.
 
 ## Communication Principles
 
@@ -23,6 +23,52 @@ Three well-chosen AUQ rounds beat five meandering ones. When you have enough sig
 ### Confirm understanding before advancing
 After Phase 1, summarize your understanding in 1-2 plain-text sentences before running the first dialogue round. After Phase 2, surface the running summary between rounds. Catching a misunderstanding at round 2 costs one turn; catching it at Phase 4 costs a rewrite.
 
+### Length is a dial, not taste
+How much you say around each question is set by the operator, not chosen by mood — see § Output Levels. "Less is more" is the discipline; the budget is the number that makes it checkable.
+
+## Output Levels
+
+The active level is `efficiency.output-level` in `~/.config/session-orchestrator/owner.yaml`. If that file is missing, unreadable, or the key is absent, the level is `full`. Apply the matching block below for the whole dialogue.
+
+**How to read a budget.** A *round* is every chat line you author between one answered question and your next `AskUserQuestion` call — the running summary, the trade-off framing, the one sentence of recommendation reasoning. A budget is a ceiling, not a target: under is fine, over is a defect. You meet it by WITHHOLDING, never by dropping — no trade-off disappears, it moves into the option description where the operator can act on it.
+
+**The spec carries no budget.** The file you write to `docs/specs/` is the deliverable, not the conversation. Budgets bound chat only; the spec keeps its full Out-of-Scope and Open-Questions sections, and pointing at it is the preferred way to stay under one.
+
+**Escalation (all levels).** When the operator writes `expand <topic>` (German: `mehr zu <Abschnitt>`), print that topic's full detail immediately, without re-asking and without the budget applying to that one response.
+
+**Never traded for brevity (all levels).** No budget may be met by cutting any of the following. Where a budget and one of them collide, the budget yields:
+- input validation, and the reporting of invalid input;
+- error handling, error messages, and failure disclosure — a swallowed error is never "concise";
+- security findings, warnings, and destructive-action confirmations (PSA-003);
+- accessibility of the output itself — no meaning carried by colour or emoji alone, no bare unlabelled numbers, no table whose header you dropped to save a line;
+- anything the operator explicitly asked to see;
+- the concrete pro and the concrete con on each option (`.claude/rules/ask-via-tool.md` AUQ-002/AUQ-003) — a budget never buys back the menu this skill exists to avoid.
+
+### output-level: ultra
+- Meaning: telegraphic — the running summary, the trade-offs, the question. No narration.
+- Budget: ≤10 lines per round; ≤2 lines of running summary; ≤1 line of recommendation reasoning before the tool call.
+- Shape: bullets only. Trade-offs as `<option> — gains <X>, costs <Y>`. Never restate the user's last answer back at them.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: full
+- Meaning: terse but complete — framing trimmed, trade-offs preserved. This is the default.
+- Budget: ≤25 lines per round; ≤4 lines of running summary; ≤2 lines of recommendation reasoning before the tool call.
+- Shape: name the design tension in one line, then the options. Prose only where a bullet would lose the causal link between a choice and what it forecloses.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: lite
+- Meaning: verbose — the reasoning behind the narrowing is spelled out. Chosen for learning, not for speed.
+- Budget: ≤60 lines per round; ≤10 lines of running summary. Still a ceiling — `lite` is not "unbounded".
+- Shape: explain WHY each option is on the table, name the paths you already discarded and why, define unfamiliar terms on first use.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### Companion dials
+
+Same file, same lookup, same fallback-to-default rule:
+
+- `efficiency.preamble` — `minimal` (default): at most one clause before a tool call, and only when the next step is non-obvious; never "Let me check the repo." immediately followed by checking it. `verbose`: one sentence before each tool call naming what you expect to find.
+- `tone.style` — `direct` (this soul's baseline: name a confused framing plainly and reframe), `neutral` (state the tension without advocacy; still recommend when asked), `friendly` (same content, softer framing; never softer facts).
+
 ## Decision-Making Philosophy
 
 When design ambiguity arises, resolve it in this order:

package/skills/claude-md-drift-check/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: claude-md-drift-check
-description: Use when detecting drift between CLAUDE.md (or AGENTS.md, the Codex CLI alias) / _meta narrative and live repository state. Ten checks: absolute-path resolution, 01-projects/ count claims, issue-reference freshness, session-file existence, command-count sync, session-config-parity (mandatory template keys = error, opt-in gaps = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness (WARN-only), rule-scoping (paths:/globs: frontmatter defects, dangling rule citations, zero-match globs), and docs-parity (docs/components.md count-claims vs on-disk counts, template-vs-reference config-key parity, stale .claude/metrics/ paths). Full per-check spec in the body table. Invoked as an opt-in session-end phase; mirrors vault-sync's lean JSON+exit-code contract.
+description: >
+  Use when detecting drift between CLAUDE.md (or AGENTS.md, the Codex CLI alias) / _meta narrative and
+  live repository state. Ten checks: absolute-path resolution, 01-projects/ count claims, issue-reference
+  freshness, session-file existence, command-count sync, session-config-parity (mandatory template keys =
+  error, opt-in gaps = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness
+  (WARN-only), rule-scoping (paths:/globs: frontmatter defects, dangling rule citations, zero-match
+  globs), and docs-parity (docs/components.md count-claims vs on-disk counts, template-vs-reference
+  config-key parity, stale .claude/metrics/ paths). Full per-check spec in the body table. Invoked as an
+  opt-in session-end phase; mirrors vault-sync's lean JSON+exit-code contract.
 model: haiku
 ---
 

package/skills/debug/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: debug
-description: Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
+description: >
+  Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase
+  systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE
+  INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
 model: inherit
 color: red
 tools: Read, Grep, Glob, Bash, Write

package/skills/discovery/issue-templates.md

@@ -79,7 +79,7 @@ Used for a single finding from a single probe.
 **CLI Example:**
 ```bash
 # GitHub
-gh issue create \
+gh issue create -R <OWNER>/<REPO> \
   --title "[Discovery] <finding_title>" \
   --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --body "$(cat <<'EOF'
@@ -88,7 +88,7 @@ EOF
 )"
 
 # GitLab
-glab issue create \
+glab issue create -R <OWNER>/<REPO> \
   --title "[Discovery] <finding_title>" \
   --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --description "$(cat <<'EOF'
@@ -159,7 +159,7 @@ Used when multiple related findings from the same probe or category are grouped
 **CLI Example:**
 ```bash
 # GitHub
-gh issue create \
+gh issue create -R <OWNER>/<REPO> \
   --title "[Discovery] <category> audit: <summary>" \
   --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --body "$(cat <<'EOF'
@@ -168,7 +168,7 @@ EOF
 )"
 
 # GitLab
-glab issue create \
+glab issue create -R <OWNER>/<REPO> \
   --title "[Discovery] <category> audit: <summary>" \
   --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --description "$(cat <<'EOF'

package/skills/discovery/probes-code.md

@@ -58,9 +58,9 @@ Grep pattern: (TODO|FIXME|HACK|XXX|TEMP|WORKAROUND)[\s:()\-]
 For each match, check whether a corresponding VCS issue exists:
 ```bash
 # Search for issue referencing the annotation text
-gh issue list --search "<annotation text>" --limit 5
+gh issue list -R <OWNER>/<REPO> --search "<annotation text>" --limit 5
 # or
-glab issue list --search "<annotation text>" --per-page 5
+glab issue list -R <OWNER>/<REPO> --search "<annotation text>" --per-page 5
 ```
 
 Flag annotations with no corresponding issue.

package/skills/discovery/probes-feature.md

@@ -113,11 +113,11 @@ Export Status: exported/public | internal
 1. List open feature/enhancement issues via the VCS CLI (syntax reference: `skills/gitlab-ops/SKILL.md` § "Common CLI Commands" — do not duplicate CLI flags here beyond what's needed to name the call):
 ```bash
 # GitLab
-glab issue list --label "feature" --per-page 100
-glab issue list --label "enhancement" --per-page 100
+glab issue list -R <OWNER>/<REPO> --label "feature" --per-page 100
+glab issue list -R <OWNER>/<REPO> --label "enhancement" --per-page 100
 # GitHub
-gh issue list --label "feature" --limit 100
-gh issue list --label "enhancement" --limit 100
+gh issue list -R <OWNER>/<REPO> --label "feature" --limit 100
+gh issue list -R <OWNER>/<REPO> --label "enhancement" --limit 100
 ```
 
 2. Extract theme keywords from each issue's title (and first paragraph of body where available): lowercase, strip stop-words, tokenize on non-alphanumeric boundaries. Group issues that share two or more significant keywords (e.g. "export", "csv", "invoice") into a candidate cluster.
@@ -125,10 +125,10 @@ gh issue list --label "enhancement" --limit 100
 3. For each candidate cluster with 3 or more issues, check whether ANY member issue is already linked to an epic (`epic` label, a GitLab Epic relationship, or an in-body reference such as `part of #<epic-iid>` / `Epic: #<epic-iid>`):
 ```bash
 # GitLab -- inspect labels + description for epic linkage
-glab issue view <IID>
+glab issue view -R <OWNER>/<REPO> <IID>
   Grep pattern: (^Labels:.*\bepic\b|part of #|Epic:\s*#)
 # GitHub -- same check against issue body/labels
-gh issue view <NUMBER>
+gh issue view -R <OWNER>/<REPO> <NUMBER>
   Grep pattern: (^labels:.*\bepic\b|part of #|Epic:\s*#)
 ```