session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/autopilot/stall-sampler.mjs

@@ -2,21 +2,39 @@
  * autopilot/stall-sampler.mjs — Stateless progress sampler for STALL_TIMEOUT
  * kill-switch (ADR-364, issue #371).
  *
- * The sampler reads `autopilot.jsonl` mtime as the progress marker: the
- * autopilot loop writes one record per session atomically (tmp+rename), so the
- * file mtime advances exactly when the loop makes progress. No false-positive
- * churn from in-place writes, no need to parse JSON, microsecond precision.
+ * PROGRESS MARKER PRECEDENCE (HR-102: a better signal REPLACES a worse one).
  *
- * Stateless — single statSync call per invocation, no side effects, no async.
- * Wire-up to the kill-switch + loop is deferred (see #371 follow-up); this
- * module ships in isolation under the ADR-364 thin-slice MVP.
+ *   1. `session.lock` `last_heartbeat` (schema v2) — advances DURING a run:
+ *      `hooks/on-stop.mjs` refreshes it at every turn-end and
+ *      `hooks/post-tool-batch-wave-signal.mjs` at every tool batch.
+ *   2. `autopilot.jsonl` mtime — the legacy marker, used only when no lock path
+ *      is supplied or the lock is absent/corrupt/timestamp-less.
+ *
+ * The header of this module used to claim `autopilot.jsonl` carries "one record
+ * per session". It does not: `telemetry.mjs` writes ONE record per /autopilot
+ * INVOCATION, and `loop.mjs` calls it exactly twice — once for the dry-run
+ * preview and once AFTER the `for(;;)` loop. So during a real run the mtime the
+ * sampler read belonged to the PREVIOUS autopilot run, typically hours or days
+ * old, and the post-session check fired STALL_TIMEOUT after iteration 1 every
+ * time. The append-once contract is correct and stays; the marker was wrong.
+ *
+ * CEILING (BV-004). The heartbeat only advances while some live session owns the
+ * lock: `updateHeartbeat()` refuses on a session_id mismatch, and a child
+ * `claude -p` spawned while a parent session already holds the lock never
+ * acquires one (`hooks/_lib/lock-bootstrap.mjs` bails on `reason: 'active'`).
+ * In that one invocation shape — the headless driver started FROM a chat
+ * session rather than from a bare shell — the heartbeat freezes and the check
+ * degrades to today's behaviour. Revisit if STALL_TIMEOUT is ever observed
+ * firing on a run whose child session did real work.
+ *
+ * Stateless — at most two sync reads per invocation, no side effects, no async.
  *
  * Exports:
  *   SAMPLE_CADENCE_MS — shared constant (30_000) defining the "fresh" window
  *   sampleProgress(opts) — returns progress descriptor; never throws
  */
 
-import { statSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -32,9 +50,40 @@ export const SAMPLE_CADENCE_MS = 30_000;
 const DEFAULT_AUTOPILOT_JSONL = '.orchestrator/metrics/autopilot.jsonl';
 const DEFAULT_STALL_TIMEOUT_SECONDS = 600;
 const MARKER_SUCCESS = 'autopilot.jsonl:mtime';
+const MARKER_HEARTBEAT = 'session.lock:last_heartbeat';
 const MARKER_MISSING = 'missing';
 const MARKER_INVALID = 'invalid';
 
+/**
+ * Read the live heartbeat timestamp (ms) out of `session.lock`.
+ *
+ * Returns `null` — meaning "fall back to the mtime marker" — for every failure
+ * mode: no path supplied, file absent, unreadable, not JSON, or carrying no
+ * parsable timestamp. A missing measurement is NOT a zero here; conflating the
+ * two would report a stall of `now` seconds the moment the lock is unreadable.
+ *
+ * @param {string} [sessionLockPath]
+ * @returns {number | null}
+ */
+function readHeartbeatMs(sessionLockPath) {
+  if (typeof sessionLockPath !== 'string' || sessionLockPath.length === 0) return null;
+  let lock;
+  try {
+    lock = JSON.parse(readFileSync(sessionLockPath, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (typeof lock !== 'object' || lock === null) return null;
+  // Same precedence `session-lock.mjs` uses on read: a v1 lock has no
+  // `last_heartbeat`, and its `started_at` is the best available stand-in.
+  const raw = typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0
+    ? lock.last_heartbeat
+    : lock.started_at;
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const ms = Date.parse(raw);
+  return Number.isFinite(ms) ? ms : null;
+}
+
 // ---------------------------------------------------------------------------
 // Progress sampler
 // ---------------------------------------------------------------------------
@@ -45,6 +94,10 @@ const MARKER_INVALID = 'invalid';
  * @param {object} [opts]
  * @param {string} [opts.autopilotJsonlPath] — path to autopilot.jsonl (default
  *   '.orchestrator/metrics/autopilot.jsonl').
+ * @param {string} [opts.sessionLockPath] — path to `session.lock`. When supplied
+ *   and readable, its `last_heartbeat` (falling back to `started_at`, the schema
+ *   v1 normalisation `session-lock.mjs` applies on read) REPLACES the mtime
+ *   marker. Omitted → mtime only, which is what every pre-existing caller gets.
  * @param {number} [opts.stallTimeoutSeconds] — kill-switch threshold (default
  *   600). NOT range-clamped here; caller is responsible for bounds.
  * @param {() => number} [opts.nowMs] — wall-clock supplier (default Date.now).
@@ -66,22 +119,26 @@ export function sampleProgress(opts = {}) {
   void _stallTimeoutSeconds;
   const nowMs = typeof opts.nowMs === 'function' ? opts.nowMs : Date.now;
 
-  let mtimeMs;
-  try {
-    const st = statSync(autopilotJsonlPath);
-    mtimeMs = st.mtimeMs;
-  } catch (err) {
-    const marker = err && err.code === 'ENOENT' ? MARKER_MISSING : MARKER_INVALID;
-    return {
-      progressed: false,
-      lastMarker: null,
-      stallSeconds: 0,
-      marker,
-    };
+  let markerMs = readHeartbeatMs(opts.sessionLockPath);
+  let markerName = MARKER_HEARTBEAT;
+
+  if (markerMs === null) {
+    markerName = MARKER_SUCCESS;
+    try {
+      markerMs = statSync(autopilotJsonlPath).mtimeMs;
+    } catch (err) {
+      const marker = err && err.code === 'ENOENT' ? MARKER_MISSING : MARKER_INVALID;
+      return {
+        progressed: false,
+        lastMarker: null,
+        stallSeconds: 0,
+        marker,
+      };
+    }
   }
 
   const now = nowMs();
-  const deltaMs = now - mtimeMs;
+  const deltaMs = now - markerMs;
   // Clamp negative deltas (clock skew, file mtime in the future) to 0.
   const stallSeconds = Math.max(0, Math.round(deltaMs / 1000));
   // Fresh if within the sample cadence window (also covers the clock-skew
@@ -90,8 +147,8 @@ export function sampleProgress(opts = {}) {
 
   return {
     progressed,
-    lastMarker: mtimeMs,
+    lastMarker: markerMs,
     stallSeconds,
-    marker: MARKER_SUCCESS,
+    marker: markerName,
   };
 }

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

@@ -104,7 +104,8 @@ function degradedResult(reason, detail) {
   // Escape here so BOTH routes are covered at their common exit. Slice first,
   // escape after: the budget is 200 chars of DETAIL, and escaping cannot then
   // leave a cut mid-`\uXXXX`.
-  const tail = detail ? ` — ${escapeControlBytes(String(detail).trim().slice(0, 200))}` : '';
+  const escaped = detail ? escapeControlBytes(String(detail).trim().slice(0, 200)) : '';
+  const tail = escaped ? ` — ${escaped}` : '';
   return {
     severity: 'warn',
     ok: false,
@@ -112,6 +113,14 @@ function degradedResult(reason, detail) {
       `⚠ ci-status: CI status for HEAD could not be determined (${reason}) — ` +
       `state UNKNOWN, not "green".${tail}`,
     degraded: reason,
+    // The SAME already-clamped, already-escaped tail, carried as a field rather
+    // than only inside the banner sentence. Consumers that render their own row
+    // (the release preflight's `ci-green-on-head`) otherwise had to discard the
+    // only distinguishing part: a short sha, an unknown commit and a missing
+    // pipeline all printed the identical `CI status unknown (query-failed)`.
+    // Absent when there is no detail, so `ci.detail` stays falsy exactly where
+    // there is nothing to add.
+    ...(escaped ? { detail: escaped } : {}),
   };
 }
 
@@ -155,6 +164,40 @@ function escapeControlBytes(text) {
   );
 }
 
+/**
+ * Ceiling (BV-004) for one API-supplied fragment embedded in a reading's
+ * operator-facing fields. 60 characters fits every real GitLab pipeline status
+ * and every CI job name this repo has ever produced (`test (macos-latest)` is
+ * 20), and keeps the release-preflight row on one line. Revisit if a platform
+ * starts emitting job names that need more.
+ */
+const API_TEXT_MAX = 60;
+
+/**
+ * Clamp AND control-byte-escape a string that came from a CI platform's API
+ * before it is interpolated into a reading (`details.reason`,
+ * `failingJobName`, `allowFailureJobs`).
+ *
+ * The degraded branch has done this since #1031 ({@link degradedResult}); the
+ * READ branch had not, so a pipeline `status` or job `name` reached the
+ * operator's terminal verbatim — including
+ * `scripts/release.mjs`'s `ci-green-on-head` row, the one line that decides
+ * whether a release proceeds. A status shaped `x\r\u001b[32m✓ ... PASS`
+ * repainted that row green while the row's own verdict stayed `ok:false`.
+ *
+ * Escaped at GENERATION, not at each render: there are four renderers
+ * (session-start banner, release preflight × 2, session-start probes) and only
+ * one producer, so the invariant "a reading carries no raw control bytes"
+ * belongs here. Slice first, escape after — the budget is 60 chars of API
+ * TEXT, and escaping afterwards cannot leave a cut mid-`\uXXXX`.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function sanitizeApiText(value) {
+  return escapeControlBytes(String(value ?? '').trim().slice(0, API_TEXT_MAX));
+}
+
 /**
  * Name a parsed JSON value's type WITHOUT quoting any of its content.
  *
@@ -493,6 +536,246 @@ async function ghApi(apiPath, repoRoot, deps = {}, expect = undefined) {
   return parseCliJson(result.stdout, `gh api ${apiPath}`, expect);
 }
 
+/**
+ * Look up the branch HEAD currently sits on, for pipeline-REF preference.
+ *
+ * **Never throws and never degrades the reading.** A missing branch is not a
+ * failure to report — it only costs the ref preference below, which then falls
+ * back to "every same-sha pipeline is an acceptable candidate", i.e. exactly the
+ * pre-#857 behaviour. Degrading here instead would turn a detached HEAD, a
+ * worktree oddity or a `git` hiccup into a dark banner on a repo whose CI state
+ * is perfectly readable.
+ *
+ * `HEAD` (detached) is reported as "unknown", not as a branch named HEAD.
+ *
+ * @param {string} repoRoot
+ * @param {{ execFile?: Function, timeoutMs?: number }} deps
+ * @returns {Promise<string|undefined>}
+ */
+async function getCurrentBranch(repoRoot, deps = {}) {
+  const gitTimeout = Math.min(2000, deps.timeoutMs ?? 2000);
+  try {
+    const result = await execWithTimeout(
+      'git',
+      ['rev-parse', '--abbrev-ref', 'HEAD'],
+      { cwd: repoRoot, timeoutMs: gitTimeout, execFile: deps.execFile },
+    );
+    const branch = String(result?.stdout ?? '').trim();
+    if (branch === '' || branch === 'HEAD') return undefined;
+    return branch;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Does a pipeline's `ref` name the branch HEAD is on?
+ *
+ * GitLab reports a branch pipeline's ref as the bare branch name (`main`);
+ * `refs/heads/main` is accepted too because nothing in the API contract forbids
+ * the long form. An MR pipeline's ref is `refs/merge-requests/<iid>/head`,
+ * which matches no branch and is therefore never a confident match.
+ *
+ * @param {unknown} ref
+ * @param {string|undefined} branch
+ * @returns {boolean}
+ */
+function refMatchesBranch(ref, branch) {
+  if (!branch || typeof ref !== 'string' || ref === '') return false;
+  return ref === branch || ref === `refs/heads/${branch}`;
+}
+
+/**
+ * Does a pipeline's `ref` name a merge-request HEAD (`detached`) pipeline?
+ *
+ * GitLab spells it `refs/merge-requests/<iid>/head` — the DETACHED pipeline,
+ * which runs the MR source commit itself. The merged-results counterpart
+ * (`refs/merge-requests/<iid>/merge`) runs a synthetic merge commit whose sha is
+ * NOT the local HEAD, so it can never reach a same-sha candidate tier and is
+ * deliberately not matched here.
+ *
+ * @param {unknown} ref
+ * @returns {boolean}
+ */
+function isMergeRequestHeadRef(ref) {
+  return typeof ref === 'string' && /^refs\/merge-requests\/[^/]+\/head$/.test(ref);
+}
+
+/**
+ * Rank a GitLab pipeline status by how ALARMING it is (#857).
+ *
+ * Used only to pick ONE reading out of several pipelines for the SAME commit on
+ * the SAME ref, whose statuses contradict each other — measured on this project
+ * 2026-09-18: 14 of ~86 distinct shas in the last 100 pipelines carry 2-4
+ * pipelines, 7 of them with contradicting statuses (`canceled`+`success`,
+ * `failed`+`success`, …), produced by different `source`s (`push`, `api`,
+ * `merge_request_event`).
+ *
+ * Worst-status-wins is this module's stated fail-toward-visible posture (see
+ * {@link SILENT_QUERY_FAILURES}) applied to disagreement: a `success` beside a
+ * `failed` or a `canceled` cannot establish that the commit is green — the two
+ * runs may have executed different job sets, and which one is "the real one" is
+ * not derivable from the pipeline list. The disagreement itself is published as
+ * evidence (`details.ambiguous` + `details.candidateStatuses`), so the operator
+ * is never left guessing WHY the verdict reads the way it does.
+ *
+ * `failed` outranks `canceled` so a real failure can never be masked by a
+ * cancellation; everything UNSETTLED outranks `success`, because an in-flight
+ * sibling run means the commit's verdict is not settled.
+ *
+ * "Unsettled" is a category, not a leftover bucket. `skipped` and `manual` are
+ * TERMINAL non-failing states — the ordinary shape of a `rules:`-gated or
+ * manual-trigger pipeline — and lumping them in with `running`/`pending` turned
+ * the everyday `success` + `skipped` pair into `unknown /
+ * unrecognised-status-skipped`, where the pre-#857 reading was `green`. They
+ * therefore rank BELOW `success`: they never beat a real reading in either
+ * direction (`success` beside them → green, `failed` beside them → red), while
+ * a LONE `skipped`/`manual` still falls through `checkGitlab`'s tail to
+ * `unknown`, unchanged. Category separation, not a threshold tweak.
+ *
+ * @param {unknown} status
+ * @returns {number} Higher = more alarming
+ */
+function statusSeverity(status) {
+  if (status === 'failed') return 4;
+  if (status === 'canceled') return 3;
+  if (status === 'success') return 1;
+  // Terminal, non-failing, carries no verdict of its own.
+  if (status === 'skipped' || status === 'manual') return 0;
+  // running / pending / created / preparing / waiting_for_resource / scheduled
+  // — and anything unrecognised, which cannot be assumed settled.
+  return 2;
+}
+
+/**
+ * Split every pipeline carrying the queried sha into the candidate set this
+ * reading may speak for, and the foreign-ref remainder it must not (#857).
+ *
+ * Before this, `pipelines.find(p => p.sha === currentSha)` took the most
+ * recently updated row in a 15-row window that MIXES refs (`main`,
+ * `refs/merge-requests/39/head`, a `codex/…` branch — measured 2026-09-18), so
+ * a foreign branch's or an MR's pipeline could silently become the local HEAD's
+ * verdict.
+ *
+ * Preference, first non-empty tier wins:
+ *   1. pipelines whose `ref` names the current branch (the confident match);
+ *   2. pipelines whose ref cannot be judged — no `ref` field, or no branch
+ *      resolved (detached HEAD, `git` unavailable). Judging is impossible, so
+ *      this is the pre-#857 CANDIDATE SET, now resolved worst-status-wins like
+ *      every other tier (a ref-less `success` + `canceled` pair read green
+ *      before #857 and reads red now — the change is deliberate, see
+ *      {@link statusSeverity});
+ *   3. pipelines on an MR HEAD ref ({@link isMergeRequestHeadRef}) carrying the
+ *      queried sha. A repo whose `workflow: rules:` only admit
+ *      `merge_request_event` produces NO branch pipeline at all, so tiers 1-2
+ *      are empty and the pre-tier-3 code reported `pipeline-unmatched-ref` for a
+ *      commit whose verdict was sitting right there. SHA EQUALITY is the
+ *      correctness argument — the ref is only a tie-breaker, and a
+ *      merged-results pipeline runs a DIFFERENT sha, so it cannot reach this
+ *      tier at all. `matchedRef` is reported, so the operator sees which ref
+ *      spoke;
+ *   4. otherwise NOTHING is selected: every same-sha pipeline belongs to a
+ *      genuinely foreign ref (another branch), which the caller reports as
+ *      `unknown` with its own reason rather than adopting.
+ *
+ * `foreign` is EVERY same-sha row outside the selected tier — on every branch,
+ * not only on tier 4 (#1390). It used to be `[]` whenever a tier matched, so a
+ * same-sha `failed` on another ref vanished with no trace behind a `green`
+ * reading. The ref preference still decides the verdict; the rows it set aside
+ * are handed back so the caller can publish them as evidence
+ * ({@link candidateEvidence} `droppedStatuses`). Linear `includes` scan over
+ * at most the 15-row API window — revisit if `per_page` grows past ~200.
+ *
+ * @param {Array<any>} pipelines
+ * @param {string} sha
+ * @param {string|undefined} branch
+ * @returns {{ selected: Array<any>, foreign: Array<any> }}
+ */
+function selectShaPipelines(pipelines, sha, branch) {
+  const sameSha = pipelines.filter((p) => p && p.sha === sha);
+  const split = (selected) => ({
+    selected,
+    foreign: sameSha.filter((p) => !selected.includes(p)),
+  });
+
+  const onBranch = sameSha.filter((p) => refMatchesBranch(p.ref, branch));
+  if (onBranch.length > 0) return split(onBranch);
+
+  const unjudgeable = sameSha.filter(
+    (p) => !branch || typeof p.ref !== 'string' || p.ref === '',
+  );
+  if (unjudgeable.length > 0) return split(unjudgeable);
+
+  const mrHead = sameSha.filter((p) => isMergeRequestHeadRef(p.ref));
+  if (mrHead.length > 0) return split(mrHead);
+
+  return split([]);
+}
+
+/**
+ * Pick the pipeline a reading speaks for: the most alarming of the candidates,
+ * ties resolved by the API's own `updated_at desc` ordering (first wins).
+ *
+ * @param {Array<any>} candidates  Non-empty
+ * @returns {any}
+ */
+function worstPipeline(candidates) {
+  let worst = candidates[0];
+  for (const p of candidates) {
+    if (statusSeverity(p.status) > statusSeverity(worst.status)) worst = p;
+  }
+  return worst;
+}
+
+/**
+ * ADDITIVE evidence fields (#857) describing how a reading was chosen.
+ *
+ * Additive by hard constraint: the `status` vocabulary stays
+ * `green | red | unknown`, because `dispatcher/rank.mjs` and
+ * `autonomy/suitability.mjs` treat only the literal `'red'` as bad and the
+ * session-start renderer prints nothing for a status string it does not know.
+ * So ambiguity is published BESIDE the verdict, never as a new verdict.
+ *
+ *   - `matchedRef`       the chosen pipeline's ref (present whenever the API
+ *                        supplied one), so the operator can see WHICH ref the
+ *                        verdict speaks for.
+ *   - `candidateCount`   number of same-sha candidates — only when > 1, so an
+ *                        ordinary one-pipeline reading is byte-identical to
+ *                        before.
+ *   - `candidateStatuses` their statuses, in API order, same gate.
+ *   - `ambiguous`        `true` only when those statuses DISAGREE.
+ *   - `droppedCount`     number of same-sha pipelines the ref preference SET
+ *                        ASIDE (another branch, an MR HEAD beside a branch
+ *                        match, a ref-less row beside a judged one) — only when
+ *                        > 0 (#1390). Without it a `failed` run of the very
+ *                        commit on another ref disappeared behind a `green`.
+ *   - `droppedStatuses`  their statuses, in API order, same gate. Evidence
+ *                        only: they never enter the verdict or `ambiguous`,
+ *                        which stay the #857 ref-preference result.
+ *
+ * @param {Array<any>} selected
+ * @param {any} chosen
+ * @param {Array<any>} dropped  Same-sha rows outside the selected tier
+ * @returns {{ matchedRef?: string, candidateCount?: number, candidateStatuses?: string[], ambiguous?: true, droppedCount?: number, droppedStatuses?: string[] }}
+ */
+function candidateEvidence(selected, chosen, dropped) {
+  /** @type {any} */
+  const out = {};
+  if (typeof chosen?.ref === 'string' && chosen.ref !== '') {
+    out.matchedRef = sanitizeApiText(chosen.ref);
+  }
+  if (selected.length > 1) {
+    out.candidateCount = selected.length;
+    out.candidateStatuses = selected.map((p) => sanitizeApiText(p.status));
+    if (new Set(out.candidateStatuses).size > 1) out.ambiguous = true;
+  }
+  if (dropped.length > 0) {
+    out.droppedCount = dropped.length;
+    out.droppedStatuses = dropped.map((p) => sanitizeApiText(p.status));
+  }
+  return out;
+}
+
 /**
  * Compute age in whole days between an ISO date string and `now`.
  *
@@ -534,6 +817,10 @@ async function checkGitlab(repoRoot, now, deps = {}) {
   // #1332: an explicit `deps.sha` (validated full hex SHA, see checkCiStatus)
   // replaces the local HEAD lookup — the caller asks about a NAMED commit.
   const currentSha = deps.sha ?? (await getHeadSha(repoRoot, deps));
+  // #857 ref preference — resolved alongside the sha, and best-effort: an
+  // unresolvable branch costs the preference, never the reading. See
+  // {@link getCurrentBranch}.
+  const branch = await getCurrentBranch(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
@@ -548,9 +835,32 @@ async function checkGitlab(repoRoot, now, deps = {}) {
     'array',
   );
 
-  const currentPipeline = pipelines.find((p) => p.sha === currentSha);
+  // #857: the window mixes refs and carries duplicate pipelines per commit, so
+  // the reading is CHOSEN (ref preference, then worst-status-wins), never
+  // `.find()`-ed off the most recently updated row.
+  const { selected, foreign } = selectShaPipelines(pipelines, currentSha, branch);
+
+  if (selected.length === 0 && foreign.length > 0) {
+    // Pipelines EXIST for this commit, but every one of them belongs to a
+    // foreign ref (another branch, or `refs/merge-requests/<iid>/head`).
+    // Adopting one would let an MR's or a foreign branch's verdict stand in for
+    // the local HEAD's; claiming "no pipeline" would hide that runs exist. So:
+    // `unknown`, with a reason that names the actual situation. The status
+    // vocabulary is unchanged — the finding is delivered as a REASON.
+    return {
+      status: 'unknown',
+      ok: false,
+      details: {
+        currentPipelineId: null,
+        cliUsed: 'glab',
+        reason: 'pipeline-unmatched-ref',
+        candidateCount: foreign.length,
+        candidateStatuses: foreign.map((p) => sanitizeApiText(p.status)),
+      },
+    };
+  }
 
-  if (!currentPipeline) {
+  if (selected.length === 0) {
     return {
       status: 'unknown',
       ok: false,
@@ -562,6 +872,8 @@ async function checkGitlab(repoRoot, now, deps = {}) {
     };
   }
 
+  const currentPipeline = worstPipeline(selected);
+  const evidence = candidateEvidence(selected, currentPipeline, foreign);
   const pipelineStatus = currentPipeline.status;
 
   if (pipelineStatus === 'success') {
@@ -581,7 +893,7 @@ async function checkGitlab(repoRoot, now, deps = {}) {
       if (Array.isArray(jobs)) {
         const softFailed = jobs
           .filter((j) => j.status === 'failed' && j.allow_failure === true)
-          .map((j) => j.name);
+          .map((j) => sanitizeApiText(j.name));
         if (softFailed.length > 0) allowFailureJobs = softFailed;
       }
     } catch {
@@ -595,6 +907,7 @@ async function checkGitlab(repoRoot, now, deps = {}) {
       details: {
         currentPipelineId: currentPipeline.id,
         cliUsed: 'glab',
+        ...evidence,
       },
     };
   }
@@ -606,33 +919,50 @@ async function checkGitlab(repoRoot, now, deps = {}) {
       details: {
         currentPipelineId: currentPipeline.id,
         cliUsed: 'glab',
-        reason: `pipeline-${pipelineStatus}`,
+        reason: `pipeline-${sanitizeApiText(pipelineStatus)}`,
+        ...evidence,
       },
     };
   }
 
   if (pipelineStatus === 'failed' || pipelineStatus === 'canceled') {
     // Find the last green pipeline in the history.
+    //
+    // #857: the look-back slice EXCLUDES every row carrying the queried sha, not
+    // just the chosen one. Pipelines are NOT one-per-commit on this project —
+    // measured 2026-09-18, 14 of ~86 distinct shas in the last 100 pipelines
+    // carry 2-4 — so a `success` duplicate of the very commit being reported red
+    // used to be found here and named as its own `lastGreen`. Reproduced on
+    // `52ae12f1` (a `canceled` push pipeline + a `success` api pipeline for the
+    // same commit): status `red`, `lastGreen.sha` === HEAD.
     const currentIdx = pipelines.indexOf(currentPipeline);
-    const rest = pipelines.slice(currentIdx + 1);
+    const rest = pipelines.slice(currentIdx + 1).filter((p) => p && p.sha !== currentSha);
     const lastGreenPipeline = rest.find((p) => p.status === 'success');
 
-    // Count consecutive non-success pipelines from current onwards.
-    let redCount = 1;
+    // The unbroken non-success run from the current pipeline back to the last
+    // green, as ROWS. Same meaning `redCount` always had.
+    const redRun = [currentPipeline];
     for (const p of rest) {
       if (p.status === 'success') break;
-      redCount++;
+      redRun.push(p);
     }
+    const redCount = redRun.length;
 
     let lastGreen;
     if (lastGreenPipeline) {
       const ageDays = ageDaysFrom(lastGreenPipeline.created_at, now);
-      // Approximate commit distance: redCount is the number of red pipelines
-      // before reaching the last green (pipelines are one-per-commit on this project).
       lastGreen = {
         sha: lastGreenPipeline.sha,
         pipelineId: lastGreenPipeline.id,
-        ageCommits: redCount,
+        // Commit distance, counted over DISTINCT shas in the red run. The old
+        // value was the ROW count under a comment asserting "pipelines are
+        // one-per-commit on this project" — measured false at 16%, so the
+        // distance was overstated whenever a commit had been re-run.
+        ageCommits: new Set(redRun.map((p) => p.sha)).size,
+        // The row count is kept under its own name rather than dropped: it is
+        // what `redCount` reports, and "3 red pipelines over 2 commits" is a
+        // different (and also useful) statement from either number alone.
+        agePipelines: redCount,
         ageDays,
       };
     }
@@ -648,7 +978,7 @@ async function checkGitlab(repoRoot, now, deps = {}) {
       );
       if (Array.isArray(jobs)) {
         const failedJob = jobs.find((j) => j.status === 'failed');
-        failingJobName = failedJob ? failedJob.name : undefined;
+        failingJobName = failedJob ? sanitizeApiText(failedJob.name) : undefined;
       }
     } catch {
       // Non-fatal — we still report red status without job name.
@@ -663,6 +993,15 @@ async function checkGitlab(repoRoot, now, deps = {}) {
       details: {
         currentPipelineId: currentPipeline.id,
         cliUsed: 'glab',
+        // A user-cancelled pipeline printed `🚨 CI RED on HEAD` indistinguishably
+        // from a real failure. The STATUS stays `red` on purpose (no consumer
+        // churn — `dispatcher/rank.mjs` and `autonomy/suitability.mjs` key on the
+        // literal `'red'`), and the distinction is delivered through the reason
+        // both the banner and the release-preflight row already interpolate.
+        // Named like the `pipeline-running` / `pipeline-pending` reasons above;
+        // `failed` keeps carrying no reason — its detail is `failingJobName`.
+        ...(pipelineStatus === 'canceled' ? { reason: 'pipeline-canceled' } : {}),
+        ...evidence,
       },
     };
   }
@@ -674,7 +1013,8 @@ async function checkGitlab(repoRoot, now, deps = {}) {
     details: {
       currentPipelineId: currentPipeline.id,
       cliUsed: 'glab',
-      reason: `unrecognised-status-${pipelineStatus}`,
+      reason: `unrecognised-status-${sanitizeApiText(pipelineStatus)}`,
+      ...evidence,
     },
   };
 }
@@ -757,7 +1097,7 @@ async function checkGithub(repoRoot, deps = {}) {
     return {
       status: 'red',
       ok: false,
-      failingJobName: failedRun.name,
+      failingJobName: sanitizeApiText(failedRun.name),
       details: {
         cliUsed: 'gh',
         reason: 'lastGreen-not-implemented-for-github',
@@ -835,7 +1175,13 @@ async function checkGithub(repoRoot, deps = {}) {
  * } | {
  *   status: 'green'|'red'|'unknown',
  *   ok: boolean,
- *   lastGreen?: { sha: string, pipelineId: number, ageCommits: number, ageDays: number|null },
+ *   lastGreen?: {
+ *     sha: string,
+ *     pipelineId: number,
+ *     ageCommits: number,
+ *     agePipelines?: number,
+ *     ageDays: number|null,
+ *   },
  *   redCount?: number,
  *   failingJobName?: string,
  *   details: {
@@ -843,8 +1189,22 @@ async function checkGithub(repoRoot, deps = {}) {
  *     cliUsed: 'glab'|'gh',
  *     reason?: string,
  *     error?: string,
+ *     matchedRef?: string,
+ *     candidateCount?: number,
+ *     candidateStatuses?: string[],
+ *     ambiguous?: true,
+ *     droppedCount?: number,
+ *     droppedStatuses?: string[],
  *   },
  * }>}
+ *
+ * The `status` vocabulary is FROZEN at `green | red | unknown` (#857/#856): the
+ * #857 "several contradicting pipelines" and "only foreign-ref pipelines"
+ * findings — and the #1390 "same-sha rows the ref preference set aside"
+ * (`droppedCount`/`droppedStatuses`) — are delivered through ADDITIVE `details`
+ * fields and `details.reason`,
+ * never as a new status value — consumers fail open on an unknown status string
+ * and the session-start renderer prints nothing for one.
  */
 export async function checkCiStatus(opts = {}, deps = {}) {
   const {