session-orchestrator 5.10.0 → 5.12.0

package/hooks/pre-task-scope-disjoint.mjs

@@ -301,6 +301,18 @@ const DISPATCH_TOOL = 'Agent';
  * A flat sibling, not a directory, on purpose: bootstrap's `store-lock-ignore`
  * step (#1495) ignores `.orchestrator/wave-dispatch-scopes.*` in consumer repos,
  * which covers this name; a directory would surface untracked in each of them.
+ *
+ * NAMED CEILING (BV-004, #1504 point 7a): nothing ever deletes a per-session
+ * file — the hook only writes its own, and no sweep exists (a sweep would delete
+ * files that may be a live peer's state, PSA-003). Each FILE is bounded: it holds
+ * one `waveKey`'s agents, reset on the next wave. The DIRECTORY is not: it grows
+ * by one file (plus a transient `.lock`) per session that dispatched an agent.
+ * Measured 2026-10-08 in this repo's main checkout: 7 files, largest 2918 bytes,
+ * oldest 2026-10-03 — negligible. Fine under ~500 files; the hook never lists
+ * the directory, so the count costs disk, not latency.
+ * Revisit-Trigger: `ls .orchestrator/wave-dispatch-scopes.*.json | wc -l`
+ * passes 500 in any repo, OR a reader starts enumerating these files — then
+ * build an age-gated sweep that skips any session with a live `session.lock`.
  */
 const LEDGER_DIR_REL = '.orchestrator';
 const LEDGER_STEM = 'wave-dispatch-scopes';

package/hooks/subagent-telemetry.mjs

@@ -113,6 +113,7 @@ import { appendSubagent } from '../scripts/lib/subagents-schema.mjs';
 import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 import { readTailWindow } from '../scripts/lib/tail-window.mjs';
+import { COST_BASIS } from '../scripts/lib/telemetry/pricing.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -859,14 +860,18 @@ async function main() {
     // the rollup can price it part by part; absent on every other record.
     if (modelsUsage !== null) record.models_usage = modelsUsage;
 
-    // Cost is best-effort / forward-compat (#624): the native transcript does
-    // NOT expose total_cost_usd today, so this is null in practice. No rate
-    // table is applied HERE — use the native cost only, default null when absent.
+    // Cost is best-effort (#624): retain the native payload value when valid,
+    // including a genuine zero; use null when absent. No rate table is applied
+    // HERE. Provenance (#1543) requires an explicit recognized payload basis;
+    // a native number alone says nothing about billing or API list prices.
     const totalCostUsd =
       typeof input.total_cost_usd === 'number' && Number.isFinite(input.total_cost_usd) && input.total_cost_usd >= 0
         ? input.total_cost_usd
         : null;
     record.total_cost_usd = totalCostUsd;
+    record.cost_basis = totalCostUsd !== null && input.cost_basis === COST_BASIS
+      ? input.cost_basis
+      : null;
 
     // OTel alias — #411 additive. `gen_ai.usage.input_tokens` stays the RAW
     // UNCACHED value (OTel semantic), which is why it is deliberately NOT equal

package/hooks/wave-scope-commit-guard.mjs

@@ -336,7 +336,10 @@ async function main() {
   // when every candidate is foreign the first comes back and
   // `scopeCommitVerdict` passes it as before. The git process inherits the
   // committing session's env; there is no hook payload here, so the env tier is
-  // the only process-local identity.
+  // the only process-local identity. CEILING (#1504 point 7b): a shell that
+  // exports a foreign CLAUDE_CODE_SESSION_ID makes this session's manifest read
+  // `foreign` and the guard stands down: the same power `--no-verify` grants, so it
+  // stays named, not fixed (docs/scope-collision-guard.md § 6 item 12).
   const ownIds = new Set(readProcessLocalSessionIds());
 
   // #1511 point d — ALSO read the manifest at the SESSION root the scope guards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.10.0",
+  "version": "5.12.0",
   "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementation wave, /close runs the full gate, verifies, commits and files the rest as issues. Scope and destructive-command guards, crash-safe resume, learnings you approve. For Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -28,7 +28,6 @@
   },
   "files": [
     ".mcp.json",
-    "AGENTS.md",
     "CHANGELOG.md",
     "pi/",
     "skills/",

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

@@ -19,7 +19,7 @@ tier: wave-only
 
 CSRF, rate limiting, CSP, and transport security. Core security rules are in `security.md` (always-on).
 
-## CSRF Protection (SEC-005)
+## CSRF Protection (SEC-018)
 - **Next.js 15+ Server Actions**: Built-in CSRF protection via Origin header validation against Host header. No manual CSRF token needed.
 - **Manual CSRF tokens required for**: custom API routes (`/api/*`), form submissions to external endpoints, any non-Server-Action mutation endpoint.
 - For manual CSRF token validation, use `crypto.timingSafeEqual()` for timing-safe comparison.

package/scripts/emit-session.mjs

@@ -39,6 +39,7 @@ import {
 import { parseStateMd, readSessionProfile, resolveStateMdPath } from './lib/state-md.mjs';
 import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
 import { rollupSessionTokens } from './lib/session-token-rollup.mjs';
+import { COST_BASIS, PRICING_TABLE_DATE } from './lib/telemetry/pricing.mjs';
 import { serializeSessionLineChecked } from './lib/session-schema/serializer.mjs';
 import {
   validateSession,
@@ -542,6 +543,18 @@ async function main() {
         }
         merged[key] = rollup[key];
       }
+      // #1470 Pkt 4/6 — label the merged cost fields. A dollar figure is the
+      // API list-price equivalent, never a payment (`cost_basis`, only beside
+      // a written `total_cost_usd`). The coverage counters, too, depend on
+      // which models the table knows, so `pricing_table_date` names the table
+      // that produced them — read from pricing.mjs, the same module the rollup
+      // priced with, never a second copy of the date.
+      if ('total_cost_usd' in merged && !hasOwn('cost_basis')) {
+        merged.cost_basis = COST_BASIS;
+      }
+      if ('cost_records_total' in merged && !hasOwn('pricing_table_date')) {
+        merged.pricing_table_date = PRICING_TABLE_DATE;
+      }
       // Enrichment must never be the reason the ledger gains no line: validate
       // the enriched record first and fall back to the un-enriched one. Blamed
       // on the rollup only when the un-enriched record validates on its own —

package/scripts/fleet-checkin-audit.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/** Read-only CLI for explicitly supplied, stable snapshot copies (#1462). */
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+import { auditCheckins } from './lib/fleet-checkin-audit.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const HELP = `Usage: fleet-checkin-audit --input-root DIR --registry FILE --checkins FILE --repo KEY [--repo KEY] --at UTC [--json]
+All five input flags are required. --repo may repeat with distinct explicit keys.
+--at is an exact UTC instant (YYYY-MM-DDTHH:MM:SS[.sss]Z).
+--json emits one JSON report; --help and --version are standalone commands.
+Supply complete registry/check-in snapshot copies with capture times matching --at.
+Only explicit regular files inside --input-root are read; symlinks are refused.
+Use stable trusted copies: simultaneous parent-directory renames are not atomic.
+No discovery, live configuration, referenced-repo reads, events or input writes.
+Exit 0: measured, including findings; 1: invalid arguments, paths or JSON;
+2: unavailable inputs/system I/O; 3: incomplete or not-measurable snapshot evidence.
+stdout contains the report; stderr contains only diagnostics.
+`;
+const failure = (category, exit, errno) => Object.assign(new Error(category), { category, exit, errno });
+
+function argumentsFor(argv) {
+  const args = { repos: [], json: false };
+  const values = new Map([['--input-root', 'root'], ['--registry', 'registry'], ['--checkins', 'checkins'], ['--at', 'at']]);
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--json') { args.json = true; continue; }
+    if (flag === '--help' || flag === '--version') {
+      if (argv.length !== 1) throw failure('invalid-arguments', 1);
+      args.action = flag;
+      return args;
+    }
+    if (flag !== '--repo' && !values.has(flag)) throw failure('invalid-arguments', 1);
+    const value = argv[++i];
+    if (!value || value.startsWith('--')) throw failure('invalid-arguments', 1);
+    if (flag === '--repo') args.repos.push(value);
+    else {
+      const key = values.get(flag);
+      if (args[key] !== undefined) throw failure('duplicate-argument', 1);
+      args[key] = value;
+    }
+  }
+  if (!args.root || !args.registry || !args.checkins || !args.at || !args.repos.length) throw failure('missing-arguments', 1);
+  if (new Set(args.repos).size !== args.repos.length || args.repos.some((repo) => repo.trim() !== repo)) {
+    throw failure('invalid-repo-selection', 1);
+  }
+  const instant = Date.parse(args.at);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(args.at)
+    || !Number.isFinite(instant)
+    || new Date(instant).toISOString() !== args.at.replace(/Z$/, args.at.includes('.') ? 'Z' : '.000Z')) {
+    throw failure('invalid-measurement-time', 1);
+  }
+  return args;
+}
+
+/** Inspect every component before reading contents; parent rename races remain
+ * outside this portable path-based reader's guarantee (use stable copies). */
+async function inspect(root, name) {
+  const target = path.resolve(root, name);
+  const relative = path.relative(root, target);
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw failure('path-outside-input-root', 1);
+  }
+  const parsed = path.parse(target);
+  let current = parsed.root;
+  let stat;
+  const components = target.slice(parsed.root.length).split(path.sep);
+  for (let i = 0; i < components.length; i++) {
+    current = path.join(current, components[i]);
+    stat = await fs.lstat(current);
+    if (stat.isSymbolicLink()) throw failure('symlink-input', 1);
+    if (i < components.length - 1 && !stat.isDirectory()) throw failure('non-directory-parent', 1);
+  }
+  if (!stat?.isFile()) throw failure('non-regular-input', 1);
+  return { target, stat };
+}
+
+async function readSnapshot({ target, stat }) {
+  // The parent check above and this open are not atomic: a same-user process can swap a parent
+  // directory in between. Fine while the operator names the snapshot files and the result grants
+  // nothing; revisit (#1549) once paths come from a foreign owner or the result gates a decision.
+  if (typeof constants.O_NOFOLLOW !== 'number' || typeof constants.O_NONBLOCK !== 'number') {
+    throw failure('unsupported-safe-open', 2);
+  }
+  const handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  let bytes;
+  try {
+    const actual = await handle.stat();
+    if (!actual.isFile() || actual.dev !== stat.dev || actual.ino !== stat.ino) throw failure('changed-input-file', 1);
+    bytes = await handle.readFile();
+  } finally { await handle.close(); }
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { throw failure('malformed-json-or-utf8', 1); }
+}
+
+function render(report) {
+  if (report.error) return `not-measurable: ${report.error.category}\n`;
+  return [`status: ${report.status}`, ...Object.entries(report.metrics).map(([key, metric]) =>
+    `${key}: ${metric.status === 'measured' ? metric.value : `not-measurable (${metric.reasons.join(', ')})`}`)].join('\n') + '\n';
+}
+
+/** The real CLI boundary; callers may route its output to their own streams. */
+export async function main(argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  let args;
+  try {
+    args = argumentsFor(argv);
+    if (args.action === '--help') { io.stdout.write(HELP); return 0; }
+    if (args.action === '--version') {
+      const manifest = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf8'));
+      io.stdout.write(`${manifest.version}\n`);
+      return 0;
+    }
+    const root = path.resolve(args.root);
+    // Inspect BOTH paths before opening either snapshot for content.
+    const registryFile = await inspect(root, args.registry);
+    const checkinFile = await inspect(root, args.checkins);
+    const registry = await readSnapshot(registryFile);
+    const checkins = await readSnapshot(checkinFile);
+    const report = auditCheckins({ registry, checkins, repos: args.repos, at: args.at });
+    io.stdout.write(args.json ? `${JSON.stringify(report)}\n` : render(report));
+    return report.status === 'measured' ? 0 : 3;
+  } catch (error) {
+    const category = error.category || 'input-io-error';
+    const errno = typeof error.code === 'string' && /^[A-Z0-9_]+$/.test(error.code) ? error.code : undefined;
+    const report = { version: 1, status: 'not-measurable', error: { category, ...(errno ? { errno } : {}) } };
+    io.stderr.write(`fleet-checkin-audit: ${category}${errno ? ` (${errno})` : ''}\n`);
+    io.stdout.write((args?.json || argv.includes('--json')) ? `${JSON.stringify(report)}\n` : render(report));
+    return error.exit || 2;
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; }, () => {
+    process.stderr.write('fleet-checkin-audit: output-io-error\n');
+    process.exitCode = 2;
+  });
+}

package/scripts/fleet-checkin.mjs

@@ -15,6 +15,10 @@
  * Then reads the navigator lease and emits `orchestrator.fleet.checkin` with the
  * payload `{ session, repo, modus, kandidaten, navigator_state }` — no paths, no
  * quota, no `auftrag_ref`.
+ * Without fleet integration, valid input exits 0 with `skipped: "no-fleet"` and no directory, file or event.
+ * That holds for `plattform: "kopflos"` too: the record cannot prove a coordinator started the run,
+ * and a write would create the navigator directory, which then flips every later solo session to
+ * fleet. A headless run without fleet integration applies the Standard-Auflagen instead (#1559 review).
  *
  * stdout: one JSON line
  * `{ ok, path, navigator_state, navigator_adresse, fallback_due_at, event }`.
@@ -29,16 +33,17 @@
  * Exit codes:
  *   0 — check-in written (an event failure only WARNs; `event: false` on stdout)
  *   1 — write error
- *   2 — invalid input (not JSON, not an object, or validation errors; no file)
+ *   2 — invalid input or semantic session ID occupied by another repo (no write/event)
  */
 
 import { randomBytes } from 'node:crypto';
-import { promises as fs } from 'node:fs';
+import { promises as fs, constants as fsConstants } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { emitEvent } from './lib/events.mjs';
 import {
   checkinPath,
+  fleetIntegrationEnabled,
   fallbackDueAt,
   navigatorDir,
   readNavigatorLease,
@@ -63,6 +68,7 @@ async function readStdin() {
  * planted symlink cannot redirect the chmod or the write.
  * @param {string} target
  * @param {object} record
+ * @returns {Promise<boolean>} false when another repo already owns the target
  */
 async function writeCheckinFile(target, record) {
   const checkinDir = path.dirname(target);
@@ -79,7 +85,46 @@ async function writeCheckinFile(target, record) {
     await fs.writeFile(tmp, JSON.stringify(record, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
     // The creation mode is filtered through the umask; pin it explicitly.
     await fs.chmod(tmp, 0o600);
+    let existing;
+    try {
+      // Fail-open on platforms without safe-open flags; never fall back to a
+      // potentially blocking read that follows symlinks.
+      if (typeof fsConstants.O_NOFOLLOW === 'number' && typeof fsConstants.O_NONBLOCK === 'number') {
+        const handle = await fs.open(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+        try {
+          const stat = await handle.stat();
+          const limit = 64 * 1024;
+          // Check-ins are small: non-files and larger targets are unreadable for
+          // this guard and fail-open. Bound reads even if the file grows after stat.
+          if (stat.isFile() && stat.size <= limit) {
+            const buffer = Buffer.alloc(limit);
+            let length = 0;
+            while (length < limit) {
+              const { bytesRead } = await handle.read(buffer, length, limit - length, length);
+              if (bytesRead === 0) break;
+              length += bytesRead;
+            }
+            if ((await handle.stat()).size <= limit) {
+              existing = JSON.parse(buffer.subarray(0, length).toString('utf8'));
+            }
+          }
+        } finally {
+          await handle.close();
+        }
+      }
+    } catch {
+      // Fail-open: an unreadable or invalid-JSON target gives the navigator no readable check-in to preserve.
+    }
+    if (typeof existing?.repo === 'string' && existing.repo !== record.repo) {
+      await fs.rm(tmp, { force: true });
+      process.stderr.write(`${PREFIX} semantic session ID ${record.session} is already occupied by another repo: ${JSON.stringify(existing.repo)}\n`);
+      return false;
+    }
+    // BV-004 ceiling: protects an already-visible foreign check-in, not concurrent
+    // writers between read and rename; revisit with atomic coordination when a
+    // simultaneous cross-repo collision is observed.
     await fs.rename(tmp, target);
+    return true;
   } catch (err) {
     await fs.rm(tmp, { force: true }).catch(() => {});
     throw err;
@@ -107,9 +152,22 @@ async function main() {
     return 2;
   }
 
+  if (!fleetIntegrationEnabled()) {
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      skipped: 'no-fleet',
+      path: null,
+      navigator_state: 'none',
+      navigator_adresse: null,
+      fallback_due_at: null,
+      event: false,
+    }) + '\n');
+    return 0;
+  }
+
   const target = checkinPath(record.session);
   try {
-    await writeCheckinFile(target, record);
+    if (!await writeCheckinFile(target, record)) return 2;
   } catch (err) {
     process.stderr.write(`${PREFIX} write failed: ${err instanceof Error ? err.message : String(err)}\n`);
     return 1;

package/scripts/lib/common.mjs

@@ -12,7 +12,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { promises as fs, existsSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { execSync } from 'node:child_process';
+import { commandOnPath } from './native-command.mjs';
 
 // ---------------------------------------------------------------------------
 // Path helpers
@@ -182,9 +182,7 @@ export function warn(message) {
  * @throws {Error} when jq is not on PATH
  */
 export function requireJq() {
-  try {
-    execSync('command -v jq', { stdio: 'ignore', shell: true });
-  } catch {
+  if (!commandOnPath('jq')) {
     throw new Error('jq is required but not installed. Install via: brew install jq');
   }
 }

package/scripts/lib/config/remote-hosts.mjs

@@ -18,7 +18,7 @@ import { preprocessBlockLinesNoDash } from './block-preprocess.mjs';
  *
  * Block shape:
  *   remote-hosts:
- *     - alias: m5                        # required; becomes `-H <alias>` argv
+ *     - alias: build-host                # required; becomes `-H <alias>` argv
  *       roles-allowed: [test, ui, perf]  # subset of ALLOWED_REMOTE_ROLES
  *       repo-path: ~/Projects/Alice   # optional
  *       claude-path: ~/.local/bin/claude # optional
@@ -54,7 +54,7 @@ export const ALLOWED_REMOTE_ROLES = Object.freeze(['test', 'ui', 'perf']);
 // The first character is anchored separately from the rest because a charset
 // cannot express a POSITION: an alias of `-H` passes any hyphen-inclusive
 // allowlist and then reaches argv as an OPTION token, where the CLI swallows the
-// operand behind it. Interior hyphens (`m5-box`) stay legal.
+// operand behind it. Interior hyphens (`build-host`) stay legal.
 const SAFE_NAME_RE = /^[A-Za-z0-9._][A-Za-z0-9._-]*$/;
 
 // `repo-path` / `claude-path` are filesystem paths handed to a remote shell —

package/scripts/lib/config.mjs

@@ -327,7 +327,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     // dispatched natively, exactly as before.
     //   impl: code-implementer      → native Agent dispatch (unchanged)
     //   impl: cursor:composer-2.5   → foreign model over the Cursor channel
-    //   test: ssh:m5                → same Claude, another host (#1160)
+    //   test: ssh:build-host        → same Claude, another host (#1160)
     // An unknown prefix is a typo or a channel this build cannot route, and
     // must fail loudly: silently accepting it would dispatch to an agent that
     // does not exist, which surfaces only as an empty wave much later.

package/scripts/lib/context-overhead-format.mjs

@@ -0,0 +1,57 @@
+/** Format Claude JSON accounting without inventing a price or its provenance. */
+import { isMainModule } from './is-main-module.mjs';
+import { COST_BASIS } from './telemetry/pricing.mjs';
+
+export const CONTEXT_OVERHEAD_HEADER =
+  'LABEL\tCONTEXT_TOK\tcache_create\tcache_read\toutput\tUSD\tCOST_BASIS\n';
+
+/**
+ * @param {string} text JSON response text
+ * @param {string} label measurement label
+ * @returns {string} TSV row, or a recognizable PARSE-ERROR / NO-USAGE row
+ */
+export function formatContextOverhead(text, label) {
+  let response;
+  try {
+    response = JSON.parse(text);
+  } catch {
+    return `${label}\tPARSE-ERROR\n`;
+  }
+  const usage = response?.usage;
+  // An error reply (e.g. "Not logged in") carries no usage; 0 tokens would be invented (#1547).
+  if (typeof usage !== 'object' || usage === null || Array.isArray(usage)) {
+    return `${label}\tNO-USAGE\n`;
+  }
+  const context =
+    (usage.input_tokens || 0) +
+    (usage.cache_creation_input_tokens || 0) +
+    (usage.cache_read_input_tokens || 0);
+  const cost = response?.total_cost_usd;
+  const validCost = typeof cost === 'number' && Number.isFinite(cost) && cost >= 0;
+  // Native numbers alone do not establish billing or API-list provenance.
+  const basis = validCost && response.cost_basis === COST_BASIS
+    ? response.cost_basis
+    : 'unknown';
+  return [
+    label, context, usage.cache_creation_input_tokens || 0,
+    usage.cache_read_input_tokens || 0, usage.output_tokens || 0,
+    validCost ? cost.toFixed(4) : 'unknown', basis,
+  ].join('\t') + '\n';
+}
+
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === '--header') {
+    process.stdout.write(CONTEXT_OVERHEAD_HEADER);
+  } else if (args.length === 2 && args[0] === '--') {
+    let text = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { text += chunk; });
+    process.stdin.on('end', () => {
+      process.stdout.write(formatContextOverhead(text, args[1]));
+    });
+  } else {
+    process.stderr.write('Usage: context-overhead-format.mjs --header | -- <label> (JSON on stdin)\n');
+    process.exitCode = 1;
+  }
+}