session-orchestrator 3.20.0 → 3.21.0

package/scripts/lib/secret-masker.mjs

@@ -0,0 +1,262 @@
+/**
+ * secret-masker.mjs — value-based secret masking over arbitrary log text (#974).
+ *
+ * Builds a masking function from an env-like object: every value that survives
+ * three filters becomes a NEEDLE, and every occurrence of a needle in the input
+ * text is replaced with the repo-wide `[REDACTED]` marker.
+ *
+ * Pure and synchronous — no I/O, no module state, no dependencies beyond the
+ * sibling `redact-spans.mjs` primitive — because hot-path consumers import it.
+ * This module deliberately does NOT wire itself into any consumer; wiring is a
+ * separate concern (and a separate wave).
+ *
+ * ---------------------------------------------------------------------------
+ * THE NEEDLE SET IS A FUNCTION OF THE CALLER'S ENV — AND THAT IS NOT A DEFECT
+ * ---------------------------------------------------------------------------
+ * Two runs of the same consumer over the same records mask DIFFERENTLY when the
+ * env differs between them (#1025): with `FOO_TOKEN` set, its value becomes
+ * `[REDACTED]`; without it, the same text passes through verbatim. Consumers that
+ * compare a previously-written artifact against a freshly-rendered candidate must
+ * therefore treat an already-redacted span as a WILDCARD, or a later
+ * partially-populated run re-writes the raw value it had already redacted (see
+ * `matchesModuloRedaction` in `scripts/lib/vault-mirror/process.mjs`).
+ *
+ * The tempting fix — persist the needle set so a later run can mask without the
+ * env — is REJECTED: it breaks the purity contract in the paragraph above and
+ * puts a plaintext secrets file on disk to defend against secrets on disk. The
+ * env dependency stays; consumers compensate.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THE FILTER ORDER IS ALLOWLIST → KEY-NAME → LENGTH, AND NOT LENGTH FIRST
+ * ---------------------------------------------------------------------------
+ * A "mask every env value longer than N characters" masker is the obvious
+ * design and it is measurably WRONG. Discovery measured 40 env values of ≥8
+ * characters on the development host against 5.2 MB of real log text; six of
+ * them collide with ordinary log content:
+ *
+ *   len 21 → 157 corpus hits (USER, LOGNAME)
+ *   len 28 → 157 corpus hits (HOME)
+ *   len 58 → 154 corpus hits (PWD, OLDPWD)
+ *   len 36 →  39 corpus hits (CLAUDE_CODE_SESSION_ID)
+ *
+ * The shortest REAL secret on that host is 32 characters; the longest collider
+ * is 58. The bands overlap completely: any threshold ≤58 admits PWD (154
+ * mis-maskings), any threshold >58 discards three real secrets (32/50/51). There
+ * is no separating value — length is provably not a discriminating feature.
+ * Length therefore runs LAST, purely as a guard against degenerate short values
+ * (`X_KEY=1`), never as the primary filter.
+ *
+ * ---------------------------------------------------------------------------
+ * CLAUDE_CODE_SESSION_ID — the sharpest boundary case, and why it is NOT
+ * allowlisted
+ * ---------------------------------------------------------------------------
+ * It is 36 characters with 39 corpus hits: length-indistinguishable from a
+ * 32-character token, yet a legitimate correlation key that appears in ordinary
+ * log lines. Masking it would destroy the log's correlation value; not masking
+ * it costs nothing, because a session id is not a credential (the credential
+ * beside it is CLAUDE_CODE_MESSAGING_TOKEN, which DOES qualify via `_TOKEN`).
+ *
+ * The decision is to leave it OUT of the allowlist and let filter 2 exclude it
+ * structurally: it ends in `_ID`, which the key-name heuristic does not match,
+ * so it can never become a needle. An allowlist entry would be redundant today
+ * AND silent tomorrow — if someone later widens the heuristic to `_ID`, an
+ * allowlist entry would quietly absorb the change, whereas the pinned test
+ * (`tests/lib/secret-masker.test.mjs`) goes RED and forces the decision to be
+ * taken again. The louder mechanism wins.
+ *
+ * ---------------------------------------------------------------------------
+ * NEEDLE SET IS `{raw}` ONLY — no base64, no percent-encoding
+ * ---------------------------------------------------------------------------
+ * Encoded variants are theoretical in this repo: the only encoders encode FILE
+ * PATHS (`scripts/lib/fetch-baseline.mjs`, `scripts/lib/vault-backfill/glab.mjs`)
+ * or HOOK SOURCE (`hooks/_lib/guard-source-loader.mjs`) — never credentials. And
+ * typical token alphabets are URI-unreserved, so percent-encoding would be the
+ * identity transform for them anyway. Each extra variant triples the needle set
+ * and with it the collision surface, buying coverage for no reachable path.
+ *
+ * @see scripts/lib/redact-spans.mjs — the overlap-safe span merge this delegates to
+ * @see scripts/lib/quality-gate/diagnostics.mjs — SECRET_ENV_NAME_RE, the shape mirrored below
+ */
+
+import { redactSpans } from './redact-spans.mjs';
+
+/**
+ * Filter 1 — deny-by-default for MASKING: these keys never become needles.
+ *
+ * Measured, not guessed: every entry either appears verbatim in ordinary log
+ * text (paths, usernames, terminal identity) or is a public toolchain constant.
+ * Masking any of them corrupts the log without protecting anything.
+ *
+ * HONEST NOTE ON ITS CURRENT REACH — measured, not assumed: no key in this set
+ * ends in a secret-bearing suffix, so filter 2 alone already rejects every one
+ * of them. Proven by a fake-regression probe: with this whole set bypassed and
+ * filter 2 intact, the over-masking tests in `tests/lib/secret-masker.test.mjs`
+ * stayed GREEN (16/17 — the single failure was the unrelated escaping probe run
+ * in the same pass). This set is therefore defense-in-depth plus a record of the
+ * measurement — NOT the load-bearing filter. Do not read a green over-masking
+ * test as proof that this list stopped the collision; the key-name heuristic
+ * did. Adding a secret-NAMED key here would open a silent hole in which a real
+ * credential is never masked, so any such addition needs its own justification
+ * beside the entry.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const NEVER_MASK_KEYS = new Set([
+  // A — POSIX / shell identity and paths; guaranteed to occur in log text.
+  'PATH',
+  'FPATH',
+  'MANPATH',
+  'INFOPATH',
+  'XDG_DATA_DIRS',
+  'HOME',
+  'PWD',
+  'OLDPWD',
+  'TMPDIR',
+  'SHELL',
+  'USER',
+  'LOGNAME',
+  'LANG',
+  'TERM',
+  'TERMINFO',
+  'COLORTERM',
+  'COMMAND_MODE',
+  '_',
+  // B — toolchain install prefixes; public constants that appear in every
+  //     build/tool log line.
+  'HOMEBREW_PREFIX',
+  'HOMEBREW_REPOSITORY',
+  'HOMEBREW_CELLAR',
+  'BUN_INSTALL',
+  'PNPM_HOME',
+  'DOTNET_ROOT',
+  // C — terminal / platform identity.
+  'GHOSTTY_SHELL_FEATURES',
+  'GHOSTTY_BIN_DIR',
+  'GHOSTTY_RESOURCES_DIR',
+  '__CF_USER_TEXT_ENCODING',
+  '__CFBundleIdentifier',
+  'AI_AGENT',
+  'CLAUDE_CODE_EXECPATH',
+  'SSH_AUTH_SOCK',
+]);
+
+/**
+ * Filter 2 — key-name heuristic: only semantically secret-bearing NAMES qualify.
+ *
+ * This MIRRORS the shape of `SECRET_ENV_NAME_RE` in
+ * `scripts/lib/quality-gate/diagnostics.mjs:49` but is deliberately a SEPARATE
+ * declaration rather than an import. Three reasons:
+ *
+ *  1. Layering. That module is a quality-gate diagnostics helper; this one must
+ *     be importable from a hot path. Importing it would drag the diagnostics
+ *     layer (and its redaction-pattern table) into every consumer for one regex.
+ *  2. Different populations. There the input is a captured env SNAPSHOT inside a
+ *     JSON bundle and the effect is "replace the value in place"; here the input
+ *     is the live `process.env` of the host and the effect is "search for this
+ *     value in unrelated text". The second is far more destructive when it
+ *     over-matches, so the two are free to diverge — and SHOULD be.
+ *  3. Recorded prior art: consolidating a primitive does not consolidate what
+ *     its call sites feed it (learnings-index, conf 0.9). A shared regex here
+ *     would create exactly that illusion of a single decision point.
+ *
+ * Two deliberate widenings over the mirrored shape:
+ *  - a bare name (`TOKEN`, `PASSWORD`, `SECRET`, `API_KEY`-less `KEY`) qualifies;
+ *    the diagnostics form requires at least one character before the suffix.
+ *  - the key is upper-cased before testing, so lowercase env keys
+ *    (`github_token`) qualify too. `npm_config_*` keys are unaffected — none of
+ *    them end in a secret-bearing suffix.
+ */
+const SECRET_KEY_RE =
+  /^(?:[A-Z][A-Z0-9_]*(?:_TOKEN|_KEY|_SECRET|_PASSWORD|_CREDENTIAL[A-Z_]*)|TOKEN|KEY|SECRET|PASSWORD)$/;
+
+/**
+ * Filter 3 — minimum value length.
+ *
+ * NAMED CEILING (this is a deliberate simplification, per the repo's
+ * build-value rule): 8 is a DEGENERATE-VALUE guard, not a discriminator. It
+ * exists so that a secret-named key carrying a trivial value (`X_KEY=1`,
+ * `MY_TOKEN=abc`) cannot turn into a needle that shreds every line of the log.
+ * It is explicitly NOT tuned to separate secrets from non-secrets — the header
+ * shows that no such threshold exists on the measured host.
+ *
+ * REVISIT TRIGGER: if a consumer reports over-masking, the answer is an
+ * allowlist entry or a narrower key-name heuristic — NOT a higher threshold.
+ * Raising it past 32 starts discarding real secrets; every value below 58 still
+ * admits PWD. Any patch that moves this number is treating a measurement as a
+ * dial.
+ */
+const MIN_MASKABLE_LENGTH = 8;
+
+/**
+ * Decide whether a single env entry qualifies as a masking needle.
+ *
+ * The three filters run in the order documented in the module header:
+ * allowlist → key-name heuristic → length.
+ *
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function qualifiesAsNeedle(key, value) {
+  if (typeof key !== 'string' || typeof value !== 'string') return false;
+  if (NEVER_MASK_KEYS.has(key)) return false; // 1 — allowlist
+  if (!SECRET_KEY_RE.test(key.toUpperCase())) return false; // 2 — key-name heuristic
+  if (value.length < MIN_MASKABLE_LENGTH) return false; // 3 — degenerate-value guard
+  return true;
+}
+
+/**
+ * Build a value-based secret masker from an env-like object.
+ *
+ * Matching is LITERAL and CASE-SENSITIVE, with no word boundaries — two
+ * deliberate departures from the confidential-names patterns that
+ * `redactSpans` was extracted for:
+ *   - No `\b`: a secret is not a word. Tokens routinely abut quotes, `=`, `:`
+ *     and newlines, and many end in `-` or `_`, where `\b` simply fails to
+ *     anchor. A boundary condition here would silently skip real hits.
+ *   - Case-sensitive: secrets are case-sensitive by construction, and folding
+ *     case only widens the collision surface for free.
+ * Every value is regex-escaped before it becomes a pattern, so a secret
+ * containing `.`, `(`, `[` or `*` matches itself and nothing else.
+ * (`RegExp.escape` is stdlib from Node 23.5; this package requires `>=24.0.0`.)
+ *
+ * Returns an OBJECT rather than a bare function so the needle count is
+ * available to callers without a function-property trick: a consumer can log
+ * "masking active, N needles" (a count is safe to print; a value never is) and
+ * can branch on `needleCount === 0` for a fast path. The masking function
+ * itself is `mask`.
+ *
+ * @param {Record<string, unknown>} env — e.g. `process.env`. A non-object
+ *   yields a masker with zero needles (identity) rather than throwing: a hot
+ *   path must not die on a malformed argument, and there is genuinely nothing
+ *   to mask in that case.
+ * @returns {{ mask: (text: string) => string, needleCount: number }}
+ */
+export function createSecretValueMasker(env) {
+  /** @type {Set<string>} deduped — two keys sharing a value need one pattern. */
+  const values = new Set();
+  if (env && typeof env === 'object') {
+    for (const [key, value] of Object.entries(env)) {
+      if (qualifiesAsNeedle(key, value)) values.add(/** @type {string} */ (value));
+    }
+  }
+
+  const patterns = [...values].map((v) => new RegExp(RegExp.escape(v)));
+
+  /**
+   * Replace every needle occurrence in `text` with `[REDACTED]`.
+   *
+   * Delegates the overlap-safe interval merge to `redactSpans`, so a needle
+   * that is a prefix of another needle yields ONE marker, not a nested pair —
+   * no splice logic is re-derived here.
+   *
+   * @param {string} text
+   * @returns {string}
+   */
+  const mask = (text) => {
+    if (patterns.length === 0 || typeof text !== 'string') return text;
+    return redactSpans(text, patterns);
+  };
+
+  return { mask, needleCount: patterns.length };
+}

