session-orchestrator 3.16.0 → 3.19.0

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "session-orchestrator",
-  "version": "3.16.0",
+  "version": "3.19.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",
   "keywords": [
     "pi-package",
     "claude-code",
+    "claude-code-plugin",
     "codex",
     "cursor",
     "ai-agents",
-    "orchestration"
+    "agentic-coding",
+    "subagents",
+    "orchestration",
+    "developer-tools",
+    "mcp",
+    "llm"
   ],
   "engines": {
     "node": ">=24.0.0"
@@ -33,6 +39,7 @@
     ".codex-plugin/",
     ".cursor/",
     "docs/*.md",
+    "docs/telemetry/telemetry-claims.md",
     "NOTICE",
     "SECURITY.md",
     "!**/node_modules/**",
@@ -42,6 +49,7 @@
     "test": "node scripts/check-package-manager.mjs && vitest --run",
     "test:coverage": "node scripts/check-package-manager.mjs && vitest --run --coverage",
     "test:watch": "node scripts/check-package-manager.mjs && vitest",
+    "quality-gate": "node scripts/run-quality-gate.mjs --variant full-gate",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "typecheck": "node scripts/typecheck.mjs",
@@ -73,13 +81,18 @@
     "vitest": "^4.1.5"
   },
   "overrides": {
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "fast-uri": "^3.1.5",
+    "brace-expansion": "^5.0.9"
   },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Kanevry/session-orchestrator.git"
   },
