session-orchestrator 5.11.0 → 5.13.0

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 {

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

@@ -22,39 +22,13 @@
  * entry point that is COMPLETELY try/catch-wrapped (never throws) and returns
  * either `null` (silent no-op) or `{severity:'warn'|'alert', message, ...extra}`.
  *
- * TWO VALIDATORS OVER ONE STORE — why this banner reports both populations.
- * The repo has two independent notions of "a valid session record", and
- * neither one contains the other:
- *
- *   - `validateSession()` (`scripts/lib/session-schema/validator.mjs`) — the
- *     canonical write-path schema, enforced by `scripts/emit-session.mjs`.
- *     It treats `effectiveness` as OPTIONAL/nullable — since #964 declared
- *     explicitly in `OPTIONAL_FIELDS` (`session-schema/constants.mjs`) rather
- *     than inferable only from an `if` — so a record vault-mirror refuses to
- *     render can pass it cleanly.
- *   - vault-mirror's render path — its own, differently-shaped requirement
- *     set (`RENDERABLE_SESSION_FIELDS_V1` / `_V2` / `_V3`, exported from
- *     `scripts/lib/vault-mirror/render-sessions.mjs` and consumed by the
- *     matching `generateSessionNote*` generator, routed by
- *     `detectSessionSchema`), which REQUIRES `effectiveness` to be present.
- *     A record can therefore be schema-valid and still get no vault note.
- *     Since #964 those lists are module-scope and pinned to the write-path
- *     schema by a mechanical superset test (v1 ⊇ `REQUIRED_FIELDS`, with
- *     measured carve-outs for the write-unreachable v2/v3) — so "renderable"
- *     is now a stated strengthening of "schema-valid" rather than an
- *     undeclared second opinion. That relationship is exactly why BOTH
- *     populations still have to be reported: a superset can still exclude.
- *
- * Reporting one population would hide the other, so the banner names both and
- * attributes each to its own consequence.
- *
- * Live ledger at HEAD 730ee9d (measured 2026-08-03; 205 parseable records,
- * 146 of them `status: 'abandoned'`, all 205 routing to the v1 generator):
- * `validateSession` fails 0, vault-mirror render fails 10 — and all 10 of
- * those are abandoned, i.e. discarded by the #909 filter BEFORE the render
- * path (see `mirrorSkipReason` below), so the banner is correctly silent
- * here. The counts move as the ledger grows; treat them as a dated
- * measurement, never as an invariant — re-run the probe before quoting them.
+ * TWO CONTRACTS OVER ONE STORE — the banner reports schema failures and
+ * actual mirror failures independently. Effectiveness is optional/nullable in
+ * both contracts (#1575); its absence now renders unknown metrics instead of
+ * losing a note. Legacy V2/V3 shapes remain outside the canonical writer's
+ * schema even when the mirror renders them. A renderer-only failure does not
+ * prove the record bypassed the writer, so the remedy must name the observed
+ * failure rather than infer its provenance.
  *
  * The vault-mirror population is measured by CALLING THE REAL RENDER PATH in
  * a try/catch — never by re-deriving its required-field list here. A third
@@ -92,6 +66,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
+import { resolveEventsLedgerRoot } from './platform.mjs';
 import { isRealSession } from './session-schema/filters.mjs';
 import { validateSession } from './session-schema/validator.mjs';
 import {
@@ -224,7 +199,9 @@ export function checkSessionsIntegrity({ repoRoot } = {}) {
   try {
     if (!repoRoot || typeof repoRoot !== 'string') return null;
 
-    const lines = readJsonlLines(path.join(repoRoot, SESSIONS_PATH));
+    // #1592: the repo's ONE ledger — the main checkout's for a linked worktree,
+    // where every writer appends. The worktree has none since #1584.
+    const lines = readJsonlLines(path.join(resolveEventsLedgerRoot(repoRoot), SESSIONS_PATH));
     if (lines === null || lines.length === 0) return null;
 
     /** @type {{line: number, sessionId: string, error: string}[]} */
@@ -284,11 +261,12 @@ export function checkSessionsIntegrity({ repoRoot } = {}) {
       );
     }
 
-    const base =
-      `sessions-integrity: ${parts.join('; ')} — records were appended without passing ` +
-      `scripts/emit-session.mjs (which validates and would have refused). ` +
-      `Inspect: node -e with validateSession from scripts/lib/session-schema/validator.mjs; ` +
-      `re-emit affected records via scripts/emit-session.mjs`;
+    const remedy = schemaInvalid.length > 0
+      ? 'Inspect schema-invalid records with validateSession; preview repairs with ' +
+        'node scripts/repair-invalid-sessions.mjs --dry-run; absolute --apply requires ' +
+        'an explicit --repo-root equal to the canonical current Git top-level (no trailing slash or ..)'
+      : 'Inspect the reported vault-mirror rendering errors; schema-valid records need no schema repair';
+    const base = `sessions-integrity: ${parts.join('; ')} — ${remedy}`;
 
     const message = severity === 'alert' ? `🚨 ${base}.` : `⚠ ${base}.`;
 

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

@@ -146,7 +146,8 @@ import path from 'node:path';
 import { eventsFilePath } from './events.mjs';
 import { readLock, DEFAULT_TTL_HOURS } from './session-lock.mjs';
 import { isRealSession } from './session-schema/filters.mjs';
-import { readCanonicalSessions } from './sessions-canonical.mjs';
+import { isMeasuredSession, readCanonicalSessions } from './sessions-canonical.mjs';
+import { resolveEventsLedgerRoot } from './platform.mjs';
 
 /** Repo-relative path to the session ledger (one record per closed session). */
 const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
@@ -238,11 +239,12 @@ function readJsonlLines(filePath) {
 }
 
 /**
- * True when a `sessions.jsonl` record is a backfill STUB — a reconstruction
- * whose `completed_at` is never an anchor candidate (module header,
+ * True when a `sessions.jsonl` record cannot supply a measured completion —
+ * unmeasured records retain only their `started_at` activity anchor (module header,
  * "Backfill-stub self-erasure fix").
  *
- * `isRealSession()` (`./session-schema/filters.mjs`) catches `status:
+ * `isMeasuredSession()` supplies the shared measured population. The legacy
+ * anchor rule also catches `status:
  * 'abandoned'`, the canonical phantom marker. A `_backfill_source` counts only
  * when the status is not `completed`: the `state-md-completed` supersede record
  * is the session's own completion claim. Same exclusion as
@@ -259,6 +261,7 @@ function readJsonlLines(filePath) {
  * @returns {boolean}
  */
 function isNonAnchorStub(record) {
+  if (!isMeasuredSession(record)) return true;
   if (!isRealSession(record)) return true;
   return typeof record._backfill_source === 'string' && record._backfill_source.length > 0
     && record.status !== 'completed';
@@ -515,7 +518,7 @@ export function checkSessionsStaleness({ repoRoot, now = Date.now() } = {}) {
 
     const nowMs = typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
 
-    const sessionsPath = path.join(repoRoot, SESSIONS_PATH);
+    const sessionsPath = path.join(resolveEventsLedgerRoot(repoRoot), SESSIONS_PATH);
     const sessionLines = readJsonlLines(sessionsPath);
     if (sessionLines === null || sessionLines.length === 0) return null;
 

package/scripts/lib/sh-quote.mjs

@@ -1,5 +1,6 @@
 /**
  * sh-quote.mjs — the one POSIX shell-quoting helper (#1438).
+ * POSIX-only: this helper does not quote cmd.exe commands.
  *
  * Four byte-identical private copies (cursor-install, tmux-layout/layouts,
  * tmux-layout/tmux-shell, run-quality-gate) and one inline copy

package/scripts/lib/skill-evidence-window.mjs

@@ -53,6 +53,7 @@ import { join } from 'node:path';
 import { createInterface } from 'node:readline';
 
 import { readLock, isLockLive } from './session-lock.mjs';
+import { readProcessLocalSessionIds } from './session-identity/own-session.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants (every ceiling named, per .claude/rules/build-value.md BV-004)
@@ -693,7 +694,10 @@ export function resolveRawSessionId({ repoRoot, env = process.env } = {}) {
   }
   if (!lock || !isLockLive(lock)) return null;
   const fromLock = typeof lock.session_id === 'string' ? lock.session_id.trim() : '';
-  return fromLock ? { sessionId: fromLock, source: 'session.lock' } : null;
+  // The repo-global lock may name a PEER (#1664, class #1663): count it only
+  // when it is among this process's own ids, never as a bare fallback.
+  if (!fromLock || !readProcessLocalSessionIds({ env }).includes(fromLock)) return null;
+  return { sessionId: fromLock, source: 'session.lock' };
 }
 
 /**

package/scripts/lib/skill-health/join.mjs

@@ -34,17 +34,17 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { isRealSession } from '../session-schema/filters.mjs';
-import { readCanonicalSessions } from '../sessions-canonical.mjs';
+import { isMeasuredSession, readCanonicalSessions } from '../sessions-canonical.mjs';
+import { resolveEventsLedgerRoot } from '../platform.mjs';
 
 const DEFAULT_INVOCATIONS_PATH = path.resolve(
   fileURLToPath(import.meta.url),
   '../../../../.orchestrator/metrics/skill-invocations.jsonl',
 );
 
-const DEFAULT_SESSIONS_PATH = path.resolve(
-  fileURLToPath(import.meta.url),
-  '../../../../.orchestrator/metrics/sessions.jsonl',
+const DEFAULT_SESSIONS_PATH = path.join(
+  resolveEventsLedgerRoot(fileURLToPath(new URL('../../../', import.meta.url))),
+  '.orchestrator', 'metrics', 'sessions.jsonl',
 );
 
 /**
@@ -78,8 +78,8 @@ async function readJsonl(filePath) {
 /**
  * Builds a Map<session_id, { agentSummary, real }> from sessions.jsonl records.
  * Records without a session_id or with a non-object agent_summary are skipped.
- * `real` is false for phantom `status: 'abandoned'` stubs (#834) — callers use
- * it to route the join to the `abandoned` outcome bucket instead of counting
+ * `real` uses the shared measured-session definition (#1584) — callers use
+ * it to route unmeasured joins to the legacy `abandoned` outcome bucket instead of counting
  * a zero-signal join as `sessionsJoined`.
  *
  * Callers pass `sessionRecords` from `readCanonicalSessions()` (#1209b) — one
@@ -99,7 +99,7 @@ function buildSessionMap(sessionRecords) {
   for (const rec of sessionRecords) {
     if (typeof rec.session_id !== 'string' || !rec.session_id) continue;
     if (rec.agent_summary && typeof rec.agent_summary === 'object') {
-      map.set(rec.session_id, { agentSummary: rec.agent_summary, real: isRealSession(rec) });
+      map.set(rec.session_id, { agentSummary: rec.agent_summary, real: isMeasuredSession(rec) });
     }
   }
   return map;
@@ -186,9 +186,10 @@ export async function joinSkillOutcomes({
           record.outcomes.spiral += typeof summary.spiral === 'number' ? summary.spiral : 0;
           sessionsJoined += 1;
         } else if (entry && !entry.real) {
-          // Found in sessions.jsonl but a phantom abandoned stub (#834) — a
+          // Found in sessions.jsonl but unmeasured (#1584) — a
           // zero-signal join. Route to a distinct bucket instead of inflating
           // sessionsJoined or conflating with "not found at all" (unknown).
+          // Keep the legacy output keys; this bucket includes completed synthetic stubs.
           record.outcomes.abandoned += 1;
           sessionsAbandoned += 1;
         } else {

package/scripts/lib/skill-invocations-schema.mjs

@@ -22,6 +22,7 @@
 import { readFile, appendFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { resolveLedgerPath } from './ledger-path.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -36,6 +37,18 @@ export const VALID_EVENTS = Object.freeze(['selected']);
 /** Default JSONL path for skill invocation records. */
 export const DEFAULT_SKILL_INVOCATIONS_PATH = '.orchestrator/metrics/skill-invocations.jsonl';
 
+/**
+ * Absolute path of the skill-invocations ledger for a writer or reader rooted
+ * at `root` (#1722): the main checkout's copy when `root` is a linked worktree
+ * of a repo that ignores the ledger, otherwise `<root>/` + the default path.
+ *
+ * @param {string} [root]  repo root; default `getProjectDir()`
+ * @returns {string}
+ */
+export function defaultSkillInvocationsPath(root) {
+  return resolveLedgerPath(DEFAULT_SKILL_INVOCATIONS_PATH, root);
+}
+
 // ---------------------------------------------------------------------------
 // ValidationError
 // ---------------------------------------------------------------------------

package/scripts/lib/skill-judgments-schema.mjs

@@ -29,6 +29,7 @@
 import { readFile, appendFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { resolveLedgerPath } from './ledger-path.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -215,7 +216,10 @@ export function normalizeSkillJudgment(entry) {
  * @returns {Promise<object>} the validated + normalized entry that was written
  * @throws {ValidationError} when the entry fails schema validation
  */
-export async function appendSkillJudgment(record, { path: filePath = DEFAULT_SKILL_JUDGMENTS_PATH } = {}) {
+export async function appendSkillJudgment(
+  record,
+  { path: filePath = resolveLedgerPath(DEFAULT_SKILL_JUDGMENTS_PATH, process.cwd()) } = {},
+) {
   const stamped = {
     ...record,
     schema_version: record?.schema_version ?? CURRENT_SCHEMA_VERSION,
@@ -241,7 +245,7 @@ export async function appendSkillJudgment(record, { path: filePath = DEFAULT_SKI
  * @param {string} [filePath] — absolute path to target .jsonl file
  * @returns {Promise<object[]>} array of normalized skill-judgment records
  */
-export async function readSkillJudgments(filePath = DEFAULT_SKILL_JUDGMENTS_PATH) {
+export async function readSkillJudgments(filePath = resolveLedgerPath(DEFAULT_SKILL_JUDGMENTS_PATH, process.cwd())) {
   if (!existsSync(filePath)) return [];
   let raw;
   try {