session-orchestrator 5.4.0 → 5.6.0

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

@@ -3,11 +3,11 @@
  *
  * ## Why this module exists
  *
- * `skills/session-start/SKILL.md` § Phase 4 names 19 measurement probes, each
- * with a module path and an entry function (re-measured 2026-09-11 — see the
+ * `skills/session-start/SKILL.md` § Phase 4 names 20 measurement probes, each
+ * with a module path and an entry function (re-measured 2026-10-02 — see the
  * registry Census below; the family stood at 18 when this module was written
- * on 2026-08-23 and one probe was registered since without updating this
- * count, the exact drift this header now warns readers not to repeat).
+ * on 2026-08-23, at 19 on 2026-09-11, and gained `events-retention` with
+ * #1401 — update this count with every registration).
  * Measured 2026-08-23 at `4f6404e`, NONE of them had a mechanical caller:
  *
  * ```
@@ -44,12 +44,14 @@
  * @module scripts/lib/session-start-probes
  */
 
-import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
 
 import { emitEvent } from './events.mjs';
+import { ARCHIVE_DIR_NAME, ARCHIVE_NAME_RE } from './events-schema.mjs';
 
 /**
  * Resolve a sibling module to an absolute `file:` URL.
@@ -66,6 +68,8 @@ import { emitEvent } from './events.mjs';
  */
 const local = (rel) => pathToFileURL(path.join(import.meta.dirname, rel)).href;
 
+const execFileAsync = promisify(execFile);
+
 /** Fallback hint when nothing cheaper than an on-demand CLI call is available. */
 const CI_UNKNOWN_HINT_DEFAULT = 'run `glab ci status` on demand';
 
@@ -93,24 +97,30 @@ const PUSHED_FOLLOW_UP_REASONS = new Set([
  * missing). Full, not short: `checkCiStatus({ sha })` matches against GitLab's
  * full pipeline SHAs and refuses anything shorter.
  *
- * NAMED CEILING (BV-004): one `git rev-parse` with a 2s timeout, run only on
- * the {@link PUSHED_FOLLOW_UP_REASONS} branch — i.e. only when the `ci-status`
- * probe already ran (network opt-in) and already found no data for HEAD.
+ * NAMED CEILING (BV-004): one `git rev-parse` with a 2s timeout, called only
+ * from {@link ciStatusFollowUp} — i.e. only when the `ci-status` probe already
+ * ran (network opt-in) and its reading needs a commit SHA.
+ *
+ * ASYNC on purpose (#1396): it runs inside the probe's budget race, and only a
+ * call that yields the event loop is (a) counted as the probe's OWN work time
+ * and (b) preemptible by the race. A synchronous spawn is subtracted from
+ * `workMs` as loop-blocked time (see {@link startLoopBlockedMeter}), so a 2s
+ * hang would never have scored `budget-exceeded`. An abandoned child is not
+ * waited for: the hook ends with `process.exit(0)`.
  *
  * @param {string|undefined} repoRoot
  * @param {string[]} refs
- * @returns {string[]|null}
+ * @returns {Promise<string[]|null>}
  */
-function revParseShas(repoRoot, refs) {
+async function revParseShas(repoRoot, refs) {
   if (!repoRoot || typeof repoRoot !== 'string') return null;
   try {
-    const out = execFileSync('git', ['rev-parse', ...refs], {
+    const { stdout } = await execFileAsync('git', ['rev-parse', ...refs], {
       cwd: repoRoot,
       encoding: 'utf8',
       timeout: 2000,
-      stdio: ['ignore', 'pipe', 'ignore'],
     });
-    const shas = String(out).trim().split('\n').map((s) => s.trim());
+    const shas = String(stdout).trim().split('\n').map((s) => s.trim());
     const valid = shas.length === refs.length
       && shas.every((s) => /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(s));
     return valid ? shas : null;
@@ -121,16 +131,6 @@ function revParseShas(repoRoot, refs) {
   }
 }
 
-/**
- * Full SHA of the last PUSHED commit (`@{upstream}`), or `null`.
- *
- * @param {string|undefined} repoRoot
- * @returns {string|null}
- */
-function lastPushedSha(repoRoot) {
-  return revParseShas(repoRoot, ['@{upstream}'])?.[0] ?? null;
-}
-
 /**
  * `ci-status` follow-up (#1332): when HEAD has no CI data, ask for the verdict
  * of the last PUSHED commit — the commit whose pipeline can actually be red
@@ -154,25 +154,28 @@ function lastPushedSha(repoRoot) {
  * the local HEAD — there the pushed SHA is a different question even when it
  * equals 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
+ * the pushed SHA in the reading the renderer receives (#1396).
+ *
  * @param {*} result   The HEAD reading from `checkCiStatus`
  * @param {{repoRoot?: string}} ctx
  * @param {(extra: object) => Promise<*>} requery  Re-invokes the probe with extra options
+ * @param {(partial: *) => void} deliver  Records a partial result as the fallback
  * @returns {Promise<*>}
  */
-async function ciPushedFollowUp(result, ctx, requery) {
+async function ciPushedFollowUp(result, ctx, requery, deliver) {
   const reason = result?.details?.reason;
-  if (result?.status !== 'unknown' || !PUSHED_FOLLOW_UP_REASONS.has(reason)) {
-    return result;
-  }
   // One spawn for both: an unresolvable `@{upstream}` fails the whole call,
   // which is exactly the "no upstream" answer.
-  const shas = revParseShas(ctx?.repoRoot, ['HEAD', '@{upstream}']);
-  // `pushed.sha: null` records "no upstream" so the renderer does not ask git again.
+  const shas = await revParseShas(ctx?.repoRoot, ['HEAD', '@{upstream}']);
+  // `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) {
     return { ...result, pushed: { sha, sameAsHead: true } };
   }