+  "bugs": {
+    "url": "https://github.com/Kanevry/session-orchestrator/issues"
+  },
   "pi": {
     "extensions": [
       "./pi/extensions/session-orchestrator.ts"

package/pi/prompts/contract-version-bump.md

@@ -0,0 +1,12 @@
+---
+description: Classify and apply a version bump to a machine-readable contract (JSON Schema, API spec, config schema) — version literals, consumer compatibility, changelog entry, downstream drift
+argument-hint: "[--contract <path>]"
+---
+
+# /contract-version-bump
+
+Use the Session Orchestrator command definition at `commands/contract-version-bump.md`.
+
+Arguments: $@
+
+Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/rules/README.md

@@ -0,0 +1,32 @@
+# Rules Library (deliverable)
+
+This directory is the **deliverable rule library** — the coding-standard and
+discipline rules that *consumer* repos adopt via `/bootstrap --sync-rules`
+(sync logic: [`scripts/lib/rules-sync.mjs`](../scripts/lib/rules-sync.mjs)).
+
+It is **not** the always-on rule set of *this* repository — those live in
+[`.claude/rules/`](../.claude/rules/). The two directories share the name
+"rules" but play opposite roles: `rules/` ships rules **out** to other repos,
+`.claude/rules/` is what this repo runs on day-to-day.
+
+Every file here carries a
+`<!-- source: session-orchestrator plugin (canonical: rules/<path>) -->` header.
+On sync, plugin-sourced files are overwritten in the consumer while its
+locally-authored rules are preserved (copy-on-write). The canonical manifest of
+what vendors where is [`_index.md`](./_index.md).
+
+## Structure
+
+- **[`always-on/`](./always-on/)** — vendored to *every* consumer repo, whatever its stack (parallel-session discipline, commit discipline, the quality-gate triad).
+- **[`opt-in-stack/`](./opt-in-stack/)** — vendored only when the consumer's resolved archetype matches (backend, frontend, Swift, web-security, …).
+- **[`opt-in-domain/`](./opt-in-domain/)** — vendored on archetype match for a specific domain concern (e.g. prompt-caching).
+
+The optional `[archetypes: …]` tag on an `_index.md` entry is the allowlist that
+decides which repos receive an opt-in file; an untagged entry is universal.
+
+## Authoring
+
+New or changed rules follow the format in
+[`../docs/rule-authoring.md`](../docs/rule-authoring.md) and must be registered
+in [`_index.md`](./_index.md) to be vendored. Category entries must not share a
+basename — all synced files flatten into the consumer's `.claude/rules/`.

package/scripts/archive-closed-prds.mjs

@@ -42,6 +42,7 @@ import { findProjectRoot, resolveInstructionFile, warn } from './lib/common.mjs'
 import { parseSessionConfig } from './lib/config.mjs';
 import { glabRun as defaultGlabRun } from './lib/vault-backfill/glab.mjs';
 import { archiveFileToVault, titleFromMarkdown } from './lib/vault-archive.mjs';
+import { defaultGlabRepo } from './lib/vcs-repo-spec.mjs';
 
 const DEFAULT_PRD_DIR = 'docs/prd';
 const DEFAULT_VAULT_SUBDIR = '01-projects/session-orchestrator/prd';
@@ -57,28 +58,17 @@ function defaultGitRun(gitArgs) {
   return { ok: r.status === 0, stdout: r.stdout || '', stderr: r.stderr || '' };
 }
 
-/**
- * Best-effort auto-detection of the glab `-R` repo spec from the local git
- * remotes (prefers a `gitlab` helper-remote, else `origin`). Returned as the raw
- * remote URL, which glab `-R` accepts (HTTPS, `.git`, or SSH forms all work).
- *
- * This keeps the committed custom-phase command host-agnostic (no private host
- * in CLAUDE.md — owner-leakage/#494) while still resolving the correct host when
- * glab is spawned non-interactively (a bare `glab` spawn ignores the shell
- * wrapper and falls back to the ambient GITLAB_HOST, which may not match).
- *
- * @param {string} repoRoot
- * @param {(args: string[]) => { ok: boolean, stdout: string, stderr: string }} gitRunFn
- * @returns {string|undefined}
- */
-export function defaultGlabRepo(repoRoot, gitRunFn) {
-  for (const remote of ['gitlab', 'origin']) {
-    const { ok, stdout } = gitRunFn(['-C', repoRoot, 'remote', 'get-url', remote]);
-    const url = ok ? stdout.trim() : '';
-    if (url) return url;
-  }
-  return undefined;
-}
+// Best-effort auto-detection of the glab `-R` repo spec from the local git
+// remotes (prefers a `gitlab` helper-remote, else `origin`) — lifted into
+// `scripts/lib/vcs-repo-spec.mjs::defaultGlabRepo` (#839) as the single shared
+// implementation; re-exported here (`export { defaultGlabRepo }` below) so
+// existing callers/tests importing it from this module keep working.
+//
+// This keeps the committed custom-phase command host-agnostic (no private host
+// in CLAUDE.md — owner-leakage/#494) while still resolving the correct host when
+// glab is spawned non-interactively (a bare `glab` spawn ignores the shell
+// wrapper and falls back to the ambient GITLAB_HOST, which may not match).
+export { defaultGlabRepo };
 
 // ---------------------------------------------------------------------------
 // Pure helpers

package/scripts/autopilot-multi.mjs

@@ -17,6 +17,7 @@ import { execFile as execFileCb, spawnSync } from 'node:child_process';
 import { promisify } from 'node:util';
 import path from 'node:path';
 import fs from 'node:fs';
+import { resolveRepoSpec } from './lib/vcs-repo-spec.mjs';
 
 const execFile = promisify(execFileCb);
 
@@ -48,7 +49,9 @@ OPTIONS:
 EXIT CODES:
   0  Success
   1  User error (bad flags)
-  2  System error (libs/binaries/probe failed)
+  2  System error (libs/binaries/probe failed) — or a terminal stop reason
+     (kill-switch / spiral / cohort-abort / spawn-error)
+  3  no productive work — apply run completed but zero loops did any work
 `;
 
 const FLAGS = {
@@ -274,15 +277,34 @@ function extractRefs(_issue, _field) {
  * Fetch the ready-backlog from GitLab via `glab issue list`.
  * Uses execFile (shell: false) per SEC-014 / cli-design rules.
  *
+ * Host-pinning (#904): a bare `glab` spawn (no shell wrapper, no `-R`) falls
+ * back to the ambient `GITLAB_HOST` config default, which can silently
+ * resolve to the WRONG GitLab instance on a multi-host machine. Injecting
+ * `GITLAB_HOST` into the spawn env is NOT a fix — it is live-refuted whenever
+ * `~/.ssh/config` maps the hostname to a `HostName` IP alias (glab then
+ * reports "none of the git remotes ... correspond to the GITLAB_HOST"). Only
+ * `-R <spec>` survives that mismatch. See scripts/lib/vcs-repo-spec.mjs
+ * docblock; reference idiom: scripts/lib/spiral-carryover.mjs.
+ *
  * @param {Function} execFileFn  Promisified execFile
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]  Repo root to resolve the `-R` spec from (default: process.cwd())
+ * @param {'gitlab'|'github'} [opts.vcs]  VCS backend (default: 'gitlab')
+ * @param {(o: { repoRoot: string, vcs: 'gitlab'|'github' }) => string|undefined} [opts.resolveRepoSpecFn]
+ *   DI seam for `resolveRepoSpec` (testability).
  * @returns {Promise<Array<{iid: number, title: string, blocks: number[], blockedBy: number[], labels: string[]}>>}
  */
-async function fetchReadyBacklog(execFileFn) {
-  const { stdout } = await execFileFn(
-    'glab',
-    ['issue', 'list', '--label', 'status:ready', '--per-page', '50', '--output', 'json'],
-    { shell: false, timeout: 30_000 },
-  );
+async function fetchReadyBacklog(execFileFn, opts = {}) {
+  const resolveRepoSpecFn = opts.resolveRepoSpecFn ?? resolveRepoSpec;
+  const vcs  = opts.vcs === 'github' ? 'github' : 'gitlab';
+  const spec = resolveRepoSpecFn({ repoRoot: opts.repoRoot ?? process.cwd(), vcs });
+
+  const args = ['issue', 'list', '--label', 'status:ready', '--per-page', '50', '--output', 'json'];
+  // Never emit '-R undefined' — resolveRepoSpec returns undefined when it
+  // cannot auto-detect a remote; omit the flag entirely in that case.
+  if (spec) args.push('-R', spec);
+
+  const { stdout } = await execFileFn('glab', args, { shell: false, timeout: 30_000 });
   const issues = JSON.parse(stdout);
   return issues.map((i) => ({
     iid:       i.iid ?? i.id,
@@ -296,11 +318,19 @@ async function fetchReadyBacklog(execFileFn) {
 /**
  * Summarise a completed apply run into a canonical result envelope.
  *
+ * Success/exit-code semantics (#905): a `reason` that is not a terminal
+ * stop-reason (see `terminalReasons`) used to be reported as `success: true`
+ * even when every registered loop did zero productive work (e.g. the inner
+ * loop fell back to manual mode with 0 iterations completed) — the classic
+ * "fallback counts as complete" bug. `success` now additionally requires
+ * either an empty backlog (no loops were ever registered — the legitimate
+ * "nothing to do" case) or at least one loop that actually completed work.
+ *
  * @param {import('./lib/autopilot/multi-killswitch.mjs').LoopRegistration[]} allLoops
  * @param {string} reason
  * @param {number} startMs
  * @param {{ kill: string, detail: string }|null} [killDetail]
- * @returns {{ success: boolean, data: object }}
+ * @returns {{ success: boolean, exitCode: number, data: object }}
  */
 function finalize(allLoops, reason, startMs, killDetail = null) {
   const terminalReasons = new Set([
@@ -310,15 +340,35 @@ function finalize(allLoops, reason, startMs, killDetail = null) {
     'spawn-error',
     STALE_SUBAGENT_MIN,
   ]);
+  const isTerminal = terminalReasons.has(reason);
+  const completed        = allLoops.filter((l) => l.status === 'complete').length;
+  const failed           = allLoops.filter((l) => l.status === 'failed').length;
+  const noWork           = allLoops.filter((l) => l.status === 'no-work').length;
+  const fellBackToManual = allLoops.filter((l) => l.fallbackToManual === true).length;
+
+  // Empty-backlog regression guard: zero registered loops is a legitimate
+  // "nothing to do" outcome, not a "no productive work" outcome — do not
+  // conflate the two.
+  const success = !isTerminal && (allLoops.length === 0 || completed > 0);
+
+  // Exit-code triage: success -> 0; a terminal stop-reason -> 2 (unchanged;
+  // this is the only way `!success` can coincide with an empty allLoops); a
+  // non-terminal reason with >=1 registered loop but zero productive loops
+  // -> 3 ("no productive work" — the run completed cleanly but nothing landed).
+  const exitCode = success ? 0 : (isTerminal ? 2 : 3);
+
   return {
-    success: !terminalReasons.has(reason),
+    success,
+    exitCode,
     data: {
       reason,
-      loopCount:   allLoops.length,
-      completed:   allLoops.filter((l) => l.status === 'complete').length,
-      failed:      allLoops.filter((l) => l.status === 'failed').length,
-      elapsedMs:   Date.now() - startMs,
-      killDetail:  killDetail ?? null,
+      loopCount:        allLoops.length,
+      completed,
+      failed,
+      noWork,
+      fellBackToManual,
+      elapsedMs:        Date.now() - startMs,
+      killDetail:       killDetail ?? null,
     },
   };
 }
@@ -430,6 +480,8 @@ async function runApplyLoop(state, libs, opts) {
         issueIid:            issue.iid,
         status:              'running',
         killSwitch:          null,
+        iterationsCompleted: 0,
+        fallbackToManual:    false,
         spiralRecoveryCount: 0,
         startedAt:           Date.now(),
         lastActivityAt:      Date.now(),
@@ -453,7 +505,20 @@ async function runApplyLoop(state, libs, opts) {
         //   yet signal "first green test"; wire once runStoryPipeline
         //   propagates a firstGreenAt timestamp in StoryResult.
       }).then((result) => {
-        registration.status      = result.killSwitch ? 'failed' : 'complete';
+        // Three-way classification (#905): a StoryResult with no kill-switch
+        // AND zero completed iterations (or an explicit fallback-to-manual
+        // flag) is NOT the same as a completed loop — it did no productive
+        // work. Conflating the two used to make an empty apply run report
+        // false success. See finalize() for the corresponding success/
+        // exit-code semantics and multi-killswitch.mjs's LoopRegistration
+        // typedef (out of scope here) for the 'queued'|'running'|'complete'|
+        // 'failed' status enum this 'no-work' value extends locally.
+        registration.iterationsCompleted = result.iterationsCompleted ?? 0;
+        registration.fallbackToManual    = result.fallbackToManual === true;
+        registration.status =
+          result.killSwitch ? 'failed'
+          : (registration.fallbackToManual || registration.iterationsCompleted === 0) ? 'no-work'
+          : 'complete';
         registration.killSwitch  = result.killSwitch ?? null;
         completed.add(issue.iid);
         lastCompletionAt = Date.now();
@@ -493,9 +558,17 @@ async function runApplyLoop(state, libs, opts) {
         Promise.race(Array.from(inFlight.values()).map((v) => v.promise.then(() => null))),
         new Promise((r) => setTimeout(r, 5000)),
       ]);
-      // Sweep completed / failed entries.
+      // Sweep completed / failed / no-work entries. 'no-work' MUST be swept
+      // here exactly like 'complete'/'failed' — omitting it leaves a settled
+      // promise permanently registered as active, which starves
+      // shouldStopOrchestrator's "backlog-empty" (activeLoops.length === 0)
+      // condition and hangs the orchestrator forever (#905 sweep regression).
       for (const [id, { registration }] of inFlight.entries()) {
-        if (registration.status === 'complete' || registration.status === 'failed') {
+        if (
+          registration.status === 'complete' ||
+          registration.status === 'failed' ||
+          registration.status === 'no-work'
+        ) {
           inFlight.delete(id);
         }
       }
@@ -714,7 +787,7 @@ export async function main(argv = process.argv.slice(2), opts = {}) {
   } else {
     // Apply path: fetch real issues via glab (execFile, shell: false — SEC-014).
     try {
-      issues = await fetchReadyBacklog(execFile);
+      issues = await fetchReadyBacklog(execFile, { repoRoot: process.cwd() });
     } catch (err) {
       const msg = `glab issue list failed: ${err.message}`;
       process.stderr.write(`autopilot-multi: ${msg}\n`);
@@ -783,13 +856,23 @@ export async function main(argv = process.argv.slice(2), opts = {}) {
   } else {
     console.log(
       `Multi-story apply complete: ${result.data.reason}` +
-      ` — ${result.data.completed}/${result.data.loopCount} loops succeeded`,
+      ` — ${result.data.completed}/${result.data.loopCount} loops succeeded, ` +
+      `${result.data.failed} failed, ${result.data.noWork} did no work` +
+      ` (${result.data.fellBackToManual} fell back to manual)`,
     );
   }
 
-  exitFn(result.success ? 0 : 2);
+  exitFn(result.exitCode);
 }
 
+// ---------------------------------------------------------------------------
+// Test-only exports — internal functions exercised directly by
+// tests/scripts/autopilot-multi.test.mjs (no behaviour change on the CLI
+// path; mirrors the export pattern in scripts/archive-closed-prds.mjs).
+// ---------------------------------------------------------------------------
+
+export { finalize, fetchReadyBacklog, runApplyLoop };
+
 // ---------------------------------------------------------------------------
 // CLI guard — prevents top-level execution on import (deep-2 #368)
 // ---------------------------------------------------------------------------

package/scripts/backfill-abandoned-sessions.mjs

@@ -41,12 +41,19 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
 
-import { backfillAbandonedSession } from './lib/session-close-backfill.mjs';
+import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
 import { SO_PROJECT_DIR } from './lib/platform.mjs';
 
 const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
 
+/**
+ * Default cap on how many candidates may reach the (expensive) shared core in a
+ * single run. Only the SessionStart path passes a limit; the CLI stays uncapped.
+ * See `backfillOnSessionStart` for the latency rationale.
+ */
+export const SESSION_START_LIMIT = 25;
+
 /** Read a JSONL file into parsed objects; missing → []; malformed lines skipped. */
 function readJsonl(filePath) {
   let raw;
@@ -101,6 +108,48 @@ export function planSessions({ repoRoot }) {
   return plan;
 }
 
+/**
+ * Cheap pre-filter (#926): the set of session ids ALREADY present in
+ * sessions.jsonl.
+ *
+ * WHY THIS EXISTS — latency. `backfillAbandonedSession` re-reads the whole
+ * events.jsonl on every call whose id cannot be resolved without it. On a
+ * mature store that is O(candidates x events-file): measured 1.26 s for 187
+ * candidates over a 1.77 MB events.jsonl, of which 183 were already recorded
+ * and therefore pure waste. Reading the (much smaller) sessions.jsonl ONCE up
+ * front lets us skip those without entering the core at all.
+ *
+ * This is a pure latency optimisation with NO behavioural change: it reproduces
+ * exactly the core's own early-dedupe branch (same `recordId` derivation, same
+ * defensive UUID check) and reports the same `skipped-already-recorded` key.
+ * Candidates whose id CANNOT be resolved cheaply (a bare UUID with no
+ * lock.acquired bridge — the synthetic-id mint needs events) are never
+ * pre-filtered; they still go through the core untouched.
+ *
+ * @param {string} repoRoot
+ * @returns {Set<string>}
+ */
+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);
+  }
+  return ids;
+}
+
+/**
+ * Resolve the sessions.jsonl record id for a planned candidate WITHOUT reading
+ * events.jsonl. Mirrors the core's own two-phase resolution: a known semantic
+ * id, or a `sessionId` that is already semantic. Returns null when the id can
+ * only be resolved from events (bare UUID → lock bridge or synthetic mint).
+ */
+function cheapRecordId({ sessionId, semanticSessionId }) {
+  if (semanticSessionId) return semanticSessionId;
+  if (sessionId && !isUuid(sessionId)) return sessionId;
+  return null;
+}
+
 /**
  * Run the migration over every planned session.
  *
@@ -108,11 +157,35 @@ export function planSessions({ repoRoot }) {
  * module docblock for why. `assumeDeadBeforeMs` is forwarded as-is (null when
  * `--assume-dead-before` was not given).
  *
- * @param {{ repoRoot: string, apply: boolean, assumeDeadBeforeMs?: number|null }} args
+ * @param {object} args
+ * @param {string}  args.repoRoot
+ * @param {boolean} args.apply
+ * @param {number|null} [args.assumeDeadBeforeMs]
+ * @param {number|null} [args.limit=null]
+ *   #926 — cap on how many candidates may reach the shared core. Pre-filtered
+ *   (already-recorded) candidates do NOT count against it, since they cost
+ *   nothing. On hitting the cap the run stops early and sets
+ *   `summary.truncated = true`; the remainder is picked up by the next run.
+ *   `null` (CLI default) means uncapped.
+ * @param {boolean} [args.newestFirst=false]
+ *   #926 — walk the plan most-recent-first. Load-bearing whenever `limit` is
+ *   set: a bare-UUID candidate with no lock.acquired bridge cannot be
+ *   pre-filtered (its synthetic id is only derivable from events), so it always
+ *   spends a core call just to be told "already recorded". In first-seen order
+ *   those ancient candidates exhaust the whole budget before the run ever
+ *   reaches the genuinely-abandoned recent ones. Measured on a copy of this
+ *   repo's live store: first-seen order → backfilled 0, truncated true.
  * @returns {Promise<object>} aggregate summary
  */
-export async function runMigration({ repoRoot, apply, assumeDeadBeforeMs = null }) {
-  const plan = planSessions({ repoRoot });
+export async function runMigration({
+  repoRoot,
+  apply,
+  assumeDeadBeforeMs = null,
+  limit = null,
+  newestFirst = false,
+}) {
+  const planned = planSessions({ repoRoot });
+  const plan = newestFirst ? [...planned].reverse() : planned;
   const summary = {
     repoRoot,
     mode: apply ? 'apply' : 'dry-run',
@@ -124,6 +197,10 @@ export async function runMigration({ repoRoot, apply, assumeDeadBeforeMs = null
     skipped: {},
   };
 
+  // Pre-filter pass — costs ONE sessions.jsonl read for the whole run.
+  const recordedIds = readRecordedIds(repoRoot);
+  let considered = 0;
+
   // Dry-run has no incremental sessions.jsonl write, so two started-UUIDs that
   // bridge to the SAME semantic id (a session that cleared/compacted mid-run)
   // would both report 'would-backfill' and over-count. Track projected ids
@@ -131,6 +208,24 @@ export async function runMigration({ repoRoot, apply, assumeDeadBeforeMs = null
   const projected = new Set();
 
   for (const item of plan) {
+    // -- Cheap pre-filter: already recorded → skip WITHOUT entering the core --
+    const known = cheapRecordId(item);
+    if (
+      (known !== null && recordedIds.has(known)) ||
+      (isUuid(item.sessionId) && recordedIds.has(item.sessionId))
+    ) {
+      summary.skipped['skipped-already-recorded'] =
+        (summary.skipped['skipped-already-recorded'] ?? 0) + 1;
+      continue;
+    }
+
+    // -- Latency cap (#926, SessionStart path only) --------------------------
+    if (typeof limit === 'number' && considered >= limit) {
+      summary.truncated = true;
+      break;
+    }
+    considered += 1;
+
     const res = await backfillAbandonedSession({
       repoRoot,
       sessionId: item.sessionId,
@@ -143,6 +238,10 @@ export async function runMigration({ repoRoot, apply, assumeDeadBeforeMs = null
       case 'backfilled':
         summary.backfilled += 1;
         if (res.deadByAge) summary.dead_by_age += 1;
+        // 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).
+        if (typeof res.sessionId === 'string') recordedIds.add(res.sessionId);
         break;
       case 'would-backfill':
         if (projected.has(res.sessionId)) {
@@ -164,6 +263,63 @@ export async function runMigration({ repoRoot, apply, assumeDeadBeforeMs = null
   return summary;
 }
 
+/**
+ * SessionStart entry point (#926) — decouple the backfill from the /close path.
+ *
+ * THE BUG THIS FIXES: `hooks/on-session-end.mjs` calls the backfill correctly,
+ * but SessionEnd only fires on a REGULAR close. A session killed by Ctrl-C, a
+ * timeout, or a crash leaves no ledger entry at all, and the backfill then waits
+ * for the NEXT clean close — which may never come. Observed on this repo:
+ * sessions.jsonl 18.9 h behind events.jsonl with 8 commits and 0 records.
+ * Running at SessionStart closes the loop: the PREVIOUS abandoned session is
+ * reconstructed by the NEXT session's start, whatever killed it.
+ *
+ * ── SAFETY (the two ways this could do damage) ───────────────────────────────
+ *  (1) NEVER record the CURRENTLY-STARTING session as abandoned. Two
+ *      independent defences:
+ *        a. STRUCTURAL — the caller invokes this BEFORE emitting
+ *           `orchestrator.session.started`, so this session is not yet in
+ *           events.jsonl and therefore not a candidate at all (`planSessions`
+ *           enumerates started-events only).
+ *        b. GUARD — on a clear/compact/resume re-fire, an EARLIER
+ *           `session.started` for the same logical session IS present. It
+ *           resolves to our own semantic id, whose lock is live, so the core's
+ *           `skipped-own-live-lock` branch (#863) rejects it.
+ *  (2) NEVER record a RUNNING FOREIGN session as abandoned. The core evaluates
+ *      lock ownership against the CANDIDATE (not the running process): a
+ *      candidate that holds a live lock returns `skipped-own-live-lock` BEFORE
+ *      the dead-by-age relaxation is ever consulted. Verified against a fixture
+ *      where the live lock holder is >4 h stale and thus relaxation-eligible.
+ *
+ * Residual risk, stated explicitly: a session that is live but does NOT hold
+ * the lock (it lost the acquire race — `bootstrapLock` leaves the foreign lock
+ * in place and bails) AND has emitted no event for longer than the lock TTL
+ * (`DEFAULT_TTL_HOURS` = 4 h) could still be relaxed past. That candidate is
+ * one the system's OWN liveness model already considers dead, since its lock
+ * would have expired; we deliberately reuse that same TTL rather than inventing
+ * a second notion of liveness.
+ *
+ * Never throws — a backfill failure must NEVER block a session start.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {number|null} [args.limit=SESSION_START_LIMIT]
+ * @returns {Promise<object|null>} the summary, or null when disabled/failed
+ */
+export async function backfillOnSessionStart({ repoRoot, limit = SESSION_START_LIMIT } = {}) {
+  try {
+    // Escape hatch for operators who never want ledger writes at session start.
+    if (process.env.SO_DISABLE_STARTUP_BACKFILL === '1') return null;
+    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 });
+  } catch {
+    // Swallowed by contract — see the docblock. The hook is informational-only.
+    return null;
+  }
+}
+
 function renderHuman(summary) {
   const lines = [];
   lines.push(`Backfill abandoned sessions — ${summary.mode}`);

package/scripts/check-doc-consistency.sh

@@ -86,7 +86,16 @@ strip_fences "$CLAUDE" > "$CLAUDE_NOFENCE"
 # ---------------------------------------------------------------------------
 # Check 3: live `## Session Config` present in CLAUDE.md
 # ---------------------------------------------------------------------------
-if ! grep -qE '^## Session Config[[:space:]]*$' "$CLAUDE"; then
+# The pattern is EXACT, mirroring isSessionConfigHeading() in
+# scripts/lib/config/section-extractor.mjs (the SSOT) — CR tolerated for CRLF
+# checkouts, nothing else. Shell cannot import the JS predicate, so the
+# alignment is by hand and this comment names the authority. It was
+# `[[:space:]]*$` until #968, which accepted `## Session Config␠` — a heading
+# the runtime parser rejects. That made this check, whose entire purpose is to
+# report whether the runtime can find the block, answer "present" for the one
+# state it exists to catch.
+CR=$(printf '\r')
+if ! grep -qE "^## Session Config${CR}?\$" "$CLAUDE"; then
   emit "$CLAUDE:1" "live-config-missing" "## Session Config heading not found (skills/_shared/config-reading.md depends on it)"
 fi
 
@@ -94,6 +103,13 @@ fi
 # Check 1: H2 parity (CLAUDE.md → README.md)
 # Canonical runtime-only headings live in CLAUDE.md exclusively and are exempt.
 # ---------------------------------------------------------------------------
+# NOT tightened to the SSOT (#968), deliberately. This is a README↔CLAUDE H2
+# PARITY-exemption list, not a comparator against "can the runtime read the
+# Session Config block" — four of its five entries have no SSOT at all, and a
+# heading it wrongly exempts costs a missing parity warning, never a silent
+# config fallback. Check 3 above is the site that answers the runtime question,
+# and that one is exact. Tightening only the `Session Config` alternative would
+# make section-extractor.mjs the authority for a fact it does not govern.
 EXEMPT_HEADINGS_RE='^## (Structure|Destructive-Command Guard|Agent Authoring Rules|Current State|Session Config)[[:space:]]*$'
 
 # Extract README H2 set (one per line, normalized — heading text without the leading `## `)

package/scripts/compute-grounding-injection.sh

@@ -54,10 +54,25 @@ SESSION_ID="${SESSION_ID:-}"
 WAVE="${WAVE:-0}"
 AGENT_TYPE="${AGENT_TYPE:-}"
 
-# --- Build list of last 3 session_ids from sessions.jsonl ---
-
+# --- Build list of last 3 REAL session_ids from sessions.jsonl ---
+
+# Filter out phantom `status: 'abandoned'` stubs (#834, session-close-backfill
+# — 0 waves, seconds of runtime) BEFORE taking the tail. Otherwise a recent
+# phantom can evict the one real session carrying the stagnation evidence,
+# silently suppressing grounding injection for a genuinely stagnating file.
+#
+# `-R` (raw-input) + `fromjson?` parses each line individually and SKIPS
+# unparseable ones instead of aborting the whole stream — plain
+# `jq -c 'select(...)'` aborts at the FIRST malformed line (jq: parse error,
+# exit 5). sessions.jsonl is append-only from multiple writers, so a torn
+# write earlier in the file must not silently starve LAST_SESSIONS down to
+# "[]" (fail-closed-empty is still wrong here, just a quieter wrong than the
+# stale-session-id case this fixes) — the whole point is that corruption
+# anywhere in the file no longer poisons the tail. Mirrors the per-line
+# try/catch behaviour of the .mjs path (scripts/lib/session-schema/filters.mjs).
 # Extract session_id values (skip entries without one, skip empty lines)
-LAST_SESSIONS=$(tail -n 3 "$SESSIONS_JSONL" \
+LAST_SESSIONS=$(jq -R -c 'fromjson? | select(.status != "abandoned")' "$SESSIONS_JSONL" 2>/dev/null \
+  | tail -n 3 \
   | jq -r 'select(.session_id != null and .session_id != "") | .session_id' 2>/dev/null \
   | jq -R -s 'split("\n") | map(select(length > 0))' 2>/dev/null) || LAST_SESSIONS="[]"