session-orchestrator 5.12.0 → 5.13.0

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 {