+  deliver({ ...result, pushed: { sha } });
   let verdict;
   try {
     verdict = await requery({ sha });
@@ -183,6 +186,36 @@ async function ciPushedFollowUp(result, ctx, requery) {
   return { ...result, pushed: { sha, verdict } };
 }
 
+/**
+ * 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
+ * on the result as data — the renderer stays a pure function of the result.
+ * #1396: the renderer used to run `git rev-parse` itself after a fallen-back
+ * follow-up, outside the budget, where `orchestrator.probes.completed` could
+ * never score it `timed_out`.
+ *
+ *   - an `unknown` reading on a {@link PUSHED_FOLLOW_UP_REASONS} reason →
+ *     {@link ciPushedFollowUp} (`pushed`)
+ *   - a `green` reading beside a set-aside FAILED same-commit pipeline →
+ *     `head: { sha }` for {@link droppedFailedLine} (#1390 P5)
+ *
+ * @param {*} result
+ * @param {{repoRoot?: string}} ctx
+ * @param {(extra: object) => Promise<*>} requery
+ * @param {(partial: *) => void} deliver
+ * @returns {Promise<*>}
+ */
+async function ciStatusFollowUp(result, ctx, requery, deliver) {
+  if (result?.status === 'unknown' && PUSHED_FOLLOW_UP_REASONS.has(result?.details?.reason)) {
+    return ciPushedFollowUp(result, ctx, requery, deliver);
+  }
+  if (result?.status === 'green' && droppedFailedCount(result) > 0) {
+    const sha = (await revParseShas(ctx?.repoRoot, ['HEAD']))?.[0] ?? null;
+    return { ...result, head: { sha } };
+  }
+  return result;
+}
+
 /**
  * `CI <status> (#<pipeline>)` for a pushed-SHA verdict, or `null` when there
  * is no readable verdict (the caller then falls back to the command hint).
@@ -222,18 +255,18 @@ function commitRunsCommand(gh, sha) {
  *
  * @param {object} result   The probe result (possibly carrying `pushed` from
  *   {@link ciPushedFollowUp})
- * @param {{repoRoot?: string}} [ctx]
  * @returns {string}
  */
-function ciUnknownHint(result, ctx) {
+function ciUnknownHint(result) {
   if (!PUSHED_FOLLOW_UP_REASONS.has(result?.details?.reason)) return CI_UNKNOWN_HINT_DEFAULT;
   // The GitHub reason names the gh CLI; a glab command there would be wrong.
   const gh = result.details.cliUsed === 'gh';
   const onDemand = gh ? 'run `gh run list` on demand' : CI_UNKNOWN_HINT_DEFAULT;
   const pushed = result.pushed && typeof result.pushed === 'object' ? result.pushed : null;
-  // The follow-up already resolved the SHA (or its absence) — never re-ask git.
-  // Without `pushed` (follow-up overran or threw) this is the only git call.
-  const sha = pushed ? pushed.sha : lastPushedSha(ctx?.repoRoot);
+  // Pure (#1396): the SHA is whatever the follow-up resolved inside the budget.
+  // Without `pushed` (the follow-up overran or threw before resolving it) the
+  // hint degrades to the on-demand command — it never asks git itself.
+  const sha = pushed ? pushed.sha : null;
   if (!sha) return onDemand;
   const short = sha.slice(0, 8);
   if (pushed?.sameAsHead) return `last pushed: ${short} = HEAD — ${onDemand}`;
@@ -277,22 +310,22 @@ function droppedFailedCount(r) {
  * #857 ref-preference result; this only stops the failure from vanishing
  * behind a silent green.
  *
- * NAMED CEILING (BV-004): one `git rev-parse HEAD` (2s timeout), run only on
- * this branch — a green reading WITH a set-aside `failed` run, behind the
- * network opt-in. The reading carries no sha, and the GitLab path read the
- * local HEAD, so HEAD is the commit it spoke for. REVISIT TRIGGER: once
- * `checkCiStatus` publishes the sha it read, take it from the reading.
+ * The HEAD sha comes from `r.head.sha`, resolved by {@link ciStatusFollowUp}
+ * inside the budget (#1396) — the reading carries no sha, and the GitLab path
+ * read the local HEAD, so HEAD is the commit it spoke for. Without it (the
+ * follow-up fell back) the line names the CLI's failed-run listing instead.
+ * REVISIT TRIGGER: once `checkCiStatus` publishes the sha it read, take it
+ * from the reading.
  *
  * Only the GitLab path publishes `droppedStatuses` today (`candidateEvidence`
  * is called from `checkGitlab` alone); the gh form exists so a GitHub producer
  * can never print a glab command (#1339 P1 class) — see {@link commitRunsCommand}.
  *
  * @param {*} r  A green reading with `droppedFailedCount(r) > 0`
- * @param {{repoRoot?: string}} [ctx]
  * @returns {string}
  */
-function droppedFailedLine(r, ctx) {
-  const sha = revParseShas(ctx?.repoRoot, ['HEAD'])?.[0] ?? null;
+function droppedFailedLine(r) {
+  const sha = typeof r.head?.sha === 'string' ? r.head.sha : null;
   const gh = r.details.cliUsed === 'gh';
   let check;
   if (sha) check = commitRunsCommand(gh, sha);
@@ -432,11 +465,15 @@ function startLoopBlockedMeter() {
  * — the #1157 SKILL.md-size split extracted Phase 4's procedure out of
  * `SKILL.md` itself, so the original 2026-08-23 citation of SKILL.md lines
  * 693-835 no longer resolves; re-run the census against the reference file):
- *   grep -oE 'via `(await )?check[A-Za-z]+' \
- *     skills/session-start/references/phase-4-ssot-environment-check.md   # -> 17
- * plus two probes the prose introduces with different phrasing —
- * `checkBootstrapLockFreshness` ("invoke the bootstrap-lock-freshness probe")
- * and `checkVaultStaleness` ("read the most recent line via …") — for 19.
+ *   grep -oE "fn: 'check[A-Za-z]+'" scripts/lib/session-start-probes.mjs \
+ *     | sed "s/fn: '//;s/'//" > fns.txt                                  # -> 20
+ *   grep -oFf fns.txt \
+ *     skills/session-start/references/phase-4-ssot-environment-check.md \
+ *     | sort -u | wc -l                                                    # -> 20
+ * i.e. every registered entry function is named in the reference file
+ * (2026-10-02, after `events-retention` / #1401; 19 on 2026-09-11). The older
+ * census `grep -oE 'via \`(await )?check[A-Za-z]+'` returned 0 at `86e636a9`
+ * — the prose no longer says "via" — so it is retired, not re-counted.
  * (Prior census, 2026-08-23 at `4f6404e`: 16 + 2 = 18 — one probe was
  * registered since without a matching update here. This count is deliberately
  * NOT pinned by an exact-equality test against `PROBES.length` — the registry
@@ -456,11 +493,19 @@ 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) => result'` run
- *                  INSIDE the budget race after the entry function, where
- *                  `requery(extra)` re-invokes it with `{...args, ...extra}`.
- *                  If it throws or overruns the budget, the entry function's
- *                  result stands (recorded `followUp: 'threw'|'budget-exceeded'`).
+ *   - `followUp`   optional; `async (result, ctx, requery, deliver) => 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
+ *                  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
+ *     that the entry function does not return is resolved in `followUp`,
+ *     inside the budget — never in the renderer.
+ *   - `telemetry`  optional; PURE `(result) => object|undefined` — the numbers
+ *                  the probe measured, persisted as `measure` on its element
+ *                  of `orchestrator.probes.completed` for `ran-*` outcomes
+ *                  (#1489), bounded by {@link probeMeasure}.
  */
 export const PROBES = [
   {
@@ -514,8 +559,8 @@ export const PROBES = [
     args: ({ repoRoot }) => ({ repoRoot }),
     // #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.
-    followUp: ciPushedFollowUp,
+    // ceiling on the function. #1396: also resolves every SHA the renderer names.
+    followUp: ciStatusFollowUp,
     // Bespoke shape: `{status, ok, details, …}` with no `message` field. The
     // banner text is prescribed by SKILL.md § Phase 4.
     //
@@ -525,7 +570,7 @@ export const PROBES = [
     // probe. Without these two lines a degraded ci-status result scored `'ok'`
     // and rendered nothing — "could not read" displayed exactly like "green",
     // which is the confusion the probe's own migration removed one layer down.
-    render: (r, ctx) => {
+    render: (r) => {
       if (!r || typeof r !== 'object') return null;
       if (r.degraded) return typeof r.message === 'string' && r.message ? r.message : null;
       // `status: 'unknown'` is the SAME collapse one level over: HEAD carries
@@ -539,7 +584,7 @@ export const PROBES = [
         // #1337: a RED pushed commit is an alert, and the banner says what the
         // rule judges (HR-106) — same 🚨 as a red HEAD.
         const mark = r.pushed?.verdict?.status === 'red' ? '🚨' : '⚠';
-        return `${mark} ci-status: CI status for HEAD could not be determined (${reason}) — ${ciUnknownHint(r, ctx)}`;
+        return `${mark} ci-status: CI status for HEAD could not be determined (${reason}) — ${ciUnknownHint(r)}`;
       }
       if (r.status === 'red') {
         const pid = r.details?.currentPipelineId ?? '?';
@@ -556,7 +601,7 @@ export const PROBES = [
           lines.push(`⚠ CI green on HEAD, but ${r.allowFailureJobs.length} allow_failure job(s) FAILED: ${names}. A pipeline reports success regardless of these.`);
         }
         // #1390 P5: a failed same-commit pipeline the ref preference set aside.
-        if (droppedFailedCount(r) > 0) lines.push(droppedFailedLine(r, ctx));
+        if (droppedFailedCount(r) > 0) lines.push(droppedFailedLine(r));
         // Both findings can hold at once; `pushBanner` takes a multi-line
         // string verbatim, so neither swallows the other.
         return lines.length > 0 ? lines.join('\n') : null;
@@ -705,6 +750,40 @@ export const PROBES = [
     network: false,
     args: ({ repoRoot, env }) => ({ repoRoot, env }),
   },
+  {
+    // #1401 part 3: archive COUNT retention vs the TIME window the ledger's
+    // readers declare (`REQUIRED_EVENTS_WINDOW_DAYS`). Without any ledger there
+    // is nothing to measure — recorded as `skipped`, never as `ran-clean`. A
+    // bare, empty or foreign-only `_archive/` is no ledger either: the probe
+    // answers those `not-measured` at severity ok, which the runner would
+    // record as `ran-clean` (see {@link hasRotationArchive}).
+    id: 'events-retention',
+    spec: local('./events-retention-banner.mjs'),
+    fn: 'checkEventsRetention',
+    network: false,
+    precondition: ({ repoRoot }) => {
+      const metrics = path.join(repoRoot, '.orchestrator', 'metrics');
+      return existsSync(path.join(metrics, 'events.jsonl')) || hasRotationArchive(metrics)
+        ? null
+        : 'no-events-ledger';
+    },
+    args: ({ repoRoot, config }) => ({ repoRoot, config }),
+    // #1489: the coverage reaches the ledger on every measured answer, warn or
+    // not — a warning that never fires is otherwise indistinguishable from a
+    // dead one (HR-105). Counts and day spans only: no path, no timestamp.
+    // A degraded answer carries no `archives`, so it persists no measure. Every
+    // measured answer has a finite `coverageDays` — a span with no stamp is
+    // degraded since #1498 — and `probeMeasure` drops a non-finite value, so a
+    // regression there reads as "not measured", never as a number.
+    telemetry: (r) => (Number.isInteger(r?.archives)
+      ? {
+          coverage_days: Math.round(r.coverageDays * 1000) / 1000,
+          archives: r.archives,
+          max_backups: r.maxBackups,
+          required_days: r.requiredDays ?? null,
+        }
+      : undefined),
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -730,6 +809,68 @@ function pluginVersion() {
   }
 }
 
+/**
+ * NAMED CEILING (BV-004): keys per probe `measure`. `events-retention`, the one
+ * probe with telemetry today, persists 4. Revisit when a probe needs more than
+ * 8 — the cap exists so one probe cannot inflate every SessionStart record.
+ */
+const MEASURE_MAX_KEYS = 8;
+const MEASURE_KEY_RE = /^[a-z][a-z0-9_]{0,31}$/;
+
+/**
+ * A probe's `telemetry(result)`, bounded for the ledger (#1489): at most
+ * {@link MEASURE_MAX_KEYS} snake_case keys whose values are finite numbers or
+ * `null`; any other entry is dropped. Strings are refused outright, not
+ * vetted: `orchestrator.probes.completed` also travels over the optional
+ * webhook unredacted, and a string is how a path or a repo slug gets there.
+ * A missing, throwing or empty telemetry yields `undefined` — no `measure`
+ * key, which reads as "not measured", never as zero.
+ *
+ * Reading the returned object stays inside the `try`: `Object.entries` runs
+ * its getters and a Proxy's `ownKeys` trap, and either may throw — which,
+ * outside it, rejected the whole runner against its never-rejects contract.
+ *
+ * @param {{telemetry?: Function}} probe
+ * @param {*} result — the probe's delivered result
+ * @returns {Record<string, number|null>|undefined}
+ */
+function probeMeasure(probe, result) {
+  if (typeof probe.telemetry !== 'function') return undefined;
+  try {
+    const raw = probe.telemetry(result);
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+    const entries = Object.entries(raw)
+      .filter(([k, v]) => MEASURE_KEY_RE.test(k) && (v === null || (typeof v === 'number' && Number.isFinite(v))))
+      .slice(0, MEASURE_MAX_KEYS);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Does `<metricsDir>/_archive/` hold at least one rotated events archive? The
+ * `events-retention` precondition's second half.
+ *
+ * It lists the directory exactly as `checkEventsRetention` does (same
+ * `ARCHIVE_NAME_RE` filter), so the precondition skips precisely the inputs the
+ * probe would answer `not-measured`. The directory existing is not a ledger
+ * (#1401 review: an empty or foreign-only `_archive/` was recorded
+ * `ran-clean`). Any listing error other than ENOENT answers `true`: the probe
+ * then runs and reports the unlistable directory as `degraded`, because an
+ * unreadable source must never be skipped as absent.
+ *
+ * @param {string} metricsDir — `<repoRoot>/.orchestrator/metrics`
+ * @returns {boolean}
+ */
+function hasRotationArchive(metricsDir) {
+  try {
+    return readdirSync(path.join(metricsDir, ARCHIVE_DIR_NAME)).some((n) => ARCHIVE_NAME_RE.test(n));
+  } catch (err) {
+    return err?.code !== 'ENOENT';
+  }
+}
+
 /**
  * Race `promise` against a budget denominated in the probe's OWN work time —
  * wall-clock elapsed MINUS the time a synchronous sibling held the event loop
@@ -973,7 +1114,12 @@ export async function runSessionStartProbes(opts = {}, deps = {}) {
         // the race below: a timeout with `delivered` set is `delivered`.
         try {
           return {
-            __probeResult: await probe.followUp(first, ctx, (extra) => fn({ ...probe.args(ctx), ...extra })),
+            __probeResult: await probe.followUp(
+              first,
+              ctx,
+              (extra) => fn({ ...probe.args(ctx), ...extra }),
+              (partial) => { delivered = { __probeResult: partial }; },
+            ),
           };
         } catch {
           followUpFailure = 'threw';
@@ -1001,24 +1147,49 @@ export async function runSessionStartProbes(opts = {}, deps = {}) {
         if (raced.__absent || raced.__probeError?.code === 'ERR_MODULE_NOT_FOUND') {
           record('skipped', { reason: 'module-absent' });
         } else {
-          record('error', { reason: String(raced.__probeError?.message ?? raced.__probeError).slice(0, 200) });
+          // The thrown value is probe-supplied: String() of an object without a
+          // prototype (or with a throwing toString) throws itself, which would
+          // reject the runner — the contract is that it never rejects.
+          let reason;
+          try {
+            reason = String(raced.__probeError?.message ?? raced.__probeError).slice(0, 200);
+          } catch {
+            reason = 'probe-threw-unprintable';
+          }
+          record('error', { reason });
         }
         return;
       }
 
       const result = raced?.__probeResult;
-      const severity = severityOf(result, probe);
-      // `ctx` (repoRoot/config/env) is passed as a SECOND argument so a
-      // renderer can name a repo-local fact the probe result does not carry
-      // (the `ci-status` unknown branch names the last pushed SHA). Every
-      // existing renderer takes one parameter and ignores it.
-      const line = typeof probe.render === 'function'
-        ? probe.render(result, ctx)
-        : defaultRender(result, severity);
+      // A custom `severityOf`, a `render`, or a getter on the result the
+      // defaults read is probe-supplied code that can throw. The runner never
+      // rejects, so such a throw degrades this probe the way a throwing
+      // precondition does: `error` with a fixed reason, no banner line.
+      let severity;
+      let line;
+      let stage = 'severity-threw';
+      try {
+        severity = severityOf(result, probe);
+        stage = 'render-threw';
+        // The renderer gets the RESULT only (#1396): no `ctx`, so it has no
+        // repo to spawn git against. It runs after the budget race, where
+        // nothing it did would be measured; a repo-local fact a banner names
+        // is resolved in the probe's `followUp`, inside the race, and carried
+        // as data.
+        line = typeof probe.render === 'function'
+          ? probe.render(result)
+          : defaultRender(result, severity);
+      } catch {
+        record('error', { reason: stage, workMs });
+        return;
+      }
+      const measure = probeMeasure(probe, result);
       record(severity === 'ok' ? 'ran-clean' : severity === 'warn' ? 'ran-warn' : 'ran-alert', {
         severity,
         workMs,
         ...(followUpFailure ? { followUp: followUpFailure } : {}),
+        ...(measure ? { measure } : {}),
         ...(line ? { line } : {}),
       });
     }),
@@ -1082,6 +1253,9 @@ export async function runSessionStartProbes(opts = {}, deps = {}) {
       // A follow-up that fell back to the delivered result is otherwise
       // invisible (the outcome is `ran-*`); this is its revisit trigger's input.
       ...(typeof r.followUp === 'string' ? { follow_up: r.followUp } : {}),
+      // What the probe MEASURED, warn or not (#1489, HR-105): without it a
+      // probe that never warns reads the same whether it is rare or dead.
+      ...(r.measure ? { measure: r.measure } : {}),
     })),
   };
 

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

@@ -93,8 +93,9 @@
  * without usage turns, or unreadable, #1474), or when the agent has a start
  * record but its stop found no transcript of its own and no other record of the
  * same agent did (`start_record_found: true`, `subagent_transcript_found: false`
- * — mostly `workflow-subagent`). A phantom stop (#939, no start record) is no
- * agent and no candidate. A record whose four token buckets
+ * — mostly `workflow-subagent`), or when its only own-transcript records are
+ * schema_version 1 (#1487 Pkt 1 — v1 has no priceable buckets). A phantom stop
+ * (#939, no start record) is no agent and no candidate. A record whose four token buckets
  * are all 0 is priced at $0 whatever its model, and never turns a null total into
  * a number on its own. A record whose turns span several models carries
  * `models_usage` (#1470) and is priced part by part. `cost_records_priced` /
@@ -104,11 +105,16 @@
  * Blind spots the ledger cannot close: an agent whose start record lies outside
  * the hook's tail window reads `start_record_found: false` and is
  * indistinguishable from a phantom, and an agent that left neither a start nor a
- * stop record is invisible. One blind spot is a rule of this module, not the
- * ledger: a session spanning the 2026-09-09 schema boundary is priced over its v2
- * records only — its v1 records are `legacy_v1_records`, never cost candidates
- * (4 distinct fleet sessions carry such a numeric cost, 31 ledgers, 2026-10-01).
- * "Never a partial sum" holds only over the v2 agents the ledger can see.
+ * stop record is invisible. "Never a partial sum" holds over the agents the
+ * ledger can see. Until #1487 Pkt 1 (2026-10-02) a session spanning the
+ * 2026-09-09 schema boundary was priced over its v2 records only — its v1
+ * agents were never cost candidates, so the v2 half's sum read as the whole
+ * bill (4 distinct fleet sessions, 31 ledgers, 2026-10-01). A v1 agent is now an
+ * unpriced candidate: such a session reports `total_cost_usd: null` with
+ * `cost_records_priced < cost_records_total`. Re-measured 2026-10-02 (28
+ * ledgers, 1,887 ledger/session pairs): the same 4 sessions turn null, and 498
+ * pure-v1 pairs change only `cost_records_total` (0/0 → 0/N, cost null before
+ * and after). FORWARD-ONLY like the #949 cut.
  *
  * @module session-token-rollup
  */
@@ -238,10 +244,10 @@ function recordCostUsd(record) {
  * @property {number|null}  total_token_input_uncached - Sum of token_input_uncached over the same one record per agent.
  * @property {number|null}  total_token_cache_read     - Sum of token_cache_read over the same one record per agent.
  * @property {number|null}  total_token_cache_creation - Sum of token_cache_creation over the same one record per agent.
- * @property {number|null}  total_cost_usd     - Σ cost over the agents counted in cost_records_priced; null when cost_records_priced < cost_records_total (#1475 — any unpriced candidate: unknown model, no model, no tokens, or a started agent without a transcript), null when there is nothing to price (cost_records_total 0), and null when no record with a non-zero bucket was priced (all-zero records alone never yield a fabricated $0). Never 0 for unknown — see telemetry/pricing.mjs.
+ * @property {number|null}  total_cost_usd     - Σ cost over the agents counted in cost_records_priced; null when cost_records_priced < cost_records_total (#1475 — any unpriced candidate: unknown model, no model, no tokens, a started agent without a transcript, or a v1 agent, #1487 Pkt 1), null when there is nothing to price (cost_records_total 0), and null when no record with a non-zero bucket was priced (all-zero records alone never yield a fabricated $0). Never 0 for unknown — see telemetry/pricing.mjs.
  * @property {number}       cost_records_priced - How many agents of cost_records_total carry a known cost on their last found v2 record: priced by the table (per model part when the record carries models_usage, #1470), or all four token buckets 0 (priced at $0 whatever the model, #1474).
- * @property {number}       cost_records_total  - How many agents were candidates for pricing, each counted once however often it stopped: every agent with a v2 record whose own transcript was found — priced on its LAST such record, so one whose last read yielded no tokens (transcript oversized, without usage turns, or unreadable, #1474) is unpriced — plus every started agent whose v2 stops found no transcript of its own (`start_record_found: true`, `subagent_transcript_found: false`) and that has no token-bearing record in the session. Both latter kinds have an unknown cost. Phantom stops (no start record, #939) are never candidates. priced < total nulls total_cost_usd.
- * @property {number}       legacy_v1_records  - Token-bearing records EXCLUDED from every total above because their schema_version < 2 (their token_input is a different quantity).
+ * @property {number}       cost_records_total  - How many agents were candidates for pricing, each counted once however often it stopped: every agent with a v2 record whose own transcript was found — priced on its LAST such record, so one whose last read yielded no tokens (transcript oversized, without usage turns, or unreadable, #1474) is unpriced — plus every started agent whose stops found no transcript of its own (`start_record_found: true`, `subagent_transcript_found: false`), plus every agent with a schema_version 1 own-transcript record (#1487 Pkt 1) — each of these two only when the agent has no v2 own-transcript record in the session. All three latter kinds have an unknown cost. Phantom stops (no start record, #939) are never candidates. priced < total nulls total_cost_usd.
+ * @property {number}       legacy_v1_records  - Token-bearing records EXCLUDED from every token total above because their schema_version < 2 (their token_input is a different quantity). Their agents are unpriced cost candidates (cost_records_total, #1487 Pkt 1).
  * @property {2}            _token_schema      - The token contract these totals were computed under.
  */
 
@@ -341,13 +347,20 @@ export function rollupSessionTokens({
   const addNonNegative = (acc, value) =>
     typeof value === 'number' && value >= 0 ? (acc ?? 0) + value : acc;
 
-  // Agents with at least one record whose own transcript WAS read. A later stop
-  // of the same agent can find a transcript an earlier one missed (measured
-  // 2026-10-01: 4 agents in one fleet session, `workflow-subagent` found:false
-  // first, then found:true) — its cost is then known and must not null the total.
-  const agentsWithTranscript = new Set(
-    matched.filter(isTokenBearing).map((r) => r.agent_id).filter((id) => typeof id === 'string'),
-  );
+  // Real agents that may have no v2 record of their own transcript — each an
+  // unpriced candidate, counted once: a started agent whose stop found no
+  // transcript (#1475), and an agent seen in a v1 record (#1487 Pkt 1 — v1
+  // carries no priceable buckets). Resolved against `agents` only AFTER the
+  // pass: a later v2 stop of the same agent that found its transcript prices it
+  // (measured 2026-10-01: 4 agents in one fleet session, `workflow-subagent`
+  // found:false first, then found:true) and must not null a known cost. A record
+  // without an agent_id cannot be joined to another and stands alone.
+  const maybeUnpriced = new Set();
+  let unkeyedUnpriced = 0;
+  const addMaybeUnpriced = (record) => {
+    if (record.agent_id === undefined || record.agent_id === null) unkeyedUnpriced += 1;
+    else maybeUnpriced.add(record.agent_id);
+  };
 
   // One agent, one count (see module header § One record per agent). Per agent:
   // `last` is its last stop that found its transcript — the cost candidate —
@@ -358,9 +371,6 @@ export function rollupSessionTokens({
   // cannot be joined to another and stands alone.
   /** @type {Map<unknown, {last: object, lastWithTokens: object|null}>} */
   const agents = new Map();
-  /** Started agents whose stops found no transcript — each counts once. */
-  const startedWithoutTranscript = new Set();
-  let unkeyedStartedWithoutTranscript = 0;
 
   for (const record of matched) {
     // Provenance gate (#949) — a record whose tokens describe the PARENT
@@ -369,28 +379,22 @@ export function rollupSessionTokens({
     // sentinel: a session of only untrustworthy records reports "no data",
     // which is true, instead of a fabricated 0.
     if (!isTokenBearing(record)) {
-      // …but a v2 agent that really ran without a readable transcript has an
+      // …but an agent that really ran without a readable transcript has an
       // unknown cost: an unpriced candidate (total, not priced), so priced <
       // total nulls `total_cost_usd` (#1475). Phantoms never reach this branch.
-      if (
-        isV2(record) &&
-        isStartedWithoutTranscript(record) &&
-        !agentsWithTranscript.has(record.agent_id)
-      ) {
-        if (record.agent_id === undefined || record.agent_id === null) {
-          unkeyedStartedWithoutTranscript += 1;
-        } else {
-          startedWithoutTranscript.add(record.agent_id);
-        }
-      }
+      if (isStartedWithoutTranscript(record)) addMaybeUnpriced(record);
       continue;
     }
 
     // Schema gate (#1244) — a v1 record's token_input is raw uncached input,
     // a different quantity from a v2 record's billable prompt volume. Count it
-    // so the boundary is visible, never sum it.
+    // so the boundary is visible, never sum it. Its agent ran, though, and v1
+    // cannot be priced: it is an unpriced cost candidate (#1487 Pkt 1), so a
+    // session spanning the 2026-09-09 boundary reports a null cost instead of
+    // the v2 half's partial sum.
     if (!isV2(record)) {
       legacyV1 += 1;
+      addMaybeUnpriced(record);
       continue;
     }
 
@@ -452,7 +456,8 @@ export function rollupSessionTokens({
       if (!allZero) sumCost = (sumCost ?? 0) + cost;
     }
   }
-  costTotal += startedWithoutTranscript.size + unkeyedStartedWithoutTranscript;
+  for (const id of maybeUnpriced) if (!agents.has(id)) costTotal += 1;
+  costTotal += unkeyedUnpriced;
 
   return {
     match_status: 'matched',

package/scripts/lib/sessions-staleness-banner.mjs

@@ -192,7 +192,9 @@ const CLOSING_DIAGNOSTIC_EVENTS = new Map([
   // scripts/lib/autopilot/worktree-pipeline.mjs (release_failed/released only).
   ['orchestrator.session.lock.released', null],
   ['orchestrator.session.lock.release_failed', null],
-  // Only emitter: hooks/on-session-end.mjs — reading the lock during teardown.
+  // hooks/on-session-end.mjs — reading the lock during teardown. Since #1494 also
+  // hooks/_lib/lock-bootstrap.mjs at SessionStart (`unreadable` only); skipping that
+  // one too loses nothing, because the same start emits orchestrator.session.started.
   ['orchestrator.session.lock.read_anomaly', null],
   // Wave lifecycle: hooks/post-tool-batch-wave-signal.mjs emits wave.completed MID-session
   // (real activity, still counted); only the SessionEnd final-wave stamp is a closing