session-orchestrator 3.23.0 → 4.0.0

package/hooks/skill-invocation-telemetry.mjs

@@ -33,7 +33,7 @@ import { spawn } from 'node:child_process';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { appendSkillInvocation } from '../scripts/lib/skill-invocations-schema.mjs';
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { shouldDailyFlush } from '../scripts/lib/telemetry/sync.mjs';
 import { resolveConsent, readTelemetryState } from '../scripts/lib/telemetry/consent.mjs';
 import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
@@ -42,9 +42,21 @@ import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
 // Constants
 // ---------------------------------------------------------------------------
 
-const METRICS_DIR = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics');
+/**
+ * Metrics directory / ledger path. FUNCTIONS, not module-level consts:
+ * `getProjectDir()` walks the filesystem on first call, and this hook must not
+ * pay that at import time (#1153 P5).
+ *
+ * @returns {string}
+ */
+function metricsDirPath() {
+  return path.join(getProjectDir(), '.orchestrator', 'metrics');
+}
 
-const JSONL_PATH = path.join(METRICS_DIR, 'skill-invocations.jsonl');
+/** @returns {string} */
+function jsonlPath() {
+  return path.join(metricsDirPath(), 'skill-invocations.jsonl');
+}
 
 /** Absolute path to the telemetry CLI (carries the hidden `_flush` subcommand). */
 const TELEMETRY_CLI_PATH = path.resolve(
@@ -123,7 +135,7 @@ export function maybeSpawnDailyFlush({
   now = Date.now(),
   statePath,
   queuePath,
-  metricsDir = METRICS_DIR,
+  metricsDir = metricsDirPath(),
 } = {}) {
   try {
     // 1. Cheapest gate: env kill-switches, no file I/O.
@@ -187,7 +199,7 @@ async function main() {
     schema_version: 1,
   };
 
-  await appendSkillInvocation(JSONL_PATH, record);
+  await appendSkillInvocation(jsonlPath(), record);
 
   // Daily-fallback telemetry flush — non-blocking, best-effort, never throws.
   maybeSpawnDailyFlush();

package/hooks/subagent-telemetry.mjs

@@ -84,13 +84,23 @@ if (!shouldRunHook('subagent-telemetry')) process.exit(0);
 import fs from 'node:fs';
 import path from 'node:path';
 import { appendSubagent } from '../scripts/lib/subagents-schema.mjs';
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
+import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const JSONL_PATH = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics', 'subagents.jsonl');
+/**
+ * Absolute path to the subagent ledger. A FUNCTION, not a module-level const:
+ * `getProjectDir()` walks the filesystem on first call, and this hook must not
+ * pay that at import time (#1153 P5).
+ *
+ * @returns {string}
+ */
+function jsonlPath() {
+  return path.join(getProjectDir(), '.orchestrator', 'metrics', 'subagents.jsonl');
+}
 
 /**
  * Defense-in-depth byte ceiling for transcript reads (#624). The transcript path
@@ -489,38 +499,22 @@ function extractTranscriptUsage(transcriptPath) {
  * Derive the path of the subagent's OWN transcript from the parent transcript
  * path the harness sends on stdin (#949).
  *
- * The `transcript_path` in a SubagentStop payload is the PARENT session
- * transcript — `<transcriptDir>/<parent_session_id>.jsonl`. Alongside it the
- * harness maintains one file per real Task subagent at
- * `<transcriptDir>/<parent_session_id>/subagents/agent-<agent_id>.jsonl`
- * (plus an `agent-<agent_id>.meta.json` carrying `agentType`). Verified against
- * live transcripts on 2026-07-31.
- *
- * Returns null — never the parent path — when the derivation is not possible.
- * Falling back to `transcript_path` IS the #949 defect: it makes every stop
- * inherit the parent's running token totals, so the caller must record null
- * instead (an honest absence).
- *
- * The agent_id is charset-restricted before it is interpolated into a path.
- * Real ids are hex-ish tokens (e.g. `a60348a01ca982b4c`); anything else is
- * rejected rather than sanitised, so no payload value can traverse out of the
- * `subagents/` directory.
+ * Thin wrapper over the consolidated derivation (#1196) —
+ * `hooks/_lib/subagent-paths.mjs` `resolveSubagentSidecar()` — which now
+ * applies a `{1,64}` bound to `agentId` (STRICTER than this file's prior
+ * unbounded `+` charset check; see that module's header for the full
+ * divergence table). Returns null — never the parent path — when the
+ * derivation is not possible. Falling back to `transcript_path` IS the #949
+ * defect: it makes every stop inherit the parent's running token totals, so
+ * the caller must record null instead (an honest absence).
  *
  * @param {string|undefined|null} parentTranscriptPath — stdin `transcript_path`
  * @param {string} agentId — the stopping agent's id
  * @returns {string|null} absolute candidate path, or null when underivable
  */
 function resolveSubagentTranscriptPath(parentTranscriptPath, agentId) {
-  if (typeof parentTranscriptPath !== 'string' || !parentTranscriptPath.trim()) return null;
-  if (typeof agentId !== 'string' || !/^[A-Za-z0-9_-]+$/.test(agentId)) return null;
-  // 'unknown' is the no-usable-id fallback — it names no file.
-  if (agentId === 'unknown') return null;
-
-  const dir = path.dirname(parentTranscriptPath);
-  const base = path.basename(parentTranscriptPath).replace(/\.jsonl$/i, '');
-  if (!base || base === '.' || base === '..') return null;
-
-  return path.join(dir, base, 'subagents', `agent-${agentId}.jsonl`);
+  const sidecar = resolveSubagentSidecar({ transcriptPath: parentTranscriptPath, agentId });
+  return sidecar === null ? null : sidecar.transcript;
 }
 
 /**
@@ -684,7 +678,7 @@ async function main() {
     // duration measurement and the explicit orphan discriminator below.
     // 'unknown' is the agent-id fallback for a payload with no usable id —
     // joining on it would collide across unrelated agents, so never scan for it.
-    const startedAtMs = agentId === 'unknown' ? null : findStartTimestampMs(JSONL_PATH, agentId);
+    const startedAtMs = agentId === 'unknown' ? null : findStartTimestampMs(jsonlPath(), agentId);
 
     // duration_ms (#917): prefer the harness value, else join backwards to this
     // agent's own start record, else null. Never 0 — see resolveDurationMs().
@@ -732,7 +726,7 @@ async function main() {
     record['gen_ai.system'] = 'anthropic';
   }
 
-  await appendSubagent(JSONL_PATH, record);
+  await appendSubagent(jsonlPath(), record);
 }
 
 // Exit 0 always — informational hook must never block Claude.

package/monitors/monitors.json

@@ -2,13 +2,13 @@
   {
     "name": "ecosystem-health",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/ecosystem-health.mjs --watch",
-    "description": "Ecosystem repo health watcher (CI status, branch drift, stale baselines across vault-registered projects). Emits one NDJSON line per detected state change.",
-    "when": "on-skill-invoke:ecosystem-health"
+    "description": "Ecosystem repo health watcher (CI status, branch drift, stale baselines across vault-registered projects). Emits one NDJSON line per detected state change. Hung on session-start because the previous trigger (on-skill-invoke:ecosystem-health) was self-referential: it could only start when the ecosystem-health skill ran, and that skill has 0 recorded invocations fleet-wide, so the watcher never started once.",
+    "when": "on-skill-invoke:session-start"
   },
   {
     "name": "convergence-monitor",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/convergence-monitor.mjs --tail",
-    "description": "Wave convergence telemetry monitor — tails .orchestrator/metrics/events.jsonl + sessions.jsonl, surfaces convergence signals (shrinking diff, pass-rate plateau, velocity).",
+    "description": "Wave convergence telemetry monitor — tails .orchestrator/metrics/events.jsonl (that file only; it never opens sessions.jsonl) and surfaces convergence signals (shrinking diff, pass-rate plateau, velocity).",
     "when": "on-skill-invoke:wave-executor"
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "3.23.0",
+  "version": "4.0.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -23,7 +23,9 @@
   },
   "files": [
     ".mcp.json",
+    "AGENTS.md",
     "CHANGELOG.md",
+    "plugin.json",
     "pi/",
     "skills/",
     "agents/",
@@ -37,11 +39,14 @@
     "assets/",
     ".claude-plugin/",
     ".codex-plugin/",
+    ".agents/",
     ".cursor/",
+    ".orchestrator/policy/",
     "docs/*.md",
     "docs/telemetry/telemetry-claims.md",
     "NOTICE",
     "SECURITY.md",
+    "!skills/vault-sync/package-lock.json",
     "!scripts/tests/**",
     "!skills/vault-sync/tests/**",
     "!**/node_modules/**",
@@ -66,9 +71,12 @@
     "ajv": "^8.17.1",
     "js-yaml": "^4.3.1",
     "mdast-util-to-string": "^4.0.0",
+    "picomatch": "^4.0.4",
     "remark": "^15.0.0",
     "remark-parse": "^11.0.0",
     "unified": "^11.0.0",
+    "yaml": "^2.9.0",
+    "zod": "^3.25.76",
     "zx": "^8.1.0"
   },
   "devDependencies": {

package/pi/prompts/session.md

@@ -1,6 +1,6 @@
 ---
-description: Start a development session (housekeeping, feature, deep)
-argument-hint: "[housekeeping|feature|deep]"
+description: Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)
+argument-hint: "[housekeeping|feature|deep|ultradeep]"
 ---
 
 # /session

package/plugin.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "session-orchestrator",
+  "version": "4.0.0",
+  "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
+  "author": {
+    "name": "Bernhard Goetzendorfer"
+  },
+  "homepage": "https://session-orchestrator.com",
+  "repository": "https://github.com/Kanevry/session-orchestrator",
+  "license": "MIT",
+  "keywords": [
+    "session",
+    "orchestration",
+    "waves",
+    "gitlab",
+    "github",
+    "quality-gates",
+    "verification-gates",
+    "multi-agent",
+    "codex",
+    "cursor",
+    "pi"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json"
+}

package/scripts/autopilot.mjs

@@ -47,6 +47,7 @@ import { selectMode } from './lib/mode-selector.mjs';
 import { probe, evaluate, DEFAULT_RESOURCE_THRESHOLDS } from './lib/resource-probe.mjs';
 import { detectPeers } from './lib/session-registry.mjs';
 import { normalizeSession } from './lib/session-schema.mjs';
+import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 // ---------------------------------------------------------------------------
 // CLI-level flag extraction
@@ -174,17 +175,29 @@ const branch = detectBranch();
 const SESSIONS_JSONL_PATH = resolve('.orchestrator/metrics/sessions.jsonl');
 
 /**
- * Count the number of non-empty lines in sessions.jsonl. Returns 0 if missing.
- * @returns {number}
+ * Set of the DISTINCT session identities currently recorded in sessions.jsonl.
+ * Empty set when the file is missing or unreadable.
+ *
+ * Identities, not lines (#1167): the ledger is append-only, so one physical
+ * session can occupy two lines (an abandoned stub plus the authoritative
+ * record that supersedes it, or the systemic double-stub pair). The
+ * pre/post comparison below asks "did the session I just spawned record
+ * itself?", and a raw line count answers that question wrong in BOTH
+ * directions — a duplicate pair looks like two sessions, while a supersede
+ * append (+1 line, −1 stub) leaves a canonical COUNT unchanged. Comparing the
+ * id SETS is immune to both.
+ *
+ * @returns {Set<string>}
  */
-function countSessionLines() {
-  if (!existsSync(SESSIONS_JSONL_PATH)) return 0;
-  try {
-    const raw = readFileSync(SESSIONS_JSONL_PATH, 'utf8');
-    return raw.split('\n').filter((l) => l.trim().length > 0).length;
-  } catch {
-    return 0;
+function readSessionIds() {
+  if (!existsSync(SESSIONS_JSONL_PATH)) return new Set();
+  const ids = new Set();
+  for (const rec of readCanonicalSessions({ filePath: SESSIONS_JSONL_PATH })) {
+    if (typeof rec.session_id === 'string' && rec.session_id.length > 0) {
+      ids.add(rec.session_id);
+    }
   }
+  return ids;
 }
 
 /**
@@ -249,7 +262,7 @@ async function modeSelector() {
  * @returns {Promise<{session_id: string, agent_summary?: object, effectiveness?: object}>}
  */
 async function sessionRunner({ mode, autopilotRunId }) {
-  const preCount = countSessionLines();
+  const preIds = readSessionIds();
 
   await new Promise((res, rej) => {
     const childStdio = hasVerbose
@@ -281,8 +294,9 @@ async function sessionRunner({ mode, autopilotRunId }) {
     });
   });
 
-  const postCount = countSessionLines();
-  if (postCount === preCount) {
+  const postIds = readSessionIds();
+  const appeared = [...postIds].some((id) => !preIds.has(id));
+  if (!appeared) {
     throw new Error('no session record appended');
   }
 

package/scripts/backfill-abandoned-sessions.mjs

@@ -42,10 +42,12 @@ import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
-import { SO_PROJECT_DIR } from './lib/platform.mjs';
+import { emitEvent } from './lib/events.mjs';
+import { getProjectDir } from './lib/platform.mjs';
 
 const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
+const SESSION_ENDED = 'orchestrator.session.ended';
 
 /**
  * Default cap on how many candidates may reach the (expensive) shared core in a
@@ -54,12 +56,31 @@ const SESSION_STARTED = 'orchestrator.session.started';
  */
 export const SESSION_START_LIMIT = 25;
 
-/** Read a JSONL file into parsed objects; missing → []; malformed lines skipped. */
+/**
+ * Read a JSONL file into parsed objects; MISSING (ENOENT) → `[]` silently,
+ * UNREADABLE (EACCES/EISDIR/…) → `[]` with a stderr WARN (#1188); malformed
+ * lines skipped.
+ */
 function readJsonl(filePath) {
   let raw;
   try {
     raw = fs.readFileSync(filePath, 'utf8');
-  } catch {
+  } catch (err) {
+    // #1188 — ENOENT and EACCES/EISDIR are different facts: a missing ledger is
+    // the ordinary fresh-repo case; an UNREADABLE one previously read as "no
+    // records" and made every downstream count silently wrong. Same split as
+    // readLockDetailed (session-lock.mjs § absent vs unreadable).
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write(
+        `⚠ backfill-abandoned-sessions: cannot read ${filePath} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+          'treating as EMPTY, counts below are floors\n',
+      );
+    }
+    // CEILING (BV-004): still [] rather than throw — this runs on the
+    // SessionStart path (SESSION_START_LIMIT), where a permissions fault must
+    // not crash the session start. REVISIT if the warn rate in events.jsonl
+    // shows masked corruption.
     return [];
   }
   const out = [];
@@ -86,16 +107,22 @@ function readJsonl(filePath) {
 export function planSessions({ repoRoot }) {
   const events = readJsonl(path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl'));
 
-  const semanticByUuid = new Map();
+  // Two independent UUID -> semantic bridges (#1167). `lock.acquired` is the
+  // original one, but a session that LOST the lock-acquire race never emits it;
+  // its `session.ended` event carries `semantic_session_id` all the same (since
+  // #1068 AC1) and was never read here. Without that second bridge the
+  // candidate resolved semantic=null and the shared core minted a SYNTHETIC id,
+  // writing a duplicate stub beside the record the SessionEnd hook had already
+  // written under the real semantic id (measured 2026-09-02 @ c3ab480: 8 pairs).
+  // lock.acquired keeps precedence — it is the older, mode-carrying attestation.
+  const semanticFromLock = new Map();
+  const semanticFromEnded = new Map();
   for (const ev of events) {
-    if (
-      ev.event === LOCK_ACQUIRED &&
-      typeof ev.session_id === 'string' &&
-      typeof ev.semantic_session_id === 'string'
-    ) {
-      semanticByUuid.set(ev.session_id, ev.semantic_session_id);
-    }
+    if (typeof ev.session_id !== 'string' || typeof ev.semantic_session_id !== 'string') continue;
+    if (ev.event === LOCK_ACQUIRED) semanticFromLock.set(ev.session_id, ev.semantic_session_id);
+    else if (ev.event === SESSION_ENDED) semanticFromEnded.set(ev.session_id, ev.semantic_session_id);
   }
+  const semanticByUuid = new Map([...semanticFromEnded, ...semanticFromLock]);
 
   const seen = new Set();
   const plan = [];
@@ -133,7 +160,14 @@ function readRecordedIds(repoRoot) {
   const records = readJsonl(path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl'));
   const ids = new Set();
   for (const r of records) {
-    if (r && typeof r.session_id === 'string') ids.add(r.session_id);
+    if (!r) continue;
+    if (typeof r.session_id === 'string') ids.add(r.session_id);
+    // #1167 — a backfilled record now stamps the harness UUID it was
+    // reconstructed from. Indexing it lets a bare-UUID candidate be recognised
+    // as already-recorded even though the record itself is keyed semantically —
+    // the join that was structurally impossible while the field was absent
+    // (0 of 286 records carried it, measured 2026-09-02 @ c3ab480).
+    if (typeof r.raw_session_id === 'string') ids.add(r.raw_session_id);
   }
   return ids;
 }
@@ -238,6 +272,7 @@ export async function runMigration({
       case 'backfilled':
         summary.backfilled += 1;
         if (res.deadByAge) summary.dead_by_age += 1;
+        await emitBackfillCompleted(repoRoot, item, res);
         // Keep the pre-filter snapshot in step with what we just wrote, so a
         // second candidate bridging to the SAME semantic id is skipped cheaply
         // instead of re-entering the core (which would reach the same verdict).
@@ -263,6 +298,40 @@ export async function runMigration({
   return summary;
 }
 
+/**
+ * Emit `orchestrator.session.backfill_completed` for a record THIS path wrote
+ * (#1167). Mirrors the payload of `hooks/on-session-end.mjs::emitBackfillOutcome`
+ * so both writers are queryable with one filter.
+ *
+ * Until now the startup/CLI path wrote records SILENTLY: only the SessionEnd
+ * hook emitted the event, so nothing in the event stream distinguished "the
+ * backfill never ran" from "the backfill ran here". Best-effort by contract —
+ * observability must never fail a migration run.
+ *
+ * @param {string} repoRoot
+ * @param {{sessionId: string, semanticSessionId: string|null}} item
+ * @param {{action: string, sessionId?: string, supersedes?: string, error?: string}} res
+ */
+async function emitBackfillCompleted(repoRoot, item, res) {
+  try {
+    await emitEvent(
+      'orchestrator.session.backfill_completed',
+      {
+        kind: 'abandoned',
+        action: typeof res?.action === 'string' ? res.action : 'unknown',
+        ...(typeof item?.sessionId === 'string' ? { session_id: item.sessionId } : {}),
+        ...(typeof item?.semanticSessionId === 'string'
+          ? { semantic_session_id: item.semanticSessionId }
+          : {}),
+        ...(typeof res?.sessionId === 'string' ? { record_id: res.sessionId } : {}),
+        ...(typeof res?.supersedes === 'string' ? { supersedes: res.supersedes } : {}),
+        ...(typeof res?.error === 'string' ? { reason: res.error } : {}),
+      },
+      { repoRoot },
+    );
+  } catch { /* observability is best-effort */ }
+}
+
 /**
  * SessionStart entry point (#926) — decouple the backfill from the /close path.
  *
@@ -313,13 +382,59 @@ export async function backfillOnSessionStart({ repoRoot, limit = SESSION_START_L
     if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
     // newestFirst is mandatory here — see runMigration's param docs for the
     // measured failure (budget burned on ancient already-recorded candidates).
-    return await runMigration({ repoRoot, apply: true, limit, newestFirst: true });
+    const summary = await runMigration({ repoRoot, apply: true, limit, newestFirst: true });
+    // The telemetry flush rides the SAME start-time trigger, for the same reason
+    // the backfill does — see flushTelemetryOnSessionStart.
+    await flushTelemetryOnSessionStart(repoRoot);
+    return summary;
   } catch {
     // Swallowed by contract — see the docblock. The hook is informational-only.
     return null;
   }
 }
 
+/** POST budget for the start-time telemetry drain (ms). Deliberately tighter than
+ *  the close-time budget: a session START must not wait on the network. Expiry is
+ *  LOSSLESS — flush() routes a timed-out batch into the offline queue. */
+const STARTUP_FLUSH_TIMEOUT_MS = 1500;
+
+/**
+ * SECOND FLUSH TRIGGER (GitLab #1234) — drain the PREVIOUS session's telemetry
+ * queue at the NEXT session's start.
+ *
+ * THE BUG THIS FIXES: the mechanical flush (#1138) lives only in
+ * `hooks/on-session-end.mjs`, which fires on a REGULAR close. Measured 2026-09-06
+ * over 90 fleet days, the real close rate is 21,3 % (429 clean closes / 2.016
+ * distinct `session.started` ids) — so roughly four sessions in five never reach
+ * the only code path that sends. This is the exact argument
+ * `backfillOnSessionStart` already makes for the ledger, applied to the ping:
+ * SessionStart is the trigger that survives whatever killed the last session.
+ *
+ * Three properties make this safe to run on the hot start path:
+ *  - LAZY IMPORT. `sync.mjs` is pulled in at CALL time, not module load. Loading
+ *    it statically would put the whole telemetry subtree onto the SessionStart
+ *    hook's import graph — the graph `tests/hooks/on-stop.test.mjs` guards for
+ *    bare specifiers, and the cost would be paid on every start whether or not
+ *    telemetry is even consented to.
+ *  - GATED, ALWAYS. `flush()` opens with `resolveConsent()`; with no consent it
+ *    returns before any network, queue write, or anon-ID mint.
+ *  - NEVER THROWS, NEVER BLOCKS A START. Every failure is swallowed, and the POST
+ *    is bounded at STARTUP_FLUSH_TIMEOUT_MS; a timeout queues the batch rather
+ *    than losing it.
+ *
+ * @param {string} repoRoot
+ * @returns {Promise<void>}
+ */
+async function flushTelemetryOnSessionStart(repoRoot) {
+  try {
+    const { flush } = await import('./lib/telemetry/sync.mjs');
+    await flush({
+      metricsDir: path.join(repoRoot, '.orchestrator', 'metrics'),
+      timeoutMs: STARTUP_FLUSH_TIMEOUT_MS,
+    });
+  } catch { /* fire-and-forget by contract */ }
+}
+
 function renderHuman(summary) {
   const lines = [];
   lines.push(`Backfill abandoned sessions — ${summary.mode}`);
@@ -372,7 +487,7 @@ async function main() {
         '  --dry-run             preview only (DEFAULT — nothing is written)\n' +
         '  --apply               synthesize + append abandoned-session stubs\n' +
         '  --json                emit the summary as JSON to stdout\n' +
-        '  --repo-root           override the project root (default: resolved SO_PROJECT_DIR)\n' +
+        '  --repo-root           override the project root (default: resolved project dir)\n' +
         '  --assume-dead-before  ISO-8601 cutoff; a candidate whose last known event\n' +
         '                        predates it bypasses a live foreign session.lock\n' +
         'Exit codes: 0 ok, 1 arg error, 2 system error\n'
@@ -382,7 +497,7 @@ async function main() {
 
   // --apply is an explicit opt-in; absent it (or with --dry-run) we never write.
   const apply = values.apply === true && values['dry-run'] !== true;
-  const repoRoot = values['repo-root'] || SO_PROJECT_DIR;
+  const repoRoot = values['repo-root'] || getProjectDir();
 
   let assumeDeadBeforeMs = null;
   if (typeof values['assume-dead-before'] === 'string' && values['assume-dead-before'].length > 0) {

package/scripts/backfill-learnings-from-vault.mjs

@@ -71,7 +71,7 @@ import { parseSessionConfig } from './lib/config.mjs';
 import { subjectToSlug, parseFrontmatter } from './lib/vault-mirror/utils.mjs';
 import { kebab } from './lib/learnings/kebab.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
-import { appendLearning } from './lib/learnings/io.mjs';
+import { appendLearning, isBackupOf } from './lib/learnings/io.mjs';
 
 const DEFAULT_RULES_DIR = '.claude/rules';
 const DEFAULT_STORE = '.orchestrator/metrics/learnings.jsonl';
@@ -620,7 +620,13 @@ function idsInStore(filePath) {
   return ids;
 }
 
-/** List `<store>.bak-*` siblings (a verbatim original beats any reconstruction). */
+/**
+ * List `<store>.bak[-.]*` siblings (a verbatim original beats any
+ * reconstruction). Both delimiter forms count — the legacy dot form
+ * (`learnings.jsonl.bak.evolve-<ts>`) is still on disk in consumer repos and
+ * was silently skipped here, i.e. a backup that exists and is not found in the
+ * one case it is for (#1173).
+ */
 function backupPaths(storePath) {
   const dir = dirname(storePath);
   const base = basename(storePath);
@@ -633,7 +639,7 @@ function backupPaths(storePath) {
     return [];
   }
   return names
-    .filter((n) => n.startsWith(`${base}.bak-`))
+    .filter((n) => isBackupOf(base, n))
     .sort()
     .map((n) => join(dir, n));
 }