session-orchestrator 5.1.0 → 5.3.0

package/pi/prompts/plan.md

@@ -1,12 +1,12 @@
 ---
-description: Plan a new project, feature, or retrospective with structured requirement gathering
+description: "Use this skill when performing structured project planning and PRD generation with three modes: new (project kickoff with repo scaffolding), feature (compact feature PRD), retro (data-driven retrospective). All modes share a researched Q&A engine that dispatches parallel Explore agents before each question wave, presents options via AskUserQuestion with recommendations, and produces documents with prioritized issue creation."
 argument-hint: "[new|feature|retro]"
 ---
 
 # /plan
 
-Use the Session Orchestrator command definition at `commands/plan.md`.
+Use the Session Orchestrator skill definition at `skills/plan/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/portfolio.md

@@ -5,8 +5,8 @@ argument-hint: "[--dry-run] [--repo <name>]"
 
 # /portfolio
 
-Use the Session Orchestrator command definition at `commands/portfolio.md`.
+Use the Session Orchestrator skill definition at `skills/portfolio/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/reconcile.md

@@ -1,12 +1,12 @@
 ---
-description: Reconcile learnings into .claude/rules/ proposals — on-demand version of session-end Phase 3.6.8
+description: Use this skill when the user wants to reconcile learnings into rules, run /reconcile, propose rules from learnings, turn learnings into .claude/rules/ entries, or review what rules would be generated from current session learnings. On-demand version of session-end Phase 3.6.8.
 argument-hint: "[--dry-run]"
 ---
 
 # /reconcile
 
-Use the Session Orchestrator command definition at `commands/reconcile.md`.
+Use the Session Orchestrator skill definition at `skills/reconcile/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/release.md

@@ -1,12 +1,12 @@
 ---
-description: Cut a release — the order the steps must run in, and the criteria that abort a release
+description: "Cut a release — the order the steps must run in, and the criteria that abort a release"
 argument-hint: "[X.Y.Z]"
 ---
 
 # /release
 
-Use the Session Orchestrator command definition at `commands/release.md`.
+Use the Session Orchestrator skill definition at `skills/release/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/repo-audit.md

@@ -1,12 +1,11 @@
 ---
-description: Run a 9-category baseline compliance audit on the current repository
-argument-hint: ""
+description: "Use this skill when the user wants to audit a repository for baseline compliance, check code quality, security posture, CI/CD setup, testing, documentation, and ecosystem configuration. Runs 9 checklist categories and emits a Markdown report plus JSON sidecar at .orchestrator/metrics/repo-audit-<timestamp>.json. <example>Context: User is in a project repo and wants a baseline compliance check. user: \"/repo-audit\" assistant: \"Running repo-audit across 9 categories — Configuration, Code Quality, Git Hygiene, CI/CD, Testing, Security, Documentation, Clank Integration (optional), and MCP Configuration. Will produce a Markdown checklist report and JSON sidecar.\" <commentary>The user wants a compliance check; this skill is appropriate because it runs all 9 categories with pass/fail/warn/skipped statuses and writes structured output.</commentary></example>"
 ---
 
 # /repo-audit
 
-Use the Session Orchestrator command definition at `commands/repo-audit.md`.
+Use the Session Orchestrator skill definition at `skills/repo-audit/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/session.md

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

package/pi/prompts/spinout.md

@@ -1,12 +1,12 @@
 ---
-description: Guided 5-step venture-spinout / sanitized-fork runbook (copy + fresh-init + SNAPSHOT-FREEZE) — interactive, not scripted
+description: "Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path, confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo, remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'."
 argument-hint: "[--type venture|snapshot] [--dry-run]"
 ---
 
 # /spinout
 
-Use the Session Orchestrator command definition at `commands/spinout.md`.
+Use the Session Orchestrator skill definition at `skills/spinout/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/sunset-review.md

@@ -1,12 +1,12 @@
 ---
