session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/session-registry.mjs

@@ -19,9 +19,18 @@
  *     started_at, last_heartbeat, status ('active'|'wave'|'idle'),
  *     current_wave, host_class, mode (Epic #583 W2-I3),
  *     role ('navigator'|null, optional, #1462 — display only, never ownership;
- *           set by heartbeat(patch.role), NOT by registerSelf)
+ *           set by heartbeat(patch.role), NOT by registerSelf),
+ *     session_root (absolute realpath|null, optional, #1605 — where THIS
+ *           session's `.orchestrator/session.lock` and `current-session.json`
+ *           live; set by registerSelf),
+ *     work_root (absolute realpath|null, optional, #1605 — the working copy the
+ *           session works in; set by registerSelf, refreshed by
+ *           heartbeat(patch.workRoot) at every turn end)
  *   }
  *
+ * `session_root` / `work_root` are additive: readers that predate #1605 ignore
+ * them, and `_validEntry` does not require them.
+ *
  * Schema v2 (Epic #583, W2-I3): `mode` field added so the exclusivity-matrix
  * can classify cross-repo registry entries correctly. Without it, every
  * registry-sourced peer was bucketed as `mode='session'` → classifyMode threw
@@ -38,7 +47,7 @@ import crypto from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import { digestSha256 } from './crypto-digest-utils.mjs';
 
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, chmodSync, mkdirSync, realpathSync } from 'node:fs';
 
 import { utcTimestamp, appendJsonl } from './common.mjs';
 import { resolvePrivateConfigDir } from './config/private-config-dir.mjs';
@@ -89,14 +98,41 @@ function entryPath(sessionId) {
 // ---------------------------------------------------------------------------
 
 /**
- * Stable SHA-256 hex of an absolute path. Used so registry entries can be
+ * Stable SHA-256 hex of a canonical repo path. Used so registry entries can be
  * correlated by repo without exposing local filesystem layout.
  */
 export function repoPathHash(absPath) {
   if (typeof absPath !== 'string' || absPath.length === 0) {
     throw new TypeError('repoPathHash: absPath must be a non-empty string');
   }
-  return digestSha256(path.resolve(absPath));
+  return digestSha256(resolveRepoPath(absPath));
+}
+
+/** Resolve symlinks and on-disk casing; unavailable paths keep their old identity. */
+function resolveRepoPath(repoPath) {
+  const resolved = path.resolve(repoPath);
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+/**
+ * Canonical spelling of an optional absolute root for `session_root` /
+ * `work_root` (#1605): `null` when absent, the realpath otherwise.
+ *
+ * @param {unknown} value
+ * @param {string} name  option name for the error message
+ * @returns {string|null}
+ * @throws {TypeError} when `value` is neither nullish nor an absolute path string
+ */
+function _optionalRoot(value, name) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'string' || !path.isAbsolute(value)) {
+    throw new TypeError(`${name} must be an absolute path when provided`);
+  }
+  return resolveRepoPath(value);
 }
 
 function _assertSessionId(sessionId) {
@@ -110,9 +146,11 @@ function _assertSessionId(sessionId) {
 }
 
 async function _writeJsonAtomic(filePath, data, { mode = 0o600 } = {}) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  // 0o700: the registry sits in the private config dir; a bare mkdir leaves it
+  // 0777 under umask 000 and breaks the owner-policy check beside it (#1629).
+  await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
   const tmp = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
-  await fs.writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  await fs.writeFile(tmp, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', mode }); // no 0666 window (#1632)
   await fs.rename(tmp, filePath);
   try { await fs.chmod(filePath, mode); } catch { /* best effort */ }
 }
@@ -208,8 +246,10 @@ export function logSweepEvent({ event, session_id, error }) {
   }) + '\n';
   try {
     const logPath = sweepLogPath();
-    try { mkdirSync(path.dirname(logPath), { recursive: true }); } catch { /* best effort */ }
-    appendFileSync(logPath, line, 'utf8');
+    try { mkdirSync(path.dirname(logPath), { recursive: true, mode: 0o700 }); } catch { /* best effort */ } // #1629
+    appendFileSync(logPath, line, { encoding: 'utf8', mode: 0o600 }); // #1632
+    // `mode` applies on creation only: tighten a loose pre-existing log too (#1636).
+    try { chmodSync(logPath, 0o600); } catch { /* best effort */ }
   } catch { /* last-resort silent no-op — never let log-write cascade */ }
 }
 
