session-orchestrator 5.12.0 → 5.13.0

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 = {

package/scripts/lib/session-work-trees.mjs

@@ -0,0 +1,166 @@
+/**
+ * session-work-trees.mjs — which trees did a session commit in, and from which
+ * start ref (#1659).
+ *
+ * `session-start-ref` names ONE sha in ONE tree. A coordinator that commits in
+ * several of its own worktrees (`git -C <wt> commit`, `cd <wt> && git commit`,
+ * subagents committing there) leaves those commits unattributed, and a ref from
+ * a different tree is no fix: a two-dot diff across two trees lists foreign
+ * files. hooks/pre-bash-staging-fence.mjs therefore records, before every
+ * `git commit`, the pair `(tree, start_ref)` as an
+ * `orchestrator.session.work_tree` event in the events ledger. This module is
+ * the reader:
+ *
+ *  - {@link readSessionWorkTrees} — the session's trees, FIRST record per tree
+ *    wins (the writer does not dedupe; every commit appends one record).
+ *  - {@link sessionCommitFiles} — per tree `git diff --name-only <ref>..HEAD`
+ *    INSIDE THAT TREE ONLY. A diff between two different trees is never
+ *    computed.
+ *
+ * Neither function throws. Unreadable ledger lines are COUNTED, not silently
+ * skipped (`.claude/rules/measurement-discipline.md` § Unlesbare JSONL-Zeilen
+ * zaehlen); an unusable tree is reported `skipped` with a reason.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { readEventsWithRotations } from './events.mjs';
+import { SESSION_WORK_TREE_EVENT } from './events-schema.mjs';
+
+/**
+ * Events-ledger window for the #1401 census (`events-retention-banner.mjs`):
+ * `null` — {@link readSessionWorkTrees} reads back to a session's FIRST
+ * `orchestrator.session.work_tree` record, however old, so no day count bounds
+ * it. A cut history loses that tree's first start_ref; the reader then takes
+ * the oldest surviving record for it, which under-reports that tree (#1659).
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = null;
+
+/** Per-git-call timeout. A hung git must not hang a consumer (close, gate). */
+const GIT_TIMEOUT_MS = 10_000;
+
+/** Full sha, SHA-1 or SHA-256 object format. */
+const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+/**
+ * Read the `(tree, start_ref)` pairs one session recorded.
+ *
+ * Only records whose `session_id` EQUALS `sessionId` (the raw harness id — a
+ * dispatched subagent carries the coordinator's raw id, so its commits count
+ * for the coordinator, as intended). The first record per `tree` wins, in
+ * ledger order (rotated archives included, oldest first). A record of the
+ * right event and session but with a missing/invalid `tree` or `start_ref` is
+ * counted in `invalid`, never used.
+ *
+ * @param {object} args
+ * @param {string} args.sessionId — raw session id to match.
+ * @param {string} [args.eventsFile] — explicit active ledger path (wins over repoRoot).
+ * @param {string} [args.repoRoot] — project root whose ledger is read; defaults
+ *   like `eventsFilePath()` (`resolveEventsLedgerRoot()`).
+ * @returns {{ trees: Array<{ tree: string, start_ref: string }>,
+ *             malformed: number, invalid: number, complete: boolean|null,
+ *             error?: string }}
+ *   `malformed` = unreadable ledger lines (all sessions, the reader cannot
+ *   attribute a line it cannot parse); `complete` mirrors
+ *   `readEventsWithRotations` (`null` = no ledger found, NOT "no trees").
+ */
+export function readSessionWorkTrees({ sessionId, eventsFile, repoRoot } = {}) {
+  if (typeof sessionId !== 'string' || sessionId.trim() === '') {
+    return { trees: [], malformed: 0, invalid: 0, complete: null, error: 'sessionId missing' };
+  }
+  let read;
+  try {
+    read = readEventsWithRotations(repoRoot, eventsFile ? { filePath: eventsFile } : {});
+  } catch (err) {
+    return { trees: [], malformed: 0, invalid: 0, complete: null, error: String(err?.message ?? err) };
+  }
+
+  const seen = new Set();
+  const trees = [];
+  let invalid = 0;
+  for (const rec of read.events) {
+    if (rec?.event !== SESSION_WORK_TREE_EVENT || rec.session_id !== sessionId) continue;
+    const { tree, start_ref: startRef } = rec;
+    if (typeof tree !== 'string' || !path.isAbsolute(tree)
+      || typeof startRef !== 'string' || !FULL_SHA_RE.test(startRef)) {
+      invalid += 1;
+      continue;
+    }
+    if (seen.has(tree)) continue; // first record per tree wins (#1659)
+    seen.add(tree);
+    trees.push({ tree, start_ref: startRef });
+  }
+  return { trees, malformed: read.malformed_lines, invalid, complete: read.complete };
+}
+
+/**
+ * Run git with an argv array (no shell) and a timeout; never throws.
+ *
+ * @param {string[]} args
+ * @returns {{ ok: true, stdout: string } | { ok: false, error: string }}
+ */
+function git(args) {
+  try {
+    const stdout = execFileSync('git', args, {
+      encoding: 'utf8',
+      timeout: GIT_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { ok: true, stdout };
+  } catch (err) {
+    const stderr = typeof err?.stderr === 'string' ? err.stderr.trim() : '';
+    return { ok: false, error: stderr || String(err?.message ?? err) };
+  }
+}
+
+/**
+ * Files each tree's commits touched since that tree's own start ref.
+ *
+ * For every `{ tree, start_ref }`: `git -C <tree> diff --name-only
+ * <start_ref>..HEAD`, run in THAT tree with THAT tree's ref — never a diff
+ * between two trees. Paths are tree-relative, as git prints them; `union` is
+ * the deduped, sorted union of those relative paths across trees (trees of the
+ * same repo share a path space).
+ *
+ * A tree whose directory is gone, or whose ref no longer resolves there (gc'd,
+ * different repo), lands in `skipped` with a reason — the caller decides what
+ * an unmeasured tree means; it is never silently dropped and never throws.
+ *
+ * @param {{ trees: Array<{ tree: string, start_ref: string }> }} args
+ * @returns {{ perTree: Array<{ tree: string, start_ref: string, files: string[] }>,
+ *             skipped: Array<{ tree: string, start_ref: string, reason: string }>,
+ *             union: string[] }}
+ */
+export function sessionCommitFiles({ trees } = {}) {
+  const perTree = [];
+  const skipped = [];
+  const union = new Set();
+  for (const entry of Array.isArray(trees) ? trees : []) {
+    const tree = entry?.tree;
+    const startRef = entry?.start_ref;
+    if (typeof tree !== 'string' || typeof startRef !== 'string' || !FULL_SHA_RE.test(startRef)) {
+      skipped.push({ tree: String(tree), start_ref: String(startRef), reason: 'invalid-entry' });
+      continue;
+    }
+    if (!existsSync(tree)) {
+      skipped.push({ tree, start_ref: startRef, reason: 'tree-missing' });
+      continue;
+    }
+    const verify = git(['-C', tree, 'rev-parse', '--verify', '--quiet', `${startRef}^{commit}`]);
+    if (!verify.ok) {
+      skipped.push({ tree, start_ref: startRef, reason: 'ref-unresolvable' });
+      continue;
+    }
+    const diff = git(['-C', tree, 'diff', '--name-only', `${startRef}..HEAD`]);
+    if (!diff.ok) {
+      skipped.push({ tree, start_ref: startRef, reason: `diff-failed: ${diff.error.split('\n')[0]}` });
+      continue;
+    }
+    const files = diff.stdout.split('\n').filter((l) => l !== '');
+    for (const f of files) union.add(f);
+    perTree.push({ tree, start_ref: startRef, files });
+  }
+  return { perTree, skipped, union: [...union].sort() };
+}

package/scripts/lib/sessions-canonical.mjs

@@ -101,6 +101,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { resolveEventsLedgerRoot } from './platform.mjs';
 
 const SESSIONS_REL = ['.orchestrator', 'metrics', 'sessions.jsonl'];
 
@@ -213,6 +214,51 @@ export function isBackfillStub(rec) {
   return !hasWork;
 }
 
+/** Session types a record must carry (or show work) to count as measured. */
+const MEASURED_SESSION_TYPES = new Set(['housekeeping', 'feature', 'deep']);
+
+/**
+ * True when a record is a MEASURED session — one a decision may count:
+ * "sessions", deep share, close rate, staleness, dispatcher ranking, site
+ * numbers, cold-start history. A record is measured when it is a parseable
+ * object, is NOT a backfill stub (`isBackfillStub`), does NOT carry
+ * `_synthetic: true`, and EITHER carries a known `session_type`
+ * (`housekeeping|feature|deep`) OR shows at least one wave/agent.
+ *
+ * Why: 59.1 % of fleet session records are synthetic backfill stubs written by
+ * `hooks/on-session-end.mjs` via `session-close-backfill.mjs::synthesizeRecord`
+ * (`_synthetic: true`, `session_type: 'unknown'`, 0 waves/agents) — measured by
+ * D1 on 2026-10-12 (audit E1, `docs/audits/2026-10-12-portfolio-analyse/`).
+ * `isRealSession` (`session-schema/filters.mjs`) only drops `status:
+ * 'abandoned'`, so a `state-md-completed` stub with `status: 'completed'` still
+ * read as a real session; a stub-only ledger then counted as session history.
+ * This predicate is the narrower READER question; it does not replace
+ * `isRealSession` (whose fail-open contract schema/render readers rely on).
+ * Decision readers use this definition alone, including legacy known-type
+ * records without a completed status. The staleness banner separately retains
+ * unmeasured starts as activity anchors, never as measured completion times.
+ *
+ * CEILING (BV-004): a legacy pre-4.0.0 record with no `session_type` but with
+ * waves counts as measured — waves are evidence of real work, the missing type
+ * is only a schema gap. Conversely a known-type record with 0 waves (a
+ * coordinator-direct housekeeping close) counts too.
+ * Revisit-Trigger: if a writer starts emitting unknown-type records WITH waves
+ * that are not real work, or `_synthetic` records stop carrying 0 waves.
+ *
+ * @param {unknown} rec
+ * @returns {boolean}
+ */
+export function isMeasuredSession(rec) {
+  if (!isRecordObject(rec)) return false;
+  if (isBackfillStub(rec) || rec._synthetic === true) return false;
+  if (MEASURED_SESSION_TYPES.has(rec.session_type)) return true;
+  return (Array.isArray(rec.waves) && rec.waves.length > 0)
+    || rec.total_waves > 0 || rec.total_agents > 0
+    // Legacy records may carry measured agent counts only in agent_summary.
+    || (isRecordObject(rec.agent_summary)
+      && ['complete', 'partial', 'failed', 'spiral'].some((key) => rec.agent_summary[key] > 0));
+}
+
 /**
  * Rule (1), cross-id half (#1443) — drop every backfill stub that shares a
  * non-empty `raw_session_id` with at least one non-stub. A group of stubs only
@@ -463,10 +509,16 @@ export function canonicalizeSessions(records, opts) {
  * so id-less records are counted as-is and only the id-bearing ones go through
  * the identity collapse.
  *
+ * `measuredOnly` drops every record `isMeasuredSession` rejects (backfill
+ * stubs, `_synthetic`, unknown type without work) — for a reader whose count
+ * is a "has this repo real session history?" decision (cold-start, audit E1).
+ *
  * @param {string} raw — full file contents.
+ * @param {object} [opts]
+ * @param {boolean} [opts.measuredOnly=false]
  * @returns {number}
  */
-export function countSessionsInJsonl(raw) {
+export function countSessionsInJsonl(raw, { measuredOnly = false } = {}) {
   if (typeof raw !== 'string' || raw.length === 0) return 0;
   const parsed = [];
   for (const line of raw.split('\n')) {
@@ -479,6 +531,12 @@ export function countSessionsInJsonl(raw) {
     }
   }
   const identified = parsed.filter((r) => isRecordObject(r) && isNonEmptyString(r.session_id));
+  if (measuredOnly) {
+    const anonymousMeasured = parsed.filter(
+      (r) => isMeasuredSession(r) && !isNonEmptyString(r.session_id),
+    ).length;
+    return canonicalizeSessions(identified).filter(isMeasuredSession).length + anonymousMeasured;
+  }
   const anonymous = parsed.length - identified.length;
   return canonicalizeSessions(identified).length + anonymous;
 }
@@ -515,7 +573,7 @@ export function countSessionsInJsonl(raw) {
  *
  * @param {object} [args]
  * @param {string} [args.repoRoot] project root; the ledger is resolved as
- *   `<repoRoot>/.orchestrator/metrics/sessions.jsonl`. Defaults to
+ *   the main checkout's `.orchestrator/metrics/sessions.jsonl`. Defaults to
  *   `process.cwd()` when neither this nor `filePath` is given.
  * @param {string} [args.filePath] explicit ledger path (wins over `repoRoot`).
  * @returns {Array<object>} canonical records
@@ -523,7 +581,7 @@ export function countSessionsInJsonl(raw) {
 export function readCanonicalSessions({ repoRoot, filePath } = {}) {
   const resolved = isNonEmptyString(filePath)
     ? filePath
-    : path.join(isNonEmptyString(repoRoot) ? repoRoot : process.cwd(), ...SESSIONS_REL);
+    : path.join(resolveEventsLedgerRoot(isNonEmptyString(repoRoot) ? repoRoot : process.cwd()), ...SESSIONS_REL);
 
   let raw;
   try {