-description: Identify unused / near-zero-use / stale skills, agents, and commands as Demote or Retire candidates (read-only; never deletes)
+description: "Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events only) with static reference scanning, classifies every surface item into Active / Investigate / Demote / Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer wants to prune dead weight. user: \"/sunset-review\" assistant: \"Running the sunset walk — classifying skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision.\" <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker, presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>"
 argument-hint: "[--kind skill|agent|command] [--window-days N]"
 ---
 
 # /sunset-review
 
-Use the Session Orchestrator command definition at `commands/sunset-review.md`.
+Use the Session Orchestrator skill definition at `skills/sunset-review/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/templates-ack.md

@@ -1,5 +1,5 @@
 ---
-description: Acknowledge templates-first policy for the current session — bypasses the pre-bash-templates-first hook for the remainder of the session
+description: "Acknowledge templates-first policy for the current session — bypasses the pre-bash-templates-first hook for the remainder of the session"
 argument-hint: "[optional-reason]"
 ---
 

package/pi/prompts/test.md

@@ -1,12 +1,12 @@
 ---
-description: Agentic end-to-end test orchestrator — drive web/macOS flows, evaluate UX rubric, reconcile issues
+description: "Agentic end-to-end test orchestrator — drive web/macOS flows, evaluate UX rubric, reconcile issues"
 argument-hint: "[scope|profile-name] [--since <git-ref>] [--full]"
 ---
 
 # /test
 
-Use the Session Orchestrator command definition at `commands/test.md`.
+Use the Session Orchestrator skill definition at `skills/test/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/ux-grill.md

@@ -1,12 +1,12 @@
 ---
-description: Grill a running web app's UX — a deterministic mechanical pass (axe, target size, overflow, journeys) followed by a screenshot-grounded interrogation of the operator.
+description: "Use when a running web app's UX has to be audited reproducibly rather than by feel — a deterministic mechanical pass over routes and viewports (axe, target size, horizontal overflow, page title, scripted journeys) followed by a screenshot-grounded interrogation of the operator, journey by journey, with two persona lenses from the target repo's manifest. Triggered by \"grill the UX\", \"roast the dashboard\", \"UX-Audit\", \"/ux-grill\". Bootstraps its own manifest from a loopback URL on the first run, so it never requires a hand-written file to start."
 argument-hint: "[url | manifest-path]"
 ---
 
 # /ux-grill
 
