session-orchestrator 5.2.0 → 5.3.0

package/monitors/monitors.json

@@ -2,7 +2,7 @@
   {
     "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. 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.",
+    "description": "Local state-file watcher: every 900 s it stats and reads ONE file, .orchestrator/metrics/ecosystem-health.jsonl under the plugin root, and emits one NDJSON line per change (appeared / disappeared / changed). No network, no CI or branch probing, no repo enumeration, no Session Config read. Nothing writes that file yet (0 writers, measured 2026-09-18), so every run emits `no-state-yet` and idles until SIGTERM — ceiling and revisit trigger at DEFAULT_INTERVAL_S in scripts/lib/ecosystem-health.mjs. 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"
   },
   {

package/output-styles/wave-summary.md

@@ -32,7 +32,7 @@ Only include if the plan changed:
 
 - One table row per agent — no nested details
 - Status is exactly one of: `done`, `partial`, `failed`
-- File lists use short relative paths (e.g., `hooks/on-stop.sh`)
+- File lists use short relative paths (e.g., `hooks/on-stop.mjs`)
 - Quality gates are pass/fail — no ambiguity
 - Adaptations only when deviating from plan — omit if on track
 - Keep under 20 lines total

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",

package/pi/prompts/eval.md

@@ -1,5 +1,5 @@
 ---
-description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v1 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
+description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
 argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"
 ---
 

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]"
+argument-hint: "[housekeeping|feature|deep|ultradeep] [task context]"
 ---
 
 # /session

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/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
@@ -41,7 +42,7 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 
 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';
@@ -125,7 +126,7 @@ function readJsonl(filePath) {
  * @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;
@@ -137,29 +138,130 @@ 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 runningIds = readRunningSessionIds(repoRoot);
 
-  const seen = new Set();
   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);
-    const semanticSessionId = semanticByUuid.get(ev.session_id) ?? null;
-    if (runningIds.has(ev.session_id)
+  for (const sessionId of startedIds) {
+    const semanticSessionId = semanticByUuid.get(sessionId) ?? null;
+    if (runningIds.has(sessionId)
       || (semanticSessionId !== null && runningIds.has(semanticSessionId))) continue;
-    plan.push({ sessionId: ev.session_id, semanticSessionId });
+    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,