@@ -225,6 +265,10 @@ export function logSweepEvent({ event, session_id, error }) {
  * @param {number} [opts.pid] — defaults to process.pid
  * @param {string} [opts.status] — 'active' | 'wave' | 'idle' (default 'active')
  * @param {number} [opts.currentWave] — default 0
+ * @param {string} [opts.sessionRoot] — absolute root holding this session's
+ *   `session.lock` / `current-session.json` (#1605); stored as `session_root`.
+ * @param {string} [opts.workRoot] — absolute working copy the session works in
+ *   (#1605); stored as `work_root`.
  * @param {string} [opts.mode] — session mode (e.g., 'deep', 'feature', 'housekeeping').
  *   Schema v2 (Epic #583, W2-I3): when present, propagated into the entry so
  *   discovery + exclusivity-matrix classification work for cross-repo peers.
@@ -248,6 +292,8 @@ export async function registerSelf(opts) {
   if (opts.semanticSessionId !== undefined && opts.semanticSessionId !== null && typeof opts.semanticSessionId !== 'string') {
     throw new TypeError('registerSelf: semanticSessionId must be a string when provided');
   }
+  const sessionRoot = _optionalRoot(opts.sessionRoot, 'registerSelf: sessionRoot');
+  const workRoot = _optionalRoot(opts.workRoot, 'registerSelf: workRoot');
   const now = utcTimestamp();
   const entry = {
     session_id: sessionId,
@@ -255,7 +301,7 @@ export async function registerSelf(opts) {
     pid: opts.pid ?? process.pid,
     platform: opts.platform ?? null,
     repo_path_hash: repoPathHash(projectRoot),
-    repo_name: path.basename(path.resolve(projectRoot)),
+    repo_name: path.basename(resolveRepoPath(projectRoot)),
     branch: opts.branch ?? null,
     started_at: now,
     last_heartbeat: now,
@@ -263,6 +309,8 @@ export async function registerSelf(opts) {
     current_wave: opts.currentWave ?? 0,
     host_class: opts.hostClass ?? null,
     mode: opts.mode ?? null,
+    session_root: sessionRoot,
+    work_root: workRoot,
   };
   await _writeJsonAtomic(entryPath(sessionId), entry);
   return entry;
@@ -277,16 +325,20 @@ export const REGISTRY_ROLES = Object.freeze(['navigator']);
  *
  * `patch.role`: `undefined` keeps the stored role, `null` clears it, a member
  * of `REGISTRY_ROLES` sets it. Anything else throws before the file is touched.
+ * `patch.workRoot` (#1605): `undefined` keeps the stored `work_root`, an
+ * absolute path replaces it (stored as its realpath).
  *
  * @param {string} sessionId
- * @param {{ status?: string, currentWave?: number, role?: string|null }} [patch]
+ * @param {{ status?: string, currentWave?: number, role?: string|null, workRoot?: string }} [patch]
  * @returns {Promise<object|null>} the updated entry, or null if none exists.
- * @throws {TypeError} when `patch.role` is neither undefined, null, nor a REGISTRY_ROLES member.
+ * @throws {TypeError} when `patch.role` is neither undefined, null, nor a REGISTRY_ROLES
+ *   member, or `patch.workRoot` is neither undefined nor an absolute path.
  */
 export async function heartbeat(sessionId, patch = {}) {
   if (patch.role !== undefined && patch.role !== null && !REGISTRY_ROLES.includes(patch.role)) {
     throw new TypeError('heartbeat: role must be "navigator" or null');
   }
+  const workRoot = patch.workRoot === undefined ? undefined : _optionalRoot(patch.workRoot, 'heartbeat: workRoot');
   const file = entryPath(sessionId);
   const existing = await _readJsonSafe(file);
   if (!_validEntry(existing)) return null;
@@ -296,6 +348,7 @@ export async function heartbeat(sessionId, patch = {}) {
     ...(patch.status !== undefined ? { status: patch.status } : {}),
     ...(patch.currentWave !== undefined ? { current_wave: patch.currentWave } : {}),
     ...(patch.role !== undefined ? { role: patch.role } : {}),
+    ...(workRoot !== undefined && workRoot !== null ? { work_root: workRoot } : {}),
   };
   await _writeJsonAtomic(file, updated);
   return updated;
@@ -353,6 +406,26 @@ export async function detectPeers({ sessionId, freshnessMin = 15 } = {}) {
   });
 }
 
+/**
+ * Count registry entries whose `started_at` lies within the last `windowMin`
+ * minutes — the start-wave signal (#1650). Pure: pass the entries you already
+ * hold. Passing detectPeers() output is complete as long as `windowMin` is at
+ * most detectPeers' `freshnessMin` (15): registerSelf() writes `started_at`
+ * and `last_heartbeat` with the same stamp, so every entry started inside the
+ * window is still heartbeat-fresh. Self must already be excluded by the caller.
+ * Unparseable or future `started_at` never counts (`_ageMinutes` → Infinity).
+ *
+ * @param {object[]} entries  Registry entries (e.g. detectPeers() result)
+ * @param {object} [opts]
+ * @param {number} [opts.windowMin=5]
+ * @param {number} [opts.now]  ms-since-epoch (test seam)
+ * @returns {number}
+ */
+export function countRecentStarts(entries, { windowMin = 5, now = Date.now() } = {}) {
+  if (!Array.isArray(entries)) return 0;
+  return entries.filter((e) => e && _ageMinutes(e.started_at, now) <= windowMin).length;
+}
+
 /**
  * Remove heartbeat entries older than `thresholdMin` minutes. Appends one
  * JSONL line per removal to sweepLogPath() for observability.
@@ -402,7 +475,7 @@ export async function sweepZombies({ thresholdMin = 60, now = Date.now() } = {})
             file: name,
             age_minutes: Number.isFinite(age) ? Math.round(age) : null,
             reason: valid ? 'stale-heartbeat' : 'malformed-entry',
-          });
+          }, { mode: 0o600 }); // #1632
           logged += 1;
         } catch { /* log best-effort */ }
       } catch { /* file might have been removed by another sweep */ }

package/scripts/lib/session-schema/constants.mjs

@@ -45,6 +45,8 @@ export const SESSION_KEY_ALIASES = Object.freeze({
   issues_filed: 'issues_created',
   issues_planned: 'planned_issues',
   files_changed: 'total_files_changed',
+  // No `agents_total` alias (#1699): session-record-repair.mjs lets the agent_summary sum win over it
+  // and flags a disagreement; an alias here would make normalize/migrate prefer agents_total instead.
   snapshots: 'snapshots_created',
   learnings: 'learnings_added',
   waves_total: 'total_waves',
@@ -252,6 +254,13 @@ export const OPTIONAL_FIELDS = Object.freeze([
   // 2026-10-01), so the counters say which of the two it is.
   'cost_records_priced',
   'cost_records_total',
+  // #1659 — `[{ tree, start_ref }]`: the work trees this session committed in,
+  // from its own `orchestrator.session.work_tree` events. Written by
+  // scripts/emit-session.mjs only when it adds something beyond
+  // `session_start_ref` (≥2 trees, or one tree that is not the own checkout).
+  // Shape (absolute `tree`, full hex `start_ref`) is enforced at that writer —
+  // malformed entries are dropped with a WARN — not in validateSession().
+  'session_work_trees',
   // #1470 Pkt 4/6 — what `total_cost_usd` is and which price table produced
   // the cost fields. Merged by scripts/emit-session.mjs from
   // scripts/lib/telemetry/pricing.mjs (`COST_BASIS`, `PRICING_TABLE_DATE`):

package/scripts/lib/session-schema/filters.mjs

@@ -34,7 +34,8 @@
  * these helpers only where the window is meant to represent REAL WORK.
  *
  * Exports: isRealSession, filterRealSessions, tailRealSessions,
- *          isCoordinatorDirectHousekeeping
+ *          isCoordinatorDirectHousekeeping, waveAgentCount,
+ *          isCoordinatorDirectWave, normalizeWaveRole
  */
 
 // ---------------------------------------------------------------------------
@@ -111,3 +112,57 @@ export function isCoordinatorDirectHousekeeping(record) {
     waves.every((w) => w?.role === 'Housekeeping' && w?.coordinator_direct === true)
   );
 }
+
+/**
+ * A wave's dispatched-agent count, read defensively across the key spellings
+ * the ledger holds (`/evolve analyze` effective-sizing, #1652): `agent_count`,
+ * else `agents` when it is a number, else the length of `agents` when it is an
+ * array (of descriptions), else `agents_dispatched`, else `agent_count_started`
+ * / its legacy spelling `agents_started` (the only count some waves carry).
+ *
+ * @param {unknown} wave — one entry of a record's `waves`
+ * @returns {number|null} — null when no key carries a count (unmeasured, never 0)
+ */
+export function waveAgentCount(wave) {
+  if (wave === null || typeof wave !== 'object' || Array.isArray(wave)) return null;
+  if (typeof wave.agent_count === 'number') return wave.agent_count;
+  if (typeof wave.agents === 'number') return wave.agents;
+  if (Array.isArray(wave.agents)) return wave.agents.length;
+  if (typeof wave.agents_dispatched === 'number') return wave.agents_dispatched;
+  if (typeof wave.agent_count_started === 'number') return wave.agent_count_started;
+  if (typeof wave.agents_started === 'number') return wave.agents_started;
+  return null;
+}
+
+/**
+ * True when a wave dispatched no agents — flagged `coordinator_direct: true`,
+ * or a measured agent count of 0 without the flag (#1652). The ledger holds
+ * 222 unflagged 0-agent waves (2026-10-17, 249 real records); counting them in
+ * an agents-per-wave ratio drags the average down with waves no agent ran in.
+ * Read side on purpose: it covers the history without rewriting the ledger.
+ * An unmeasured count (`waveAgentCount` → null) is not coordinator-direct.
+ *
+ * @param {unknown} wave — one entry of a record's `waves`
+ * @returns {boolean}
+ */
+export function isCoordinatorDirectWave(wave) {
+  if (wave === null || typeof wave !== 'object' || Array.isArray(wave)) return false;
+  return wave.coordinator_direct === true || waveAgentCount(wave) === 0;
+}
+
+/**
+ * Grouping key for a wave role, case- and separator-insensitive (#1652): the
+ * ledger spells one role several ways (`Finalization`/`finalization`,
+ * `Express-Path`/`Express Path`). Lowercases and collapses runs of spaces,
+ * underscores and hyphens to one `-`. Ceiling: distinct words stay distinct —
+ * `Express` and `Express-Path` remain two keys; merging synonyms needs an
+ * alias table, revisit when a consumer has to report them as one role.
+ *
+ * @param {unknown} role
+ * @returns {string|null} — null for a non-string or blank role
+ */
+export function normalizeWaveRole(role) {
+  if (typeof role !== 'string') return null;
+  const key = role.trim().toLowerCase().replace(/[\s_-]+/g, '-').replace(/^-+|-+$/g, '');
+  return key.length > 0 ? key : null;
+}

package/scripts/lib/session-schema/validator.mjs

@@ -37,6 +37,11 @@ const COST_BASES = Object.freeze(['api-list-equivalent']);
 /** `pricing_table_date` (#1470 Pkt 6): a calendar date, `YYYY-MM-DD`. */
 const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
+/** #1603: namespace/project#issue, allowing nested groups and ASCII path segments.
+ * The final assertion requires the actual end of input, including after newlines.
+ */
+const QUALIFIED_ISSUE_RE = /^(?:[A-Za-z0-9](?:[A-Za-z0-9_.-]*[A-Za-z0-9])?\/)+[A-Za-z0-9](?:[A-Za-z0-9_.-]*[A-Za-z0-9])?#[1-9][0-9]*(?![\s\S])/;
+
 /**
  * Valid values for the optional `status` field (Epic #724 C1).
  * `completed`  — record written by a normal /close flow.
@@ -329,12 +334,17 @@ function _validateOptionalFields(entry) {
     }
   }
   if (entry.issues_created !== undefined) {
-    if (
-      !Array.isArray(entry.issues_created) ||
-      entry.issues_created.some((n) => typeof n !== 'number')
-    ) {
-      throw new ValidationError('issues_created must be an array of numbers');
+    if (!Array.isArray(entry.issues_created)) {
+      throw new ValidationError('issues_created must be an array of numbers or qualified references group/repo#n');
     }
+    entry.issues_created.forEach((issue, index) => {
+      if (typeof issue !== 'number' &&
+          !(typeof issue === 'string' && QUALIFIED_ISSUE_RE.test(issue))) {
+        throw new ValidationError(
+          `issues_created[${index}] must be a number or qualified reference group/repo#n`
+        );
+      }
+    });
   }
 
   // ADR-364 optional additive fields — remote-agent substrate thin-slice.

package/scripts/lib/session-start-probes.mjs

@@ -76,8 +76,15 @@ const CI_UNKNOWN_HINT_DEFAULT = 'run `glab ci status` on demand';
 /**
  * `ci-status` "no usable reading for HEAD" reasons after which the last PUSHED
  * commit is worth asking about: GitLab's `no-pipeline-for-head-sha`, GitHub's
- * `no-check-runs-for-head`, and GitLab's `pipeline-unmatched-ref` (all emitted
- * by `checkCiStatus`).
+ * `no-check-runs-for-head` and `head-sha-not-on-remote`, and GitLab's
+ * `pipeline-unmatched-ref` (all emitted by `checkCiStatus`).
+ *
+ * `head-sha-not-on-remote` (#1727) is GitHub's answer for a local HEAD the
+ * remote does not know — the normal state of a session with unpushed commits,
+ * now that the GitHub path asks for the LOCAL HEAD sha instead of the literal
+ * ref `HEAD`. Left out of this set, an unpushed GitHub HEAD rendered only the
+ * on-demand hint while the last pushed commit could be red: silence there
+ * reads as green, the #1332 collapse on the other host.
  *
  * `pipeline-unmatched-ref` (#857) is not a "no data" state — pipelines EXIST for
  * the sha, they just all sit on a foreign ref, so the reading stays `unknown`.
@@ -88,9 +95,24 @@ const CI_UNKNOWN_HINT_DEFAULT = 'run `glab ci status` on demand';
 const PUSHED_FOLLOW_UP_REASONS = new Set([
   'no-pipeline-for-head-sha',
   'no-check-runs-for-head',
+  'head-sha-not-on-remote',
   'pipeline-unmatched-ref',
 ]);
 
+/**
+ * The {@link PUSHED_FOLLOW_UP_REASONS} whose HEAD reading was taken for the
+ * LOCAL HEAD sha and found no CI data for it — so when the pushed commit IS
+ * HEAD, re-querying it would ask the identical question (see
+ * {@link ciPushedFollowUp}). `pipeline-unmatched-ref` is deliberately absent:
+ * there pipelines DO exist for the sha, only on a foreign ref, and the
+ * re-query keeps the behaviour #857 gave it.
+ */
+const NO_DATA_FOR_LOCAL_HEAD_REASONS = new Set([
+  'no-pipeline-for-head-sha',
+  'no-check-runs-for-head',
+  'head-sha-not-on-remote',
+]);
+
 /**
  * Full SHAs for `refs`, in order, from ONE `git rev-parse` — or `null` when
  * any ref does not resolve (no upstream, detached HEAD, not a git repo, git
@@ -143,16 +165,23 @@ async function revParseShas(repoRoot, refs) {
  * `skipped: network-probe-opt-in` and this never runs). It runs INSIDE the
  * probe's budget race and gets only what is left of that budget; if it
  * overruns or throws, the runner keeps the HEAD reading it was given (see
- * `runSessionStartProbes`). REVISIT TRIGGER: if `follow_up: 'budget-exceeded'`
- * shows up regularly in `orchestrator.probes.completed`, cache the verdict per
- * pushed SHA instead of re-asking.
+ * `runSessionStartProbes`). REVISIT TRIGGER: `follow_up: 'budget-exceeded'`
+ * on the `ci-status` record of `orchestrator.probes.completed` showing up
+ * regularly. Since #1728 that value means EITHER `ci-status` follow-up
+ * overran — this pushed-SHA requery OR {@link ciRedHistoryFollowUp}'s
+ * last-green history read — and the record carries no field that tells the
+ * two apart. Before caching the verdict per pushed SHA instead of re-asking,
+ * check the record's `outcome`: the pushed-SHA path runs only on an
+ * `unknown` reading (`ran-warn`), the history path only on a red one
+ * (`ran-alert`).
  *
- * The CLI round trip is skipped when the pushed commit IS HEAD on GitLab: its
- * HEAD reading was taken for the local HEAD SHA, so the re-query would ask the
- * identical question. Not on GitHub: `checkCiStatus` asks the API for the
- * literal ref `HEAD`, which GitHub resolves to the REMOTE default branch, not
- * the local HEAD — there the pushed SHA is a different question even when it
- * equals local HEAD.
+ * The CLI round trip is skipped when the pushed commit IS HEAD on a
+ * {@link NO_DATA_FOR_LOCAL_HEAD_REASONS} reading, on GitLab and GitHub alike:
+ * both paths take the HEAD reading for the LOCAL HEAD SHA, so the re-query
+ * would ask the identical question. GitHub joined that skip with #1727 —
+ * before it, `checkCiStatus` asked the GitHub API for the literal ref `HEAD`,
+ * which GitHub resolves to the REMOTE default branch, so the pushed SHA was a
+ * different question there even when it equalled local HEAD.
  *
  * The resolved SHA is handed to the runner through `deliver` BEFORE the CLI
  * round trip, so a requery that overruns the budget or throws still leaves
@@ -172,7 +201,7 @@ async function ciPushedFollowUp(result, ctx, requery, deliver) {
   // `pushed.sha: null` records "no upstream" as DATA — the renderer never asks git.
   if (!shas) return { ...result, pushed: { sha: null } };
   const [head, sha] = shas;
-  if (reason === 'no-pipeline-for-head-sha' && sha === head) {
+  if (NO_DATA_FOR_LOCAL_HEAD_REASONS.has(reason) && sha === head) {
     return { ...result, pushed: { sha, sameAsHead: true } };
   }
   deliver({ ...result, pushed: { sha } });
@@ -186,6 +215,36 @@ async function ciPushedFollowUp(result, ctx, requery, deliver) {
   return { ...result, pushed: { sha, verdict } };
 }
 
+/**
+ * `ci-status` follow-up (#1728): the GitHub red reading arrives WITHOUT its
+ * last-green history (`checkCiStatus({ deferHistory: true })`, reason
+ * `last-green-deferred`), so the red verdict is in the runner's hands before
+ * the ~0.5 s history query starts. It is delivered FIRST, re-marked
+ * `last-green-budget-exceeded` — the reading that stands if the query overruns
+ * the budget or throws, and that renders "history not read within the probe
+ * budget". Then the history query alone runs via the module's
+ * `readDeferredGithubHistory` — never a second full `checkCiStatus`, which
+ * would repeat `gh repo view` and the check-runs query.
+ *
+ * @param {*} result  A red reading with `details.reason: 'last-green-deferred'`
+ * @param {{repoRoot?: string}} ctx
+ * @param {(partial: *) => void} deliver
+ * @param {*} mod  The probe's imported module (`ci-status-banner.mjs`)
+ * @returns {Promise<*>}
+ */
+async function ciRedHistoryFollowUp(result, ctx, deliver, mod) {
+  const { deferredHistory: _pending, ...reading } = result;
+  const fallback = {
+    ...reading,
+    details: { ...reading.details, reason: 'last-green-budget-exceeded' },
+  };
+  deliver(fallback);
+  // No reader on the module: the query never ran, so no budget was exceeded —
+  // keep the reading's own `last-green-deferred` ("history not read").
+  if (typeof mod?.readDeferredGithubHistory !== 'function') return reading;
+  return mod.readDeferredGithubHistory(result, { repoRoot: ctx?.repoRoot });
+}
+
 /**
  * The `ci-status` follow-up (#1332, #1396): every git fact a `ci-status`
  * banner names is resolved HERE, inside the probe's budget race, and carried
@@ -198,14 +257,20 @@ async function ciPushedFollowUp(result, ctx, requery, deliver) {
  *     {@link ciPushedFollowUp} (`pushed`)
  *   - a `green` reading beside a set-aside FAILED same-commit pipeline →
  *     `head: { sha }` for {@link droppedFailedLine} (#1390 P5)
+ *   - a GitHub `red` reading whose history was deferred →
+ *     {@link ciRedHistoryFollowUp} (`redCount` / `lastGreen`, #1728)
  *
  * @param {*} result
  * @param {{repoRoot?: string}} ctx
  * @param {(extra: object) => Promise<*>} requery
  * @param {(partial: *) => void} deliver
+ * @param {*} [mod]  The probe's imported module
  * @returns {Promise<*>}
  */
-async function ciStatusFollowUp(result, ctx, requery, deliver) {
+async function ciStatusFollowUp(result, ctx, requery, deliver, mod) {
+  if (result?.status === 'red' && result?.details?.reason === 'last-green-deferred') {
+    return ciRedHistoryFollowUp(result, ctx, deliver, mod);
+  }
   if (result?.status === 'unknown' && PUSHED_FOLLOW_UP_REASONS.has(result?.details?.reason)) {
     return ciPushedFollowUp(result, ctx, requery, deliver);
   }
@@ -276,6 +341,56 @@ function ciUnknownHint(result) {
   return `last pushed: ${short} (pipeline not checked; run \`${commitRunsCommand(gh, sha)}\`)`;
 }
 
+/**
+ * The `(pipeline #<id>)` part of a red `ci-status` line. GitLab readings carry
+ * `details.currentPipelineId` (`?` when it is null, the pre-#856 text). GitHub
+ * readings have no pipeline id at all (#856) — there the part is omitted
+ * instead of printing a `(pipeline #?)` that names a pipeline that never
+ * existed.
+ *
+ * @param {*} r
+ * @returns {string}
+ */
+function redPipelineText(r) {
+  const details = r?.details;
+  if (!details || typeof details !== 'object' || !('currentPipelineId' in details)) return '';
+  return ` (pipeline #${details.currentPipelineId ?? '?'})`;
+}
+
+/**
+ * The `— last green: …` part of a red `ci-status` line.
+ *
+ *   - GitLab (`lastGreen.pipelineId` present): unchanged text, byte for byte.
+ *   - GitHub (#856, no pipeline ids): `— last green: commit <sha7> (<n>
+ *     commit(s) ago)` — interpolating the GitLab form there printed
+ *     `#undefined` into the banner the operator reads.
+ *   - `details.reason: 'last-green-query-failed'` with no `lastGreen`: says
+ *     so. Omitting it would read exactly like "no green commit in the window",
+ *     a different fact (three states, not two: found / none / not measured).
+ *   - `last-green-budget-exceeded` (#1728): the red verdict arrived, the
+ *     history query did not finish inside the probe budget — says so.
+ *     `last-green-deferred` (the follow-up never re-marked it): not read.
+ *
+ * @param {*} r
+ * @returns {string}
+ */
+function lastGreenText(r) {
+  const lg = r?.lastGreen;
+  if (lg && typeof lg === 'object') {
+    const sha7 = String(lg.sha ?? '').slice(0, 7);
+    if (lg.pipelineId !== undefined) {
+      return ` — last green: #${lg.pipelineId} (commit ${sha7}, ${r.redCount} pipelines ago)`;
+    }
+    const n = lg.ageCommits;
+    return ` — last green: commit ${sha7} (${n} commit${n === 1 ? '' : 's'} ago)`;
+  }
+  const reason = r?.details?.reason;
+  if (reason === 'last-green-query-failed') return ' — last green: unknown (history query failed)';
+  if (reason === 'last-green-budget-exceeded') return ' — last green: unknown (history not read within the probe budget)';
+  if (reason === 'last-green-deferred') return ' — last green: unknown (history not read)';
+  return '';
+}
+
 /** Additive GitHub diagnostics; absent counts leave existing banners unchanged. */
 function checkRunCountsText(result) {
   const counts = result?.details?.checkRunCounts;
@@ -508,10 +623,12 @@ function startLoopBlockedMeter() {
  *   - `precondition` optional; returns a skip-reason string to skip the probe
  *   - `render`     optional; maps a result to a banner line. Default:
  *                  `result.message` when severity is warn/alert.
- *   - `followUp`   optional; `async (result, ctx, requery, deliver) => result'`
+ *   - `followUp`   optional; `async (result, ctx, requery, deliver, mod) => result'`
  *                  run INSIDE the budget race after the entry function, where
- *                  `requery(extra)` re-invokes it with `{...args, ...extra}`
- *                  and `deliver(partial)` replaces the fallback result. If it
+ *                  `requery(extra)` re-invokes it with `{...args, ...extra}`,
+ *                  `deliver(partial)` replaces the fallback result, and `mod`
+ *                  is the probe's imported module (for a narrower second call
+ *                  than a full requery, #1728). If it
  *                  throws or overruns the budget, the last delivered result
  *                  stands (recorded `followUp: 'threw'|'budget-exceeded'`).
  *   - `render` is a PURE function of the result (#1396): anything it names
@@ -571,10 +688,23 @@ export const PROBES = [
     spec: local('./ci-status-banner.mjs'),
     fn: 'checkCiStatus',
     network: true,
-    args: ({ repoRoot }) => ({ repoRoot }),
+    // #1728: `deferHistory` keeps the GitHub last-green history query out of
+    // the entry function, so a red verdict is delivered before the query can
+    // overrun PROBE_BUDGET_MS (measured 2026-10-22: red with history
+    // 1605–1717 ms, the query alone ~495 ms). The follow-up reads it inside
+    // what is left of the budget. Ceiling: other local-HEAD callers of
+    // `checkCiStatus` still pay the query inline on red (see `checkGithub`).
+    // Second ceiling (BV-004): the red verdict is still lost when
+    // `checkCiStatus` ITSELF (git lookups + `gh repo view` + check-runs,
+    // measured 915–941 ms on 2026-10-22) overruns the work-time budget —
+    // `delivered` is set only after the entry function returns. Revisit
+    // trigger: an `orchestrator.probes.completed` record with `ci-status`
+    // `outcome: 'timeout'`.
+    args: ({ repoRoot }) => ({ repoRoot, deferHistory: true }),
     // #1332: on `no-pipeline-for-head-sha` / `no-check-runs-for-head`, query
     // the last PUSHED commit's verdict via `checkCiStatus({ sha })` — see the
     // ceiling on the function. #1396: also resolves every SHA the renderer names.
+    // #1728: on a deferred GitHub red reading, reads the last-green history.
     followUp: ciStatusFollowUp,
     // Bespoke shape: `{status, ok, details, …}` with no `message` field. The
     // banner text is prescribed by SKILL.md § Phase 4.
@@ -602,12 +732,8 @@ export const PROBES = [
         return `${mark} ci-status: CI status for HEAD could not be determined (${reason})${checkRunCountsText(r)} — ${ciUnknownHint(r)}`;
       }
       if (r.status === 'red') {
-        const pid = r.details?.currentPipelineId ?? '?';
-        const green = r.lastGreen
-          ? ` — last green: #${r.lastGreen.pipelineId} (commit ${String(r.lastGreen.sha ?? '').slice(0, 7)}, ${r.redCount} pipelines ago)`
-          : '';
         const job = r.failingJobName ? ` Failing job: ${r.failingJobName}` : '';
-        return `🚨 CI RED on HEAD (pipeline #${pid})${green}.${job}${checkRunCountsText(r)}`;
+        return `🚨 CI RED on HEAD${redPipelineText(r)}${lastGreenText(r)}.${job}${checkRunCountsText(r)}`;
       }
       if (r.status === 'green') {
         const lines = [];
@@ -1134,6 +1260,7 @@ export async function runSessionStartProbes(opts = {}, deps = {}) {
               ctx,
               (extra) => fn({ ...probe.args(ctx), ...extra }),
               (partial) => { delivered = { __probeResult: partial }; },
+              mod,
             ),
           };
         } catch {

package/scripts/lib/session-token-rollup.mjs

@@ -122,6 +122,7 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { costUsd } from './telemetry/pricing.mjs';
+import { resolveLedgerPath } from './ledger-path.mjs';
 
 // ---------------------------------------------------------------------------
 // Default subagents.jsonl path (relative to cwd, mirroring the rest of the
@@ -262,7 +263,7 @@ function recordCostUsd(record) {
  */
 export function rollupSessionTokens({
   parentSessionId,
-  subagentsPath = DEFAULT_SUBAGENTS_PATH,
+  subagentsPath = resolveLedgerPath(DEFAULT_SUBAGENTS_PATH, process.cwd()),
 }) {
   /** @type {TokenRollupResult} */
   const ZERO = {