session-orchestrator 5.10.0 → 5.11.0

package/evals/instruction-ablation/run.mjs

@@ -243,7 +243,7 @@ function runCell(variant, kase, run) {
   if (DRY) return { variant: variant.id, case: kase.id, run, dry: true, workdir: wd };
 
   let usage = {};
-  let cost = 0;
+  let cost = null;
   let text = '';
   let error = null;
   try {
@@ -255,7 +255,9 @@ function runCell(variant, kase, run) {
     });
     const j = JSON.parse(out);
     usage = j.usage || {};
-    cost = j.total_cost_usd || 0;
+    // Missing or non-numeric cost stays unknown; a reported 0 stays 0 (#1547).
+    const c = j.total_cost_usd;
+    cost = typeof c === 'number' && Number.isFinite(c) && c >= 0 ? c : null;
     text = typeof j.result === 'string' ? j.result : '';
   } catch (e) {
     error = String(e.message || e).slice(0, 300);
@@ -275,7 +277,7 @@ function runCell(variant, kase, run) {
     error,
     context_tokens: ctx,
     output_tokens: usage.output_tokens || 0,
-    cost_usd: Number(cost.toFixed(4)),
+    cost_usd: cost === null ? null : Number(cost.toFixed(4)),
     oracles,
     reply_excerpt: text.slice(0, 300),
     workdir: wd,
@@ -300,7 +302,7 @@ for (const kase of cases) {
       const rec = runCell(variant, kase, run);
       records.push(rec);
       if (!DRY) appendFileSync(outFile, JSON.stringify(rec) + '\n');
-      process.stderr.write(rec.dry ? 'built\n' : `${rec.pass ? 'PASS' : 'FAIL'} (${rec.cost_usd ?? 0} USD)\n`);
+      process.stderr.write(rec.dry ? 'built\n' : `${rec.pass ? 'PASS' : 'FAIL'} (${rec.cost_usd ?? 'unknown'} USD)\n`);
     }
   }
 }
@@ -324,13 +326,16 @@ for (const kase of cases) {
   console.log(row.join('\t'));
 }
 
-const spend = records.reduce((a, r) => a + (r.cost_usd || 0), 0);
+// One unknown cell makes the total unknown; a partial sum would read as complete.
+const spend = records.some((r) => r.cost_usd === null)
+  ? 'unknown'
+  : records.reduce((a, r) => a + r.cost_usd, 0).toFixed(2);
 const ctxAvg = (id) => {
   const c = records.filter((r) => r.variant === id && r.context_tokens);
   return c.length ? Math.round(c.reduce((a, r) => a + r.context_tokens, 0) / c.length) : 0;
 };
 console.log('\n=== mean context tokens by variant ===');
 for (const v of variants) console.log(`${v.id}\t${ctxAvg(v.id)}`);
-console.log(`\ntotal spend: USD ${spend.toFixed(2)}`);
+console.log(`\ntotal spend: USD ${spend}`);
 console.log(`results:     ${outFile}`);
 console.log(`workdirs:    ${ROOT}  (throwaway; inspect failures there, remove when done)`);

package/hooks/_lib/hook-import-set.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-10-05T10:45:41.038Z",
-  "head": "94dc4a0cf182a06492feb217162d290e9fd0e921",
+  "generated_at": "2026-10-10T12:04:56.821Z",
+  "head": "f4f6200c067d28025bf70e34296cd5ebabcfc7f8",
   "entries": [
     {
       "file": "hooks/_lib/atomic-json.mjs",
@@ -34,6 +34,12 @@
         "on-session-end.mjs"
       ]
     },