-Use the Session Orchestrator command definition at `commands/ux-grill.md`.
+Use the Session Orchestrator skill definition at `skills/ux-grill/SKILL.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.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/rules/README.md

@@ -9,7 +9,7 @@ It is **not** the always-on rule set of *this* repository — those live in
 "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
+Every rule 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

package/rules/opt-in-domain/prompt-caching.md

@@ -267,4 +267,4 @@ The four PoCs filed against this rule. Each adopts in <30 LOC and is independent
 
 ## See Also
 
-backend.md · testing.md · development.md
+backend.md

package/rules/opt-in-stack/backend-data.md

@@ -185,4 +185,4 @@ async function updateUser(id: string, data: Partial<User>): Promise<void> {
 - Batch operations: use `.upsert()` or `.insert()` with arrays instead of individual inserts in loops.
 
 ## See Also
-development.md · security.md · security-web.md · testing.md · frontend.md · backend.md · swift.md · mvp-scope.md · cli-design.md · parallel-sessions.md
+security-web.md · frontend.md · backend.md · swift.md · parallel-sessions.md

package/rules/opt-in-stack/backend.md

@@ -165,7 +165,7 @@ Split api and worker into separate processes when any of these apply: queue-base
 - Named events (`event: <name>\n`) instead of untyped `data:` payloads, so client code reads `source.addEventListener('<name>', ...)` rather than switching on payload shape.
 - Naming: lowercase, dot-scoped, noun-verb. Examples: `draft.ready`, `classification.done`, `job.failed`, `stream.heartbeat`, `stream.end`.
 - Scope events by domain, not by endpoint. Two endpoints emitting `job.failed` is fine if the payload shape is identical.
-- Document the event catalog in the service's `CLAUDE.md` or `docs/api.md` — consumers need to know what to listen for without reading source.
+- Document the event catalog in the service's `CLAUDE.md` or `docs/api.md` — consumers need to know what to listen for without reading source. <!-- path-check: example -->
 
 ### Client reconnect pattern
 - `EventSource` reconnects automatically on network drop. Use the `Last-Event-ID` header to resume from the last received ID — set `id: <number>\n` on each server event for this to work.
@@ -285,7 +285,7 @@ Uses the canonical envelope from the [Canonical API Response Envelope](#canonica
 - **Reusable helper:** candidate for `@your-org/http-client` or a dedicated `@your-org/ringbuffer` package if demand grows past 2 consumer repos.
 
 ## Feature Flags
-- Use environment-variable-backed typed flags as default (see `docs/feature-flags.md`).
+- Use environment-variable-backed typed flags as default (see `docs/feature-flags.md`). <!-- path-check: example -->
 - Naming convention: `FF_<FEATURE_NAME>` in `.env`.
 - Every flag must have an expiry date. Remove within 30 days of full rollout.
 
@@ -387,4 +387,4 @@ export async function askAI(prompt: string, options?: { model?: string; maxToken
 - Checking budget after the LLM call (check before, enforce before spending)
 
 ## See Also
-development.md · security.md · security-web.md · testing.md · frontend.md · backend-data.md · swift.md · mvp-scope.md · cli-design.md · parallel-sessions.md
+security-web.md · frontend.md · backend-data.md · swift.md · parallel-sessions.md

package/rules/opt-in-stack/frontend.md

@@ -95,4 +95,4 @@ tier: wave-only
 - No arbitrary z-index (`z-index: 999 / 9999`). Build a semantic z-index scale (dropdown → sticky → modal → toast → tooltip); never magic numbers.
 
 ## See Also
-development.md · security.md · security-web.md · testing.md · backend.md · backend-data.md · mvp-scope.md · parallel-sessions.md
+security-web.md · backend.md · backend-data.md · parallel-sessions.md

package/rules/opt-in-stack/security-web.md

@@ -67,7 +67,7 @@ CSRF, rate limiting, CSP, and transport security. Core security rules are in `se
 
 #### SEC-011: CSP single-source enforcement
 - Advisory rules are silent when they regress. Wire the single-source rule into a mechanical check so duplicates fail fast.