package/scripts/lib/session-lock.mjs

@@ -161,6 +161,14 @@ function lockAgeHours(lock) {
  * effective heartbeat, so TTL freshness still rescues recent locks even when
  * the writer process is dead (the D2/D5 production case).
  *
+ * RETAINED, not forgotten (#595, re-verified 2026-08-15): zero v1 files exist
+ * on this host, but this normalisation is MIRRORED in
+ * `scripts/lib/harness-audit/categories/category4.mjs` `lockIsLive()` and
+ * pinned by `tests/lib/lock-ttl-parity.test.mjs`. Removing it here alone
+ * breaks that parity by construction — see
+ * `skills/_shared/state-ownership.md` § Schema v1 Sunset for the full
+ * co-change set the removal needs.
+ *
  * @param {string} raw
  * @returns {object|null}
  */
@@ -230,6 +238,12 @@ function buildLock({ sessionId, mode, ttlHours, semanticSessionId }) {
  *
  * Liveness rule: a lock is live when (now - last_heartbeat) < ttl_hours.
  *
+ * The `started_at` fallback below is RETAINED, not forgotten (#595,
+ * re-verified 2026-08-15): it is mirrored verbatim in
+ * `scripts/lib/harness-audit/categories/category4.mjs` `lockIsLive()` and
+ * pinned by `tests/lib/lock-ttl-parity.test.mjs`. See
+ * `skills/_shared/state-ownership.md` § Schema v1 Sunset.
+ *
  * @param {{ last_heartbeat: string, started_at: string, ttl_hours?: number }} lock
  * @param {number} [nowMs]
  * @returns {boolean}
@@ -863,13 +877,18 @@ export function loadOwnerProof({ repoRoot } = {}) {
  * (see `buildLockOwnerProof()` / `isLockOwnedByProof()`) to require a SECOND
  * identity factor beyond `session_id` before deleting — this is what makes
  * a same-day semantic-id collision safe to release against. When `proof` is
- * omitted (the default), behaviour is BYTE-IDENTICAL to before this change:
- * only the `session_id` match gates the delete. This keeps the ONE other
- * external caller (`scripts/lib/autopilot/worktree-pipeline.mjs`, which does
- * not pass `proof`) working unchanged — it stays on the weaker,
- * session_id-only path.
+ * ABSENT (omitted, `undefined`, or `null`), behaviour is BYTE-IDENTICAL to
+ * before this change: only the `session_id` match gates the delete.
+ *
+ * `null` is treated as absent DELIBERATELY (#989): the two producers of a
+ * proof — `loadOwnerProof()` and `buildLockOwnerProof()` — both return `null`
+ * to mean "cannot prove ownership". Gating on `proof !== undefined` forced
+ * every call site to spread-guard (`...(proof ? { proof } : {})`) or brick
+ * release with a permanent `proof-mismatch`; treating both absent spellings
+ * alike moves that contract inside the API where it belongs. A caller that
+ * wants fail-closed-on-unprovable must branch itself before calling.
  *
- * @param {{ sessionId: string, repoRoot?: string, proof?: { pid: number, host: string, startedAt: string } }} args
+ * @param {{ sessionId: string, repoRoot?: string, proof?: { pid: number, host: string, startedAt: string }|null }} args
  * @returns {{ ok: true, deleted: boolean, reason?: string, verified?: boolean }}
  */
 export function release({ sessionId, repoRoot, proof } = {}) {
@@ -886,11 +905,16 @@ export function release({ sessionId, repoRoot, proof } = {}) {
     }
 
     // Proof-gated release (additive, #906-class fix): when the caller supplies
-    // `proof`, the session_id match above is NOT sufficient by itself —
+    // a proof, the session_id match above is NOT sufficient by itself —
     // session_id collisions are the documented root cause behind this check.
-    // Omitting `proof` leaves this branch dead code, preserving the exact
-    // pre-existing behaviour for callers that don't pass it.
-    if (proof !== undefined && !isLockOwnedByProof(existing, proof)) {
+    // Absent-proof handling (#989): an absent proof — omitted, `undefined`, or
+    // the `null` that loadOwnerProof()/buildLockOwnerProof() return for
+    // "cannot prove" — leaves this branch dead code and preserves the exact
+    // pre-existing session_id-only behaviour. No call-site spread-guard needed.
+    // Spelled out rather than as `proof != null` because the repo's `eqeqeq`
+    // lint rule admits no null-loose exception.
+    const proofSupplied = proof !== undefined && proof !== null;
+    if (proofSupplied && !isLockOwnedByProof(existing, proof)) {
       return { ok: true, deleted: false, reason: 'proof-mismatch' };
     }
 

package/scripts/lib/session-registry.mjs

@@ -23,7 +23,8 @@
  * registry-sourced peer was bucketed as `mode='session'` → classifyMode threw
  * → fell back to `parallel-ok`, silently bypassing the exclusivity matrix
  * for cross-repo entries (D5 from Epic #583 audit). The field is optional
- * on read for back-compat with v1 entries (defaults to null).
+ * on read for back-compat with v1 entries (defaults to null) — retained
+ * deliberately, see `skills/_shared/state-ownership.md` § Schema v1 Sunset.
  */
 
 import os from 'node:os';
@@ -115,6 +116,13 @@ function _validEntry(obj) {
   // Schema v2 (Epic #583): `mode` is optional. When present it MUST be a string
   // (no number / object / array smuggling). When absent (v1 entry), it is
   // accepted — back-compat with pre-#583 registry files.
+  //
+  // RETAINED, not forgotten (#595, re-verified 2026-08-15): zero mode-less
+  // entries exist on this host, but rejecting one would make a LIVE peer
+  // invisible to the exclusivity matrix — a strict weakening of
+  // parallel-session detection for zero functional gain (an absent mode
+  // already degrades to the `parallel-ok` bucket). See
+  // `skills/_shared/state-ownership.md` § Schema v1 Sunset.
   if ('mode' in obj && obj.mode !== null && typeof obj.mode !== 'string') {
     return false;
   }

package/scripts/lib/state-md/mission-status.mjs

@@ -24,8 +24,9 @@ import { updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mj
  * STATE.md files). Returns `[]` when the key is present but the value is an empty
  * array. Returns the array of entries when present and non-empty.
  *
- * Does NOT validate individual entry shapes — callers that need schema validation
- * should use `validateMissionStatusEntry` from mission-status-schema.mjs.
+ * Does NOT validate individual entry shapes, and no helper in this repo does:
+ * entry shape and the `status` enum are coordinator convention, deliberately not a
+ * mechanical gate (see `syncFrontmatterMissionStatus` below for why).
  *
  * @param {object} frontmatter
  * @returns {object[]|null}
@@ -55,9 +56,9 @@ export function parseMissionStatus(frontmatter) {
  * - Works on string input (pure — no file I/O). Returns the updated STATE.md contents.
  * - No-ops if `contents` has no parseable frontmatter (returns input unchanged).
  *
- * Individual entry objects must conform to the shape validated by
- * `validateMissionStatusEntry` in mission-status-schema.mjs, but this function does
- * NOT enforce that constraint — callers are responsible for pre-validation.
+ * Individual entry objects are expected to carry `{ id, task, wave, status }`, but
+ * this function does NOT enforce that shape and no validator in this repo does —
+ * callers own the invariant.
  *
  * @param {string} contents
  * @param {object[]|null|undefined} missionStatusArray
@@ -85,16 +86,24 @@ export function writeMissionStatus(contents, missionStatusArray) {
  * UPDATE-ONLY by design: when the key is absent, is not an array, or holds no entry
  * with a matching `id`, the frontmatter is returned unchanged. It is deliberately
  * neither created nor an error, because `setMissionStatus(contents, taskId, status)`
- * knows only `id` and `status` — it lacks the `task` and `wave` fields that
- * `validateMissionStatusEntry` (mission-status-schema.mjs) requires, so a synthesised
- * entry would be schema-invalid yet look authoritative to frontmatter consumers such
- * as `vault-status/narrative-mirror.mjs`. Throwing is likewise excluded by the
- * never-throw contract of `setMissionStatus`.
+ * knows only `id` and `status` — it lacks the `task` and `wave` fields a full entry
+ * carries, so a synthesised entry would be shape-invalid yet look authoritative to
+ * frontmatter consumers such as `vault-status/narrative-mirror.mjs`. Throwing is
+ * likewise excluded by the never-throw contract of `setMissionStatus`.
  *
  * `status` is mirrored verbatim without an enum check on purpose: gating it would
  * reintroduce the exact divergence (body says X, frontmatter says Y) this sync exists
- * to remove. An out-of-enum value now lands on BOTH surfaces, where the repo's own
- * validator can see it.
+ * to remove. An out-of-enum value therefore lands visibly on BOTH surfaces rather than
+ * being silently rejected on one.
+ *
+ * There is deliberately NO transition validator behind this. A `mission-status-schema.mjs`
+ * once existed (#340) offering `isValidMissionStatusTransition`; it was never wired and
+ * was removed, because the only guard form it enabled — read the current status, reject a
+ * disallowed transition — would reject legitimate live writes. Measured against a copy of
+ * this repo's own STATE.md carrying 24 items: 12 had no body entry yet (current status
+ * reads `null`, so every transition out of them is "invalid"), and the routine
+ * `in-dev` → `completed` write is not in the strict forward chain either — 18 of 24
+ * writes would have been refused. The enum is a vocabulary, not a state machine.
  *
  * @param {object} frontmatter
  * @param {string} taskId

package/scripts/lib/tmux-layout/vcs-detector.mjs

@@ -6,20 +6,116 @@
  * so all commands are wrapped in a `while true; sleep` loop per D5 findings.
  *
  * Issue #561 — ADR-0007 tmux-visualization substrate.
+ *
+ * ## The probed pane commands — SSOT for the lockstep test
+ *
+ * The two lines below are the argv this module emits, with the resolved repo
+ * spec written as `<spec>` and the `2>&1` redirect dropped. They are not a
+ * description of the commands: `tests/lib/tmux-layout/vcs-detector.test.mjs`
+ * reconstructs the same normalisation from `detectVcsCommand()` and asserts
+ * equality, so a flag added to the emitted command without a matching probe
+ * here turns that test RED. See § Why a probe line, not prose.
+ *
+ *   PROBE 2026-08-14 glab 1.91.0: glab ci status -R <spec> --output json
+ *   PROBE 2026-08-14 gh 2.86.0: gh pr checks --watch
+ *
+ * ## Why `glab ci status` carries no pipeline selector (#1022)
+ *
+ * The glab pane emitted `--pipeline-id LATEST` until 2026-08-14. That flag does
+ * not exist on any `glab ci` subcommand, and `glab ci status --help` (1.91.0)
+ * lists only `-b --branch`, `-c --compact`, `-l --live`, `-F --output`,
+ * `-R --repo`. Probed from a non-git cwd against this repo's own remote:
+ *
+ *   with the flag → `ERROR Unknown flag: --pipeline-id.`, exit 1
+ *   without it    → exit 0, `{"jobs":[…],"pipeline":{…}}`
+ *
+ * So the flag was the sole cause and it has NO replacement: the argument-less
+ * form already means "the pipeline of the current branch" (glab's own help
+ * example). `--branch=<name>` is the only selector glab offers and is
+ * deliberately NOT used — it would freeze a render-time branch snapshot into a
+ * pane that must follow the operator's checkout, the same reason the gh pane
+ * takes no positional.
+ *
+ * The `jq` filter was dead by the same measurement and is fixed with it: the
+ * payload is an OBJECT keyed `jobs`/`pipeline`, so the old `.[]` raised
+ * `Cannot index array with string "name"` (jq exit 5) on every real response.
+ * `.jobs[]` returns one `<status> <name>` line per job. Because the whole
+ * pipeline is `… 2>&1 | jq … 2>/dev/null || echo …`, both failures were
+ * swallowed into the fallback text — the pane printed "glab not available or no
+ * pipeline" against a healthy pipeline, indistinguishable from a missing binary.
+ *
+ * ## Why only the glab pane carries `-R` (#971)
+ *
+ * The pane commands run in whatever cwd the operator pastes the one-liner into,
+ * so an omitted `-R`/`--repo` silently targets the ambient cwd remote. Both
+ * halves were probed against the installed binaries on 2026-08-14
+ * (glab 1.91.0 / gh 2.86.0) and they do NOT behave the same:
+ *
+ *  - `glab ci status -R <spec> --output json` from a NON-git cwd → exit 0 with
+ *    real pipeline JSON. The flag is applicable and makes the pane
+ *    cwd-independent, so it is passed whenever `resolveRepoSpec()` resolves one.
+ *  - `gh pr checks -R <spec>` with NO positional argument →
+ *    `argument required when using the --repo flag` (exit non-zero, no output).
+ *    gh selects "the PR of the current branch" ONLY in the argument-less form;
+ *    `-R` is legal there only alongside a `<number> | <url> | <branch>`
+ *    positional, which this pane deliberately does not have (the watched branch
+ *    must follow the operator's checkout, and a render-time branch snapshot
+ *    would go stale on the next `git switch`). Adding `-R` there would break the
+ *    pane at runtime — the exact defect shape recorded in
+ *    `scripts/lib/ci-status-banner.mjs` (`-R` on `gh repo view`, which rejects
+ *    it). The gh pane therefore stays cwd-scoped BY MEASUREMENT, not by
+ *    oversight.
+ *
+ * ## Why a probe line, not prose
+ *
+ * The #971 sweep added `-R` here and left `--pipeline-id` untouched, then wrote
+ * a header documenting a probe of `glab ci status -R <spec> --output json` —
+ * a command the pane never emitted. The measurement was real and cited for
+ * something it had not measured, so a dead flag rode through a green test.
+ * NAMED CEILING: the lockstep only proves that command and probe were changed
+ * together; it cannot prove the probe was re-executed. It buys the one step
+ * that was skipped — no flag change without touching the measurement record.
+ * Revisit if a pane ever needs a runtime-varying flag, which this shape cannot
+ * express.
+ */
+
+import { resolveRepoSpec } from '../vcs-repo-spec.mjs';
+
+/**
+ * Shell-safe spec shape. A git remote URL (`git@host:group/project.git`,
+ * `https://host/group/project.git`) and an `OWNER/REPO` spec are both fully
+ * inside this character class, so a matching value can be spliced into the pane
+ * command line without quoting. A value OUTSIDE it is DROPPED (the flag is
+ * omitted) rather than quoted — this mirrors `resolveRepoSpec`'s own contract
+ * that an unresolvable spec means "omit the flag entirely", never "emit a
+ * broken one", and keeps a hostile remote URL out of the pane's shell.
  */
+const SHELL_SAFE_SPEC_RE = /^[A-Za-z0-9._:/@+-]+$/;
 
 /**
  * Resolve the CI-watch pane command based on Session Config vcs: key.
  *
- * @param {{ config?: object, projectRoot: string }} args
+ * @param {{
+ *   config?: object,
+ *   projectRoot: string,
+ *   gitRun?: (args: string[]) => { ok: boolean, stdout: string, stderr: string }
+ * }} args
+ *   - gitRun: optional `resolveRepoSpec` seam, so callers/tests can pin the
+ *     resolved repo spec instead of spawning `git` against the real checkout.
  * @returns {{ bin: 'glab'|'gh'|null, command: string, fallback: string, blocking: boolean, platform: 'gitlab'|'github'|null }}
  *   - command: the shell command for Pane 3 (wrapped in poll-loop since glab/gh are poll-based, not live-tail)
  *   - fallback: shell command shown when bin is not available in PATH
  */
-export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
+export function detectVcsCommand({ config, projectRoot, gitRun }) {
   const vcs = config?.vcs;   // 'gitlab' | 'github' | undefined
 
   if (vcs === 'gitlab') {
+    const spec = resolveRepoSpec({
+      repoRoot: projectRoot,
+      vcs: 'gitlab',
+      ...(typeof gitRun === 'function' ? { gitRun } : {}),
+    });
+    const repoFlag = spec && SHELL_SAFE_SPEC_RE.test(spec) ? ` -R ${spec}` : '';
     return {
       bin: 'glab',
       platform: 'gitlab',
@@ -29,8 +125,12 @@ export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
         '  clear;',
         '  date;',
         "  echo '--- glab ci status (refresh: 15s) ---';",
-        '  glab ci status --pipeline-id LATEST --output json 2>&1',
-        "    | jq -r '.[] | \"\\(.status) \\(.name)\"' 2>/dev/null",
+        // No pipeline selector: `--pipeline-id` is not a glab flag (1.91.0
+        // rejects it outright) and the argument-less form already means "the
+        // current branch's pipeline". `.jobs[]`, not `.[]` — the payload is an
+        // object. Both measured 2026-08-14; see the module header.
+        `  glab ci status${repoFlag} --output json 2>&1`,
+        "    | jq -r '.jobs[] | \"\\(.status) \\(.name)\"' 2>/dev/null",
         "    || echo 'glab not available or no pipeline';",
         '  sleep 15;',
         'done',
@@ -55,6 +155,10 @@ export function detectVcsCommand({ config, projectRoot: _projectRoot }) {
         '  clear;',
         '  date;',
         "  echo '--- gh pr checks --watch (will exit on PR completion) ---';",
+        // No `-R` here BY MEASUREMENT, not by oversight: `gh pr checks -R <spec>`
+        // without a positional PR/branch argument is rejected outright
+        // ("argument required when using the `--repo` flag", gh 2.86.0), and this
+        // pane must follow the operator's current branch. See the module header.
         '  gh pr checks --watch 2>&1',
         "    || echo 'no PR in current branch';",
         '  sleep 15;',