+    {
+      "file": "hooks/_lib/orchestrator-ignore.mjs",
+      "reachable_from": [
+        "on-session-start.mjs"
+      ]
+    },
     {
       "file": "hooks/_lib/profile-gate.mjs",
       "reachable_from": [
@@ -1158,6 +1164,19 @@
         "post-edit-validate.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/native-command.mjs",
+      "reachable_from": [
+        "on-session-end.mjs",
+        "on-session-start.mjs",
+        "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
+        "post-edit-validate.mjs",
+        "post-subagent-discovery-validator.mjs",
+        "pre-bash-issue-budget.mjs",
+        "pre-bash-templates-first.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/orphan-reaper/defaults.mjs",
       "reachable_from": [
@@ -1633,6 +1652,12 @@
         "skill-invocation-telemetry.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/telemetry/pricing.mjs",
+      "reachable_from": [
+        "subagent-telemetry.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/telemetry/queue.mjs",
       "reachable_from": [

package/hooks/_lib/orchestrator-ignore.mjs

@@ -0,0 +1,112 @@
+/**
+ * orchestrator-ignore.mjs — keep the plugin's runtime state out of `git status`
+ * in a repo that has never been bootstrapped (#1515 Pkt 5).
+ *
+ * Measured 2026-10-08 @ 644743cc: one SessionStart in a fresh `git init` repo
+ * left five untracked files under `.orchestrator/` (session.lock,
+ * current-session.json, host.json, runtime/lock-owner-proof.json,
+ * metrics/events.jsonl) and nothing ignored them. Bootstrapped repos get their
+ * runtime ignore lines from `skills/bootstrap/_shared-template.md`
+ * § store-lock-ignore; an un-bootstrapped one gets nothing.
+ *
+ * Root, not per writer (BV-003): 23 hook-reachable modules call mkdir, and
+ * `.orchestrator/` is created by whichever runs first. SessionStart is the first
+ * plugin hook of every session (hooks/hooks.json), so the one call in
+ * on-session-start.mjs covers the session. Because SessionStart runs async, a
+ * PreToolUse hook MAY have created the directory a moment earlier — which is
+ * why the decision keys on "nothing under .orchestrator/ is tracked" (one
+ * `git ls-files`), not on "the directory was just created".
+ *
+ * Invariants:
+ *   - A repo WITH `.orchestrator/bootstrap.lock` is never given the file. If it
+ *     carries a file this helper wrote (byte-identical), the file is removed:
+ *     after bootstrap, steering/, peers/, policy/ and the ledgers are durable
+ *     project data and must not stay ignored.
+ *   - An existing `.orchestrator/.gitignore` is never overwritten.
+ *   - Any tracked path under `.orchestrator/`, or git failing (no repo, no git
+ *     binary), means: write nothing.
+ *   - Never throws; returns a reason string for tests and diagnostics.
+ *
+ * The negations are the exact `.orchestrator/` paths a bootstrap run stages
+ * with `git add -- <file>` (BOOTSTRAP_FILES in skills/bootstrap/*-template.md,
+ * measured 2026-10-08). The Bootstrap Gate runs bootstrap in the SAME session
+ * this file was written, before the next SessionStart can remove it, and git
+ * refuses `git add` on an explicitly named ignored path. NAMED CEILING
+ * (BV-004): the list is hand-copied; revisit when a template adds a new
+ * `BOOTSTRAP_FILES+=(.orchestrator/...)` entry.
+ */
+
+import { readFile, writeFile, link, unlink, mkdir } from 'node:fs/promises';
+import { existsSync, lstatSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+
+/** Directories that hold durable project data, never plugin runtime output. */
+const PROJECT_DATA_DIRS = ['steering', 'peers', 'policy'];
+
+export const GENERATED_IGNORE = [
+  '# Written by session-orchestrator (#1515): this repo has no .orchestrator/bootstrap.lock,',
+  '# so the plugin runtime state below stays out of git status. Removed automatically',
+  '# at the first session start after /bootstrap.',
+  '*',
+  '!*/',
+  '!/bootstrap.lock',
+  '!/metrics/learnings.jsonl',
+  '!/metrics/sessions.jsonl',
+  '!/metrics/README.md',
+  '!/policy/quality-gates.json',
+  '',
+].join('\n');
+
+function trackedUnderOrchestrator(repoRoot) {
+  return new Promise((resolve) => {
+    execFile('git', ['ls-files', '-z', '--', '.orchestrator'], { cwd: repoRoot, timeout: 2000 }, (err, stdout) => {
+      if (err) return resolve(null); // unknown → caller writes nothing
+      resolve(stdout.length > 0);
+    });
+  });
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {Promise<'written'|'removed'|'bootstrapped'|'present'|'project-data'|'symlink'|'tracked'|'no-git'|'error'>}
+ */
+export async function ensureOrchestratorIgnore(repoRoot) {
+  try {
+    const dir = path.join(repoRoot, '.orchestrator');
+    const target = path.join(dir, '.gitignore');
+    if (existsSync(path.join(dir, 'bootstrap.lock'))) {
+      if (existsSync(target)) {
+        const current = await readFile(target, 'utf8').catch(() => null);
+        if (current === GENERATED_IGNORE) {
+          await unlink(target);
+          return 'removed';
+        }
+      }
+      return 'bootstrapped';
+    }
+    if (existsSync(target)) return 'present';
+    // Durable project data (bootstrap/_shared-template.md #store-lock-ignore)
+    // the user may hold untracked on purpose: ignoring it would hide it from
+    // git status without a word. Only plugin runtime output may be swept.
+    if (PROJECT_DATA_DIRS.some((d) => existsSync(path.join(dir, d)))) return 'project-data';
+    // A symlinked .orchestrator would put the file outside the repo.
+    if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) return 'symlink';
+    const tracked = await trackedUnderOrchestrator(repoRoot);
+    if (tracked === null) return 'no-git';
+    if (tracked) return 'tracked';
+    await mkdir(dir, { recursive: true });
+    // tmp + link: atomic, and link() fails with EEXIST instead of replacing a
+    // .gitignore another process created in between (rename would overwrite).
+    const tmp = `${target}.tmp-${process.pid}`;
+    await writeFile(tmp, GENERATED_IGNORE, 'utf8');
+    try {
+      await link(tmp, target);
+    } finally {
+      await unlink(tmp).catch(() => {});
+    }
+    return 'written';
+  } catch (err) {
+    return err && err.code === 'EEXIST' ? 'present' : 'error';
+  }
+}

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.10.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.11.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.10.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.11.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/on-session-end.mjs

@@ -43,6 +43,7 @@ import {
   release,
   loadOwnerProof,
   OWNER_PROOF_RELPATH,
+  isLockOwnedByProof,
 } from '../scripts/lib/session-lock.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
@@ -789,8 +790,14 @@ async function main() {
           // millisecond started_at cannot match any FUTURE lock, so it
           // self-invalidates), this just avoids the stale artifact. ENOENT
           // (no proof was ever written) lands in the same swallow.
+          // Only when the proof still describes the lock we released: since
+          // #1541 every acquire() rewrites it, so a successor that acquired
+          // during the awaited emit above owns a fresh proof we must not
+          // remove. A narrow window between this read and the unlink remains.
           try {
-            await fs.unlink(path.join(projectRoot, OWNER_PROOF_RELPATH));
+            if (isLockOwnedByProof(lock, loadOwnerProof({ repoRoot: projectRoot }))) {
+              await fs.unlink(path.join(projectRoot, OWNER_PROOF_RELPATH));
+            }
           } catch { /* best-effort — a leftover proof is self-invalidating */ }
         }
       } else {

package/hooks/on-session-start.mjs

@@ -36,6 +36,7 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { ensureOrchestratorIgnore } from './_lib/orchestrator-ignore.mjs';
 
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
 import { readNavigatorLease } from '../scripts/lib/fleet-protocol.mjs';
@@ -781,6 +782,12 @@ function maybeQueueConsentNudge() {
 async function main() {
   const projectRoot = resolveProjectDir();
 
+  // #1515 Pkt 5 — before this hook's own writers (host.json, session.lock,
+  // events.jsonl) run: an un-bootstrapped repo gets `.orchestrator/.gitignore`
+  // so the runtime state never shows up in `git status`. Bootstrapped repos
+  // pay two existsSync and nothing else. Never throws.
+  await ensureOrchestratorIgnore(projectRoot);
+
   // Read optional stdin payload in parallel with git info so we don't stall
   // the hook. Both are best-effort and the promise races against a 500 ms cap
   // inside readStdinJson itself.

package/hooks/post-bash-write-verify.mjs

@@ -1299,10 +1299,23 @@ async function main() {
     ? []
     : readPeerScopeRecords(path.dirname(scopePath), scope.wave, sidecarRaw);
   if (sidecarBinding.notify) {
-    messages.push(formatSidecarMismatchNotice(
-      path.relative(repoRoot, path.join(path.dirname(scopePath), 'filescopes', `wave-${scope.wave}.scopes.json`)),
-    ));
+    const relSidecar = path.relative(
+      repoRoot,
+      path.join(path.dirname(scopePath), 'filescopes', `wave-${scope.wave}.scopes.json`),
+    );
+    messages.push(formatSidecarMismatchNotice(relSidecar));
     warn = true;
+    // #1514 point 6 (HR-105) — the notice alone left its firing rate unmeasurable.
+    // Same once-per-new-hash dedupe as the notice (`bindPeerSidecar().notify`);
+    // awaited so the append cannot be lost to the process exiting.
+    try {
+      const { emitEvent } = await import('../scripts/lib/events.mjs');
+      await emitEvent(
+        'orchestrator.scope.sidecar_mismatch',
+        { hook: 'post-bash-write-verify', sidecar: relSidecar.split(path.sep).join('/'), wave: scope.wave },
+        { repoRoot: context.manifestRoot },
+      );
+    } catch { /* observability is best-effort — never blocks the notice */ }
   }
   const violations = [];
   for (const relPath of report) {

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.11.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",

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/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/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;
+  }
+}