-- Canonical hook: `templates/shared/hooks/check-csp-single-source.sh`. Greps all TS/JS under the given paths for `Content-Security-Policy`, filters to `proxy.ts` / `middleware.ts` / `next.config.*`, fails if more than one file matches.
+- Canonical hook: `templates/shared/hooks/check-csp-single-source.sh`. Greps all TS/JS under the given paths for `Content-Security-Policy`, filters to `proxy.ts` / `middleware.ts` / `next.config.*`, fails if more than one file matches. <!-- path-check: example -->
 - **Wire into pre-push (Husky):**
   ```json
   // package.json
@@ -77,7 +77,7 @@ CSRF, rate limiting, CSP, and transport security. Core security rules are in `se
   # .husky/pre-push
   pnpm run hook:check-csp
   ```
-- **Wire into CI security stage:** copy the `check-csp-single-source` job from `templates/shared/hooks/README.md` into `.gitlab-ci.yml`. Runs on every merge request.
+- **Wire into CI security stage:** copy the `check-csp-single-source` job from `templates/shared/hooks/README.md` into `.gitlab-ci.yml`. Runs on every merge request. <!-- path-check: example -->
 - Exit codes: `0` pass, `1` duplicate CSP source (SEC-011 violation), `2` tool error.
 - Why: browsers receiving two `Content-Security-Policy` headers take the intersection — nonces and `strict-dynamic` break silently. Humans miss this in review; a grep doesn't.
 
@@ -191,4 +191,4 @@ securityMiddleware(app);
 - **Template Literals**: Never use tagged template literals with user input for SQL, HTML, or shell commands. Use parameterized queries, DOMPurify, or `child_process.execFile()` respectively.
 
 ## See Also
-development.md · security.md · testing.md · frontend.md · backend.md · backend-data.md · swift.md · mvp-scope.md · cli-design.md · parallel-sessions.md
+frontend.md · backend.md · backend-data.md · swift.md · parallel-sessions.md

package/rules/opt-in-stack/swift.md

@@ -62,4 +62,4 @@ tier: wave-only
 - Validate all server-sent data with Codable schemas. Never `force-unwrap` optional JSON fields.
 
 ## See Also
-development.md · security.md · testing.md · frontend.md · backend.md · mvp-scope.md · parallel-sessions.md
+frontend.md · backend.md · parallel-sessions.md

package/scripts/archive-closed-prds.mjs

@@ -41,7 +41,6 @@
 
 import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import { join } from 'node:path';
 
 import { findProjectRoot, resolveInstructionFile, warn } from './lib/common.mjs';
@@ -52,6 +51,7 @@ import { defaultGlabRepo } from './lib/vcs-repo-spec.mjs';
 import { readLock } from './lib/session-lock.mjs';
 import { resolveStateMdPath } from './lib/state-md/frontmatter-mutators.mjs';
 import { parseStateMd } from './lib/state-md/yaml-parser.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_PRD_DIR = 'docs/prd';
 const DEFAULT_VAULT_SUBDIR = '01-projects/session-orchestrator/prd';
@@ -635,7 +635,7 @@ export function main({
 // CLI guard — prevents process.exit during test-time imports
 // ---------------------------------------------------------------------------
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   try {
     const { code } = main();
     process.exit(code ?? 0);

package/scripts/auq-audit.mjs

@@ -76,6 +76,7 @@ import {
 } from './lib/auq/schema.mjs';
 import { corpusKindOf, parseRepo } from './lib/auq/parse.mjs';
 import { writeStdoutLineSync } from './lib/io.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT_DEFAULT = path.resolve(HERE, '..');
@@ -818,8 +819,6 @@ function pkgVersion() {
   }
 }
 
-const invokedDirectly =
-  process.argv[1] !== undefined &&
-  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+const invokedDirectly =isMainModule(import.meta.url);
 
 if (invokedDirectly) main();

package/scripts/autopilot.mjs

@@ -14,6 +14,7 @@
  *   --max-sessions=N            Max iterations (1..50, default 5).
  *   --max-hours=H               Max wall-clock hours (0.5..24.0, default 4.0).
  *   --confidence-threshold=0.X  Mode confidence gate (0.0..1.0, default 0.85).
+ *   --max-tokens=N              Cumulative output-token budget (0..10000000, default 500000; 0 disables).
  *   --dry-run                   Emit a single record without spawning sessions.
  *   --verbose                   Pipe child process stdio (instead of inherit).
  *
@@ -35,6 +36,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { spawnSync, spawn } from 'node:child_process';
 import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import {
   runLoop,
@@ -55,6 +57,14 @@ import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 const argv = process.argv.slice(2);
 
+/**
+ * Plugin root, resolved from THIS file's own location (`<root>/scripts/autopilot.mjs`
+ * → `<root>`) and never from an env var. The driver is spawned unattended from an
+ * arbitrary cwd, so `--plugin-dir` must name the plugin that owns this very file;
+ * an env-var read would point wherever the operator's shell last happened to point.
+ */
+const PLUGIN_ROOT = resolve(fileURLToPath(new URL('.', import.meta.url)), '..');
+
 const hasHeadless = argv.includes('--headless');
 const hasVerbose = argv.includes('--verbose');
 
@@ -69,7 +79,7 @@ const flagsForParse = argv.filter(
   (a) => a !== '--headless' && a !== '--verbose'
 );
 
-const { maxSessions, maxHours, confidenceThreshold, dryRun } = parseFlags(flagsForParse);
+const { maxSessions, maxHours, confidenceThreshold, maxTokens, dryRun } = parseFlags(flagsForParse);
 
 // ---------------------------------------------------------------------------
 // Session Config (parsed once, shared by thresholds + decay readers)
@@ -269,9 +279,14 @@ async function sessionRunner({ mode, autopilotRunId }) {
       ? ['ignore', 'pipe', 'pipe']
       : ['ignore', 'inherit', 'inherit'];
 
+    // `session` is a RESERVED terminal-only built-in name under `claude -p`: the
+    // bare `/session <mode>` form answers "/session isn't available in this
+    // environment." and the child exits having done nothing (measured 2026-09-16,
+    // claude 2.1.273 — `commands/session.md` § Headless). Only the namespaced form
+    // resolves, and only when the plugin that defines it is on `--plugin-dir`.
     const child = spawn(
       'claude',
-      ['-p', `/session ${mode}`],
+      ['-p', `/session-orchestrator:session ${mode}`, '--plugin-dir', PLUGIN_ROOT],
       {
         env: { ...process.env, AUTOPILOT_RUN_ID: autopilotRunId },
         stdio: childStdio,
@@ -372,12 +387,18 @@ async function main() {
     maxSessions,
     maxHours,
     confidenceThreshold,
+    maxTokens,
     dryRun,
     modeSelector,
     sessionRunner,
     resourceEvaluator,
     peerCounter,
     abortSignal: controller.signal,
+    // STALL_TIMEOUT progress marker. `autopilot.jsonl` is written ONCE per
+    // invocation (after the loop), so its mtime belongs to the PREVIOUS run and
+    // fired the kill-switch after iteration 1; the session.lock heartbeat is
+    // refreshed while a session is alive. See stall-sampler.mjs § PRECEDENCE.
+    sessionLockPath: resolve('.orchestrator/session.lock'),
     runId: autopilotRunId,
     branch: branch ?? undefined,
   });

package/scripts/backfill-abandoned-sessions.mjs

@@ -2,7 +2,8 @@
 /**
  * backfill-abandoned-sessions.mjs — one-time historical migration CLI (#724 C1).
  *
- * Scans `.orchestrator/metrics/events.jsonl` for every distinct
+ * Scans `.orchestrator/metrics/events.jsonl` — and every rotated archive
+ * beside it (#1414) — for every distinct
  * `orchestrator.session.started` UUID that has no counterpart in
  * `.orchestrator/metrics/sessions.jsonl`, bridges each to its semantic id via
  * `orchestrator.session.lock.acquired` where available, and synthesizes a
@@ -39,11 +40,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { fileURLToPath } from 'node:url';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
-import { emitEvent } from './lib/events.mjs';
+import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst } from './lib/events.mjs';
 import { getProjectDir } from './lib/platform.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { isLockLive, readLock } from './lib/session-lock.mjs';
+import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
 
 const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
@@ -101,11 +104,29 @@ function readJsonl(filePath) {
  * session.started UUID, each bridged to its semantic id via lock.acquired
  * where one exists. Preserves first-seen order.
  *
+ * THIS VERY PROCESS is excluded (#1376). The shared core's own
+ * `skipped-own-live-lock` branch used to carry that job alone, but it is now
+ * defeasible: `ownSessionIsEnding` lets the SessionEnd hook record its own
+ * session, so the CLI must not depend on a branch whose meaning the caller
+ * chooses. The exclusion needs THREE conjuncts, and dropping any one of them
+ * breaks it in a different direction:
+ *   1. the candidate names the lock (by either id, including the #863 (d)
+ *      lock shape that stores the semantic id in `session_id`),
+ *   2. the lock is LIVE — a stale lock names a session nobody is running, and
+ *      reconstructing it is exactly this CLI's job, and
+ *   3. a PROCESS-LOCAL id (hook payload / harness env, never the repo-global
+ *      lock — see `readProcessLocalSessionIds`) matches the lock, which is
+ *      what distinguishes THIS process from a PEER's running session in the
+ *      same working copy. Without it the repo-global lock would vouch for
+ *      itself and a peer's live session would read as "me".
+ * A peer's live session is NOT excluded here and does not need to be: the core
+ * still rejects it through the untouched own/foreign live-lock guards.
+ *
  * @param {{ repoRoot: string }} args
  * @returns {Array<{ sessionId: string, semanticSessionId: string|null }>}
  */
 export function planSessions({ repoRoot }) {
-  const events = readJsonl(path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl'));
+  const eventsPath = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
 
   // Two independent UUID -> semantic bridges (#1167). `lock.acquired` is the
   // original one, but a session that LOST the lock-acquire race never emits it;
@@ -117,24 +138,159 @@ export function planSessions({ repoRoot }) {
   // 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 (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 seen = new Set();
+  /** Distinct `session.started` ids in FIRST-SEEN (chronological) order. */
+  const startedIds = [];
+
+  // #1414 — the whole history, OLDEST SOURCE FIRST, streamed line by line. The
+  // previous `readJsonl` of the active file alone missed every session whose
+  // `session.started` had been rotated into `_archive/`; reading the same
+  // sources through `readEventsWithRotations` instead would have loaded up to
+  // ~60 MB into memory on a path that runs at SESSION START
+  // (`hooks/on-session-start.mjs` → `backfillOnSessionStart`). Reversing the
+  // newest-first source list keeps first-seen order chronological, exactly as
+  // the single-file read produced it.
+  for (const source of [...listEventSourcesNewestFirst({ filePath: eventsPath })].reverse()) {
+    forEachJsonlRecord(source.path, (ev) => {
+      if (!ev || typeof ev !== 'object') return;
+      if (typeof ev.session_id === 'string' && typeof ev.semantic_session_id === 'string') {
+        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);
+        }
+      }
+      if (ev.event !== SESSION_STARTED || typeof ev.session_id !== 'string') return;
+      if (seen.has(ev.session_id)) return;
+      seen.add(ev.session_id);
+      startedIds.push(ev.session_id);
+    });
   }
+
+  // Resolved AFTER the pass, never during it: a `lock.acquired` / `session.ended`
+  // bridge may sit later in the stream (or in a later source) than the
+  // `session.started` it names, and deciding mid-stream would mint a synthetic
+  // id for a session whose semantic id was two lines further on.
   const semanticByUuid = new Map([...semanticFromEnded, ...semanticFromLock]);
 
-  const seen = new Set();
+  const runningIds = readRunningSessionIds(repoRoot);
+
   const plan = [];
-  for (const ev of events) {
-    if (ev.event !== SESSION_STARTED || typeof ev.session_id !== 'string') continue;
-    if (seen.has(ev.session_id)) continue;
-    seen.add(ev.session_id);
-    plan.push({ sessionId: ev.session_id, semanticSessionId: semanticByUuid.get(ev.session_id) ?? null });
+  for (const sessionId of startedIds) {
+    const semanticSessionId = semanticByUuid.get(sessionId) ?? null;
+    if (runningIds.has(sessionId)
+      || (semanticSessionId !== null && runningIds.has(semanticSessionId))) continue;
+    plan.push({ sessionId, semanticSessionId });
   }
   return plan;
 }
 
+/**
+ * Stream one JSONL file, handing every PARSED record to `onRecord` in file
+ * order — without ever holding the file in memory (#1414).
+ *
+ * MISSING (ENOENT) → silent no-op; UNREADABLE → a stderr WARN, same split as
+ * {@link readJsonl} (#1188: a missing ledger is the fresh-repo case, an
+ * unreadable one used to read as "no records" and made every count below
+ * silently wrong). Malformed lines are skipped, as in the full-read path.
+ *
+ * A line split across a chunk boundary is CARRIED as a BUFFER, so neither a
+ * record nor a multibyte character is ever cut in half — the 0x0A byte cannot
+ * occur inside a UTF-8 continuation sequence.
+ *
+ * @param {string} filePath
+ * @param {(record: object) => void} onRecord
+ */
+function forEachJsonlRecord(filePath, onRecord) {
+  const emit = (buf) => {
+    const text = buf.toString('utf8').trim();
+    if (!text) return;
+    try {
+      onRecord(JSON.parse(text));
+    } catch {
+      /* skip malformed */
+    }
+  };
+
+  let fd;
+  try {
+    fd = fs.openSync(filePath, 'r');
+  } catch (err) {
+    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',
+      );
+    }
+    return;
+  }
+  try {
+    const size = fs.fstatSync(fd).size;
+    const buf = Buffer.alloc(SCAN_CHUNK_BYTES);
+    let pos = 0;
+    let carry = Buffer.alloc(0);
+    while (pos < size) {
+      const n = fs.readSync(fd, buf, 0, SCAN_CHUNK_BYTES, pos);
+      if (n <= 0) break;
+      pos += n;
+      const block =
+        carry.length > 0
+          ? Buffer.concat([carry, buf.subarray(0, n)])
+          : Buffer.from(buf.subarray(0, n));
+      let start = 0;
+      let idx = block.indexOf(0x0a, start);
+      while (idx !== -1) {
+        emit(block.subarray(start, idx));
+        start = idx + 1;
+        idx = block.indexOf(0x0a, start);
+      }
+      carry = block.subarray(start);
+    }
+    if (carry.length > 0) emit(carry);
+  } catch (err) {
+    process.stderr.write(
+      `⚠ backfill-abandoned-sessions: cannot read ${filePath} ` +
+        `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+        'treating as EMPTY, counts below are floors\n',
+    );
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+/**
+ * The id(s) naming the session THIS process is, when that session holds the
+ * live lock — else the empty set (#1376). Never throws: an unreadable lock,
+ * an absent one, or an env without any process-local id all degrade to "no
+ * exclusion", which is the pre-#1376 behaviour.
+ *
+ * @param {string} repoRoot
+ * @returns {Set<string>}
+ */
+function readRunningSessionIds(repoRoot) {
+  const ids = new Set();
+  try {
+    const lock = readLock({ repoRoot });
+    if (!lock || !isLockLive(lock)) return ids;
+    const lockIds = [lock.session_id, lock.semantic_session_id]
+      .filter((id) => typeof id === 'string' && id.length > 0);
+    const processLocal = new Set(readProcessLocalSessionIds());
+    // Conjunct 3 — only a PROCESS-LOCAL witness may promote the repo-global
+    // lock to "this is me". Membership is tested against the lock's ids, not
+    // the other way round, so an env var that happens to name some other
+    // session never widens the exclusion.
+    if (!lockIds.some((id) => processLocal.has(id))) return ids;
+    for (const id of lockIds) ids.add(id);
+  } catch {
+    /* readLock is no-throw by contract; the contract is not ours to trust */
+  }
+  return ids;
+}
+
 /**
  * Cheap pre-filter (#926): the set of session ids ALREADY present in
  * sessions.jsonl.
@@ -527,7 +683,7 @@ async function main() {
   process.exit(0);
 }
 
-const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const isDirectRun = isMainModule(import.meta.url);
 if (isDirectRun) {
   main().catch((err) => {
     process.stderr.write(`backfill-abandoned-sessions: unexpected error: ${err?.stack ?? err}\n`);

package/scripts/backfill-evidence-digest.mjs

@@ -50,6 +50,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 
 import { computeEvidenceDigest } from './lib/reconcile/renderer.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 /** ISO-8601 instant — mirrors the renderer's `EVIDENCE_RECORDED_AT_RE`. */
 const EVIDENCE_RECORDED_AT_RE = /^\d{4}-\d{2}-\d{2}T[0-9:.]+(?:Z|[+-]\d{2}:\d{2})$/;
@@ -373,4 +374,4 @@ function main(argv) {
   process.exit(unsealable === 0 ? 0 : 1);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) main(process.argv.slice(2));
+if (isMainModule(import.meta.url)) main(process.argv.slice(2));