session-orchestrator 3.22.0 → 3.23.0

package/scripts/lib/autopilot/worktree-pipeline.mjs

@@ -36,6 +36,11 @@ import { acquire, release, buildLockOwnerProof } from '../session-lock.mjs';
 import { emitEvent } from '../events.mjs';
 import { main as gcMain } from '../../gc-stale-worktrees.mjs';
 import { SEMANTIC_ID_RE } from '../session-id.mjs';
+import { repoPathHash } from '../session-registry.mjs';
+// Marker location is owned by its READER (session-end Phase 4a) — importing the
+// constant from there keeps writer and reader on one string. The dependency runs
+// heavy→lean (this pipeline → the dependency-free cleanup helper), never back.
+import { PROMOTION_MARKER_RELPATH } from '../session-end/worktree-cleanup.mjs';
 
 // ---------------------------------------------------------------------------
 // Type definitions
@@ -547,6 +552,134 @@ export async function runStoryPipeline(context, opts = {}) {
 /** Valid git branch character set — mirrors isValidBranch from session-id.mjs. */
 const ENTER_WORKTREE_BRANCH_RE = /^[a-zA-Z0-9._/-]+$/;
 
+/**
+ * Raised when the promotion branch `so/<sessionId>` is already checked out by
+ * another worktree. Refusing is the point: adopting a foreign target worktree
+ * would put two sessions on one branch (PSA-002 territory), so the caller gets
+ * the conflicting path by name instead of a silent takeover.
+ */
+export class WorktreePromotionBranchError extends Error {
+  /**
+   * @param {string} message
+   * @param {{branch: string, checkedOutAt: string}} detail
+   */
+  constructor(message, { branch, checkedOutAt } = {}) {
+    super(message);
+    this.name = 'WorktreePromotionBranchError';
+    this.branch = branch;
+    this.checkedOutAt = checkedOutAt;
+  }
+}
+
+/**
+ * Map of branch name → worktree path for every branch currently checked out by
+ * ANY worktree of `repoRoot` (#1067).
+ *
+ * Deliberately NOT `listWorktrees()` from `../worktree/listing.mjs`: that helper
+ * runs `git worktree list --porcelain` in `process.cwd()` (it has no repo
+ * parameter), and `enterWorktree` takes `repoRoot` explicitly precisely to avoid
+ * CWD drift (#219) — so reusing it would query whichever repo the process
+ * happens to sit in. Its `$` seam also has a different shape (`$({cwd})` returns
+ * the tag) than `enterWorktree`'s (`exec` IS the tag), so the two cannot share
+ * one injected executor. Only the `branch` lines are parsed here; `HEAD`,
+ * `detached`, `bare` and `locked` records carry nothing this decision needs.
+ *
+ * @param {Function} exec      zx-like template-tag executor (the DI seam).
+ * @param {string} repoRoot    Absolute path to the source git repository.
+ * @returns {Promise<Map<string, string>>} Branch names (without the
+ *   `refs/heads/` prefix) → the worktree path that has them checked out.
+ *   Empty on git failure — the caller then behaves exactly as it did before this
+ *   check existed, so a broken listing degrades to git's own loud
+ *   `already used by worktree` error rather than to a silent wrong branch.
+ */
+async function listCheckedOutBranches(exec, repoRoot) {
+  let stdout;
+  try {
+    const result = await exec`git -C ${repoRoot} worktree list --porcelain`;
+    stdout = String(result?.stdout ?? '');
+  } catch {
+    return new Map();
+  }
+
+  const branches = new Map();
+  let currentPath = null;
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.trimEnd();
+    const wtMatch = /^worktree (.+)$/.exec(line);
+    if (wtMatch) {
+      currentPath = wtMatch[1];
+      continue;
+    }
+    const branchMatch = /^branch refs\/heads\/(.+)$/.exec(line);
+    if (branchMatch) branches.set(branchMatch[1], currentPath ?? '');
+  }
+  return branches;
+}
+
+/**
+ * Does `<ref>` resolve in `repoRoot`? Wraps `git rev-parse --verify --quiet`.
+ *
+ * @param {Function} exec
+ * @param {string} repoRoot
+ * @param {string} ref
+ * @returns {Promise<boolean>} false on any git failure (the ref is absent, or
+ *   git could not be asked — both lead to the create-new path, whose failure
+ *   mode is git's own loud error rather than a silent wrong checkout).
+ */
+async function refExists(exec, repoRoot, ref) {
+  try {
+    await exec`git -C ${repoRoot} rev-parse --verify --quiet ${ref}`;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Record, inside the freshly created worktree, that it was auto-promoted —
+ * and from where. Best-effort: a failure to write the marker degrades Phase 4a
+ * detection to the legacy basename key, it never fails the promotion itself.
+ *
+ * No absolute source path is stored: `source_root_hash` is `repoPathHash()`, the
+ * same stable SHA-256 the session registry uses to correlate repos without
+ * exposing the operator's filesystem layout.
+ *
+ * @param {object} params
+ * @param {string} params.wtPath        Freshly created worktree.
+ * @param {string} params.sourceRoot    Resolved source checkout.
+ * @param {string} params.sessionId     Session label the worktree was created for.
+ * @param {string} params.branch        Branch the worktree actually landed on.
+ * @returns {boolean} true when the marker was written.
+ */
+function writePromotionMarker({ wtPath, sourceRoot, sessionId, branch }) {
+  try {
+    const markerPath = path.join(wtPath, PROMOTION_MARKER_RELPATH);
+    fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+    fs.writeFileSync(
+      markerPath,
+      JSON.stringify(
+        {
+          source_root_hash: repoPathHash(sourceRoot),
+          source_root_basename: path.basename(sourceRoot),
+          source_session_id: sessionId,
+          branch,
+          promoted_at: new Date().toISOString(),
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf8',
+    );
+    return true;
+  } catch (err) {
+    console.warn(
+      `enterWorktree: could not write promotion marker in ${wtPath} (${err.message}) — ` +
+        'session-end Phase 4a falls back to basename detection',
+    );
+    return false;
+  }
+}
+
 /**
  * Create a sibling git worktree for Worktree-Auto-Promotion (#574, Epic #568 P3.1).
  *
@@ -573,10 +706,25 @@ const ENTER_WORKTREE_BRANCH_RE = /^[a-zA-Z0-9._/-]+$/;
  * check as `setupWorktree` (CWE-23 / SEC-013 defence-in-depth). Throws
  * `WorktreeBoundaryError` if the computed path escapes `basePath`.
  *
- * Branch handling: if the branch already exists (verified via
- * `git rev-parse --verify <branch>`), use `git worktree add <wtPath> <branch>`
- * (reuse). Otherwise use `git worktree add -b <branch> <wtPath>` (create new).
- * This differs from `setupWorktree`, which always passes `-b`.
+ * Branch handling — three cases, decided in this order (#1067):
+ *  1. `<branch>` is already checked out by ANY worktree of `repoRoot` (the
+ *     normal session-start Phase 0.5 case, where `branch` is the CURRENT HEAD):
+ *     git refuses a second checkout of the same branch
+ *     (`fatal: '<branch>' is already used by worktree at '<repoRoot>'`). Treat
+ *     `<branch>` as a START POINT only and create a fresh promotion branch
+ *     `so/<sessionId>` at it: `git worktree add -b so/<sessionId> <wtPath> <branch>`.
+ *     The source branch and the source worktree are left untouched.
+ *     If `so/<sessionId>` ALREADY exists (a worktree directory was removed but
+ *     its branch survived), it is REUSED — `git worktree add <wtPath>
+ *     so/<sessionId>`, `reusedBranch: true` in the return — because `-b` would
+ *     abort with `fatal: a branch named 'so/<sessionId>' already exists`.
+ *     If it exists AND is checked out by some worktree, this throws
+ *     `WorktreePromotionBranchError` naming that path: adopting a foreign
+ *     target worktree is refused, never silently taken over.
+ *  2. `<branch>` exists but is not checked out (verified via
+ *     `git rev-parse --verify <branch>`): `git worktree add <wtPath> <branch>`.
+ *  3. `<branch>` does not exist: `git worktree add -b <branch> <wtPath>`.
+ * Cases 2/3 differ from `setupWorktree`, which always passes `-b`.
  *
  * @param {object} params
  * @param {string} params.basePath  - Parent directory where the new worktree goes (absolute).
@@ -585,9 +733,22 @@ const ENTER_WORKTREE_BRANCH_RE = /^[a-zA-Z0-9._/-]+$/;
  * @param {string} params.repoRoot  - Path to the source git repository (passed explicitly to avoid CWD drift per #219).
  * @param {object} [opts]
  * @param {Function} [opts.$]       - zx-like template-tag executor (DI seam); falls back to lazy `await import('zx')`.
- * @returns {Promise<{ wtPath: string, reused: boolean }>}
+ * Every freshly created worktree also gets a `.orchestrator/promoted-from.json`
+ * marker (see {@link PROMOTION_MARKER_RELPATH}) so session-end Phase 4a can
+ * still recognise it after the #1069 process boundary hands the worktree to a
+ * session with a different id. Marker writing is best-effort and never fails
+ * the promotion.
+ *
+ * @returns {Promise<{ wtPath: string, reused: boolean, branch?: string, promotedFrom?: string, reusedBranch?: true }>}
+ *   `branch` is the branch the new worktree actually landed on — equal to the
+ *   `branch` param except in case 1 above, where it is `so/<sessionId>` and
+ *   `promotedFrom` carries the requested source branch. `reusedBranch` is
+ *   present (and `true`) only when an existing `so/<sessionId>` was checked out
+ *   rather than created. All three are absent on the `reused: true` path (no
+ *   branch was chosen — the worktree pre-existed).
  * @throws {TypeError} when any required param is missing or fails validation.
  * @throws {WorktreeBoundaryError} when the computed worktree path escapes `basePath`.
+ * @throws {WorktreePromotionBranchError} when `so/<sessionId>` is checked out elsewhere.
  */
 export async function enterWorktree({ basePath, sessionId, branch, repoRoot } = {}, opts = {}) {
   // -------------------------------------------------------------------------
@@ -686,28 +847,91 @@ export async function enterWorktree({ basePath, sessionId, branch, repoRoot } =
   }
 
   // -------------------------------------------------------------------------
-  // Step 5: Detect whether branch already exists, then `git worktree add`.
+  // Step 5: Is `branch` already checked out elsewhere? (#1067)
+  //
+  // Phase 0.5 passes the CURRENT HEAD as `branch`, so in the normal promotion
+  // case it is checked out by `repoRoot` itself and git would refuse a second
+  // checkout. Then `branch` is only a start point and the worktree lands on a
+  // fresh `so/<sessionId>`; the source branch/worktree stay untouched.
   // -------------------------------------------------------------------------
-  let branchExists = false;
-  try {
-    await exec`git -C ${repoRoot} rev-parse --verify ${branch}`;
-    branchExists = true;
-  } catch {
-    // Branch does not exist — fall through to create-new path with `-b`.
+  const checkedOutBranches = await listCheckedOutBranches(exec, repoRoot);
+  const promoted = checkedOutBranches.has(branch);
+  const targetBranch = promoted ? `so/${sessionId}` : branch;
+
+  // -------------------------------------------------------------------------
+  // Step 6: Decide the `git worktree add` argv.
+  //
+  // On the promotion path the target is `so/<sessionId>`, which can be in any
+  // of THREE states — and only the first was handled before:
+  //   (a) absent           → create it at `<branch>`: `add -b so/<id> <wt> <branch>`
+  //   (b) exists, free     → REUSE it: `add <wt> so/<id>`. This is the survivor
+  //       of a worktree whose directory was removed while its branch stayed
+  //       behind (`git worktree remove` does not delete the branch); `-b` would
+  //       abort Phase 0.5 with `fatal: a branch named 'so/<id>' already exists`.
+  //   (c) exists, checked out elsewhere → REFUSE. Adopting a foreign target
+  //       worktree is exactly what Phase 0.5 must not do.
+  // -------------------------------------------------------------------------
+  let reusedBranch = false;
+  if (promoted) {
+    const checkedOutAt = checkedOutBranches.get(targetBranch);
+    if (checkedOutAt !== undefined) {
+      throw new WorktreePromotionBranchError(
+        `enterWorktree: promotion branch '${targetBranch}' is already checked out at '${checkedOutAt}' — refusing to adopt a foreign worktree`,
+        { branch: targetBranch, checkedOutAt },
+      );
+    }
+    reusedBranch = await refExists(exec, repoRoot, `refs/heads/${targetBranch}`);
   }
 
-  if (branchExists) {
+  // A branch that a worktree has checked out exists by construction, so the
+  // source-branch rev-parse probe is skipped on the promotion path.
+  let branchExists = promoted;
+  if (!promoted) {
+    try {
+      await exec`git -C ${repoRoot} rev-parse --verify ${branch}`;
+      branchExists = true;
+    } catch {
+      // Branch does not exist — fall through to create-new path with `-b`.
+    }
+  }
+
+  if (promoted && reusedBranch) {
+    await exec`git -C ${repoRoot} worktree add ${wtPath} ${targetBranch}`;
+  } else if (promoted) {
+    await exec`git -C ${repoRoot} worktree add -b ${targetBranch} ${wtPath} ${branch}`;
+  } else if (branchExists) {
     await exec`git -C ${repoRoot} worktree add ${wtPath} ${branch}`;
   } else {
     await exec`git -C ${repoRoot} worktree add -b ${branch} ${wtPath}`;
   }
 
   // -------------------------------------------------------------------------
-  // Step 6: WARN to stderr (PRD §3 P3 Gherkin row-1 + #574 DoD).
+  // Step 6b: Record the promotion FACT inside the new worktree (#1069 boundary).
+  // Session-end Phase 4a runs in a session whose id is NOT this one, so nothing
+  // in the path or the branch identifies the worktree to it — the marker does.
+  // -------------------------------------------------------------------------
+  writePromotionMarker({
+    wtPath,
+    sourceRoot: resolvedRepoRoot,
+    sessionId,
+    branch: targetBranch,
+  });
+
+  // -------------------------------------------------------------------------
+  // Step 7: WARN to stderr (PRD §3 P3 Gherkin row-1 + #574 DoD).
   // -------------------------------------------------------------------------
   console.warn(
-    `enterWorktree: created sibling worktree at ${wtPath} (branch=${branch}, sessionId=${sessionId})`,
+    promoted
+      ? `enterWorktree: created sibling worktree at ${wtPath} (branch=${targetBranch}, promoted from ${branch}, sessionId=${sessionId})`
+      : `enterWorktree: created sibling worktree at ${wtPath} (branch=${branch}, sessionId=${sessionId})`,
   );
 
-  return { wtPath, reused: false };
+  if (promoted) {
+    const result = { wtPath, reused: false, branch: targetBranch, promotedFrom: branch };
+    // Present only when it happened, so the common shape stays byte-identical
+    // for every existing consumer and strict-equality pin.
+    if (reusedBranch) result.reusedBranch = true;
+    return result;
+  }
+  return { wtPath, reused: false, branch };
 }

package/scripts/lib/build-live-signals.mjs

@@ -10,7 +10,8 @@
  *  - Synchronous file I/O for STATE.md / sessions.jsonl / bootstrap.lock.
  *    The async wrapper exists only because `scanBacklog` is async.
  *  - Logging is NOT this helper's job — silent graceful-null on every error.
- *  - Paths are resolved absolutely from process.cwd() if relative.
+ *  - Relative paths resolve against `opts.repoRoot` (which itself defaults to
+ *    process.cwd()); an explicit ABSOLUTE path always wins over the root.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -32,9 +33,16 @@ import { scanBacklog, DEFAULT_BACKLOG_LIMIT } from './backlog-scan.mjs';
  * null/[] value to the Signals object.
  *
  * @param {object} [opts]
- * @param {string} [opts.statePath]      — defaults to '.claude/STATE.md'
- * @param {string} [opts.sessionsPath]   — defaults to '.orchestrator/metrics/sessions.jsonl'
- * @param {string} [opts.lockPath]       — defaults to '.orchestrator/bootstrap.lock'
+ * @param {string} [opts.repoRoot]       — absolute project root every relative
+ *   path below resolves against, and the root forwarded to `scanBacklog`.
+ *   Defaults to `process.cwd()`. Without it (#1071) a caller running from a
+ *   worktree or a subdirectory silently read a DIFFERENT repo's STATE.md and
+ *   sessions.jsonl than the one it was reporting on — measured as
+ *   `recentSessions: []` against a checkout holding 245 session records.
+ *   An explicit absolute `statePath`/`sessionsPath`/`lockPath` still wins.
+ * @param {string} [opts.statePath]      — defaults to '<repoRoot>/.claude/STATE.md'
+ * @param {string} [opts.sessionsPath]   — defaults to '<repoRoot>/.orchestrator/metrics/sessions.jsonl'
+ * @param {string} [opts.lockPath]       — defaults to '<repoRoot>/.orchestrator/bootstrap.lock'
  * @param {Array}  [opts.learnings]      — pre-surfaced top-N learnings; defaults to []
  * @param {number} [opts.backlogLimit]   — passed to scanBacklog; defaults to
  *   `DEFAULT_BACKLOG_LIMIT` from backlog-scan.mjs (never a local copy of that
@@ -46,15 +54,24 @@ import { scanBacklog, DEFAULT_BACKLOG_LIMIT } from './backlog-scan.mjs';
  * @returns {Promise<import('./mode-selector.mjs').Signals>}
  */
 export async function buildLiveSignals(opts = {}) {
+  const repoRoot =
+    typeof opts.repoRoot === 'string' && opts.repoRoot.length > 0
+      ? opts.repoRoot
+      : process.cwd();
+  // `resolve(root, p)` returns `p` unchanged when `p` is absolute — explicit
+  // per-file overrides therefore keep precedence over repoRoot.
   const statePath = resolve(
+    repoRoot,
     typeof opts.statePath === 'string' ? opts.statePath : '.claude/STATE.md'
   );
   const sessionsPath = resolve(
+    repoRoot,
     typeof opts.sessionsPath === 'string'
       ? opts.sessionsPath
       : '.orchestrator/metrics/sessions.jsonl'
   );
   const lockPath = resolve(
+    repoRoot,
     typeof opts.lockPath === 'string' ? opts.lockPath : '.orchestrator/bootstrap.lock'
   );
   const learnings = Array.isArray(opts.learnings) ? opts.learnings : [];
@@ -137,7 +154,9 @@ export async function buildLiveSignals(opts = {}) {
   let backlog = null;
 
   try {
-    backlog = await _scan({ limit: backlogLimit });
+    // `repoRoot` is forwarded so VCS detection and the `-R` host-pinning spec
+    // inside scanBacklog answer about the SAME repo the signals describe.
+    backlog = await _scan({ limit: backlogLimit, repoRoot });
   } catch {
     // Branch 6: scanBacklog threw — backlog stays null
   }

package/scripts/lib/ci-status-banner.mjs

@@ -47,6 +47,128 @@ async function execWithTimeout(cmd, args, opts = {}) {
   ]);
 }
 
+/** C0 controls plus DEL — matching them is the POINT, hence the disable. */
+// eslint-disable-next-line no-control-regex
+const CONTROL_BYTE_RE = /[\u0000-\u001f\u007f]/g;
+
+/**
+ * Replace every C0/DEL control byte with its printable `\uXXXX` escape.
+ *
+ * `JSON.stringify` covers the payload preview, but NOT `SyntaxError.message` —
+ * V8 quotes the offending input INTO that message verbatim, so an ANSI/CR
+ * payload reached the operator's terminal through the error text even after
+ * the preview was escaped. Both halves go through here.
+ *
+ * @param {unknown} text
+ * @returns {string}
+ */
+function escapeControlBytes(text) {
+  return String(text).replace(
+    CONTROL_BYTE_RE,
+    (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`,
+  );
+}
+
+/**
+ * Name a parsed JSON value's type WITHOUT quoting any of its content.
+ *
+ * @param {unknown} value
+ * @returns {'null'|'array'|'object'|'string'|'number'|'boolean'|'undefined'}
+ */
+function jsonTypeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return /** @type {any} */ (typeof value);
+}
+
+/**
+ * Parse CLI stdout as JSON, degrading an unparseable payload onto this module's
+ * documented failure channel instead of a bare `SyntaxError` (CWE-502).
+ *
+ * The throw IS that channel, not an escape from it: every call site runs under
+ * `checkCiStatus`'s outer catch, whose comment already names "unparseable
+ * output" as a case it converts to `console.warn` + `null`. Measured
+ * 2026-08-28 at 30940cb, BEFORE this helper existed: an HTML login page from
+ * `gh repo view`, a literal `null`, and an empty `glab` stdout ALL already
+ * returned `null` with a warn — nothing crashed, and
+ * `tests/lib/ci-status-banner.test.mjs` § "error containment" pinned it. So
+ * this does not fix a crash — the outer catch already turned non-JSON output
+ * into a warn + `null`. The rule this helper closes is lexical
+ * (`json-parse-untrusted-input`, see below), not a crash it prevents.
+ *
+ * What it does fix is the message. The raw parse error (`Unexpected token
+ * '<'`) named neither the CLI nor the request, and this banner spawns four
+ * different subprocesses — an operator reading that line at session-start
+ * could not tell which one returned garbage, which is the same
+ * "could not read looks like nothing to report" class #1022/#1039 attacked.
+ * Guarding at the parse also satisfies the `json-parse-untrusted-input` rule,
+ * which keys on a LEXICALLY enclosing try/catch and cannot see the outer one.
+ *
+ * Ceiling (BV-004): the payload preview is clamped to 120 characters. An
+ * unbounded one would bury the session-start banner it is printed beside — a
+ * paginated HTML error page is the realistic worst case. Revisit if a CLI
+ * starts emitting a diagnostic that needs more than one line to identify.
+ *
+ * The preview is emitted through `JSON.stringify`, not raw. It comes from a
+ * subprocess whose stdout this module does not control and lands in a
+ * `console.warn` beside the session-start banner: a payload carrying ANSI
+ * escapes, a `\r`, or a bare newline could otherwise repaint or overwrite the
+ * lines around it. `JSON.stringify` escapes every control byte and quotes the
+ * result, so the preview stays exactly one line of printable text.
+ *
+ * `expect` closes the second half of the same gap: valid JSON of the WRONG
+ * SHAPE parsed fine and escaped this named channel entirely. Measured
+ * 2026-08-28 at 7daa3d2 — a `gh repo view` that printed `null` reached
+ * `const { nameWithOwner } = …` and threw a bare
+ * `TypeError: Cannot destructure property 'nameWithOwner' of 'null'`, which
+ * names neither the CLI nor the request; a `glab api …/pipelines` that printed
+ * `null` was swallowed by `!Array.isArray(pipelines) → return null`, silent.
+ * Both now fail as the SAME named error the parse failure produces.
+ *
+ * @param {string} stdout  Raw child-process stdout (untrusted)
+ * @param {string} label   The command that produced it, for the failure message
+ * @param {'object'|'array'} [expect]  Required shape; omit to accept any JSON
+ * @returns {unknown} The parsed value
+ * @throws {Error} Named parse/shape failure carrying a bounded payload preview
+ */
+function parseCliJson(stdout, label, expect) {
+  const raw = String(stdout ?? '');
+  // Bounded (BV-004: 120 chars — a paginated HTML error page is the realistic
+  // worst case) AND escaped, so it can never break the line it is printed on.
+  const preview = raw.trim().slice(0, 120);
+  const shown = preview
+    ? `got: ${escapeControlBytes(JSON.stringify(preview))}`
+    : 'got: (empty stdout)';
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const reason = escapeControlBytes(err instanceof Error ? err.message : String(err));
+    // `cause` preserves the original for a debugger; the reason is ALSO
+    // inlined into the message because the outer catch reads `err.message`
+    // only — a cause-only wrapper would lose it on the operator-facing line.
+    throw new Error(
+      `${label} returned unparseable JSON (${reason}) — ${shown}`,
+      { cause: err },
+    );
+  }
+
+  // A shape mismatch reports the JSON TYPE, never the payload. The parse
+  // succeeded, so the bytes add nothing an operator can act on — and
+  // `tests/lib/ci-status-banner.test.mjs` § "unexpected benign pipeline
+  // metadata" pins that a well-formed-but-wrong-shaped API body must not have
+  // its contents echoed anywhere. A type name carries no body content.
+  const actual = jsonTypeOf(parsed);
+  if (expect === 'array' && actual !== 'array') {
+    throw new Error(`${label} returned JSON of an unexpected shape — expected an array, got ${actual}`);
+  }
+  if (expect === 'object' && actual !== 'object') {
+    throw new Error(`${label} returned JSON of an unexpected shape — expected an object, got ${actual}`);
+  }
+  return parsed;
+}
+
 /**
  * The one failure this probe can produce that the frozen
  * `REMOTE_RESOLUTION_REASONS` set has no member for: the async timeout race
@@ -201,16 +323,17 @@ async function getHeadSha(repoRoot, deps = {}) {
  * @param {string} apiPath
  * @param {string} repoRoot
  * @param {{ execFile?: Function, timeoutMs?: number, repoHost: string }} deps
+ * @param {'object'|'array'} [expect]  Required payload shape (see `parseCliJson`)
  * @returns {Promise<unknown>}
  */
-async function glabApi(apiPath, repoRoot, deps = {}) {
+async function glabApi(apiPath, repoRoot, deps = {}, expect = undefined) {
   const args = ['api', apiPath, '--hostname', deps.repoHost];
   const result = await execWithTimeout(
     'glab',
     args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  return JSON.parse(result.stdout);
+  return parseCliJson(result.stdout, `glab api ${apiPath}`, expect);
 }
 
 /**
@@ -222,9 +345,10 @@ async function glabApi(apiPath, repoRoot, deps = {}) {
  * @param {string} apiPath
  * @param {string} repoRoot
  * @param {{ execFile?: Function, timeoutMs?: number, repoHost?: string }} deps
+ * @param {'object'|'array'} [expect]  Required payload shape (see `parseCliJson`)
  * @returns {Promise<unknown>}
  */
-async function ghApi(apiPath, repoRoot, deps = {}) {
+async function ghApi(apiPath, repoRoot, deps = {}, expect = undefined) {
   const args = ['api', apiPath];
   if (deps.repoHost) args.push('--hostname', deps.repoHost);
   const result = await execWithTimeout(
@@ -232,7 +356,7 @@ async function ghApi(apiPath, repoRoot, deps = {}) {
     args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  return JSON.parse(result.stdout);
+  return parseCliJson(result.stdout, `gh api ${apiPath}`, expect);
 }
 
 /**
@@ -276,14 +400,18 @@ async function checkGitlab(repoRoot, now, deps = {}) {
   const currentSha = await getHeadSha(repoRoot, deps);
   const apiDeps = { ...deps, repoHost: project.host };
   const projectPath = `projects/${project.encodedProjectPath}`;
+  // `'array'` is load-bearing, not decoration: before it, a `glab api` that
+  // returned valid JSON of the wrong shape (`null`, `"ok"`, an object) fell
+  // into `!Array.isArray(pipelines) → return null` — a SILENT no-op an operator
+  // reads as "nothing to report". It now raises the same named error an
+  // unparseable payload does, so the outer catch warns.
   const pipelines = await glabApi(
     `${projectPath}/pipelines?order_by=updated_at&sort=desc&per_page=15`,
     repoRoot,
     apiDeps,
+    'array',
   );
 
-  if (!Array.isArray(pipelines)) return null;
-
   const currentPipeline = pipelines.find((p) => p.sha === currentSha);
 
   if (!currentPipeline) {
@@ -312,6 +440,7 @@ async function checkGitlab(repoRoot, now, deps = {}) {
         `${projectPath}/pipelines/${currentPipeline.id}/jobs`,
         repoRoot,
         apiDeps,
+        'array',
       );
       if (Array.isArray(jobs)) {
         const softFailed = jobs
@@ -379,6 +508,7 @@ async function checkGitlab(repoRoot, now, deps = {}) {
         `${projectPath}/pipelines/${currentPipeline.id}/jobs`,
         repoRoot,
         apiDeps,
+        'array',
       );
       if (Array.isArray(jobs)) {
         const failedJob = jobs.find((j) => j.status === 'failed');
@@ -450,12 +580,22 @@ async function checkGithub(repoRoot, deps = {}) {
     repoViewArgs,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  const { nameWithOwner } = JSON.parse(repoViewResult.stdout);
+  // `'object'` before the destructuring: a `gh repo view` that printed `null`
+  // (or a bare string, or an array) used to throw a bare
+  // `TypeError: Cannot destructure property 'nameWithOwner' of 'null'`, whose
+  // message names neither the CLI nor the request — the exact identification
+  // failure this helper exists to fix.
+  const { nameWithOwner } = parseCliJson(
+    repoViewResult.stdout,
+    `gh ${repoViewArgs.join(' ')}`,
+    'object',
+  );
 
   const data = await ghApi(
     `repos/${nameWithOwner}/commits/HEAD/check-runs`,
     repoRoot,
     deps,
+    'object',
   );
 
   const checkRuns = data.check_runs;
@@ -516,12 +656,19 @@ async function checkGithub(repoRoot, deps = {}) {
  *     or >= 2 remotes with no preference match) — a benign, measured absence
  *   - Required CLI (glab / gh) not in PATH
  *   - Any CLI invocation times out
- *   - JSON parse failure on CLI output
  *
  * Also returns `null`, but with a `console.warn` trace, when the VCS-detection
- * QUERY ITSELF failed (`git` not on PATH, `git remote -v` erroring) or when a
- * present CLI rejected its invocation. `null` alone cannot express "could not
- * read" — see the outer catch and Step 1 for why the warn channel carries it.
+ * QUERY ITSELF failed (`git` not on PATH, `git remote -v` erroring), when a
+ * present CLI rejected its invocation, or when a CLI returned output this
+ * module could not parse (see {@link parseCliJson}). `null` alone cannot
+ * express "could not read" — see the outer catch and Step 1 for why the warn
+ * channel carries it.
+ *
+ * The unparseable-output case was listed above as SILENT until 2026-08-28.
+ * That was never the behaviour — it has always fallen through to the outer
+ * catch's warn branch (measured at 30940cb). The drift survived because the
+ * one test covering it asserted only the `null` and let the file-wide
+ * `console.warn` spy swallow the rest.
  *
  * @param {{
  *   repoRoot?: string,