session-orchestrator 4.0.1 → 4.2.0

package/hooks/pre-bash-issue-budget.mjs

@@ -17,10 +17,12 @@
  * Decision flow:
  *   G1 tool filter — only Bash is gated.
  *   G2 command is a non-empty string.
- *   G3 matcher — `gh|glab … issue create|new` only. PR/MR creation passes.
+ *   G3 matcher — `gh|glab … issue create|new` plus the REST route
+ *      (`gh|glab api … /issues`, #1163) only. PR/MR creation passes.
  *      Verb-resolved since #1145, so a wrapped (`nohup`), absolute-path or
  *      env-prefixed create is seen; a `--help` invocation is not (it creates
- *      nothing).
+ *      nothing). Since #1163 the matcher returns EVERY create statement of the
+ *      chain, and the cap charges ONE unit per statement.
  *   G4 config — `issue-budget` from CLAUDE.md/AGENTS.md. `mode: off` → allow.
  *   G3b bulk — a create inside a shell LOOP body creates an unknowable number
  *      of issues (#1145). `strict` → deny; `warn` → allow with an explicit
@@ -29,7 +31,8 @@
  *   G5 exemption — priority::critical / carryover class / broken-window /
  *      the overflow collector itself bypass the cap unconditionally, keeping
  *      the session-end promises at SKILL.md:319 and :1113 intact.
- *   G6 charge the counter in .orchestrator/runtime/issue-budget/<hash>.json
+ *   G6 charge the counter ONCE PER ISSUE-CREATE STATEMENT in
+ *      .orchestrator/runtime/issue-budget/<hash>.json
  *      (one file per session since #1141 — see scripts/lib/issue-budget.mjs
  *      `budgetStateRel`).
  *      under cap → allow; over cap + `warn` → allow with stderr notice;
@@ -50,13 +53,16 @@
 import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
 import { resolveProjectDir } from '../scripts/lib/platform.mjs';
 import { readJson } from '../scripts/lib/common.mjs';
-import { isIssueCreate, isLoopedIssueCreate, extractTitle } from './_lib/vcs-create-matcher.mjs';
+import { findIssueCreateStatements, isLoopedIssueCreate } from './_lib/vcs-create-matcher.mjs';
 import {
   loadIssueBudgetConfig,
   resolveIssueBudgetSessionId,
   chargeIssueBudget,
   classifyExemption,
   formatBlockReason,
+  readBudgetState,
+  writeBudgetState,
+  budgetStatePath,
 } from '../scripts/lib/issue-budget.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
@@ -145,7 +151,13 @@ async function resolveSessionId(input, projectDir) {
  *
  * NAMED CEILING (BV-004): a loop is detected by `do`/`done` in command position
  * (see `isLoopedIssueCreate`), so an UNROLLED bulk create — 50 create statements
- * chained with `&&` — is not a "loop" and is charged 50, correctly. Revisit this
+ * chained with `&&` — is not a "loop". Since #1163 it is charged 50, once per
+ * issue-create STATEMENT: until then this comment CLAIMED that behaviour while
+ * the code called `chargeIssueBudget` exactly once per Bash tool call with the
+ * whole command string, so `glab issue create --title A && glab issue create
+ * --title B` charged 1 for 2 (measured 2026-09-09). The claim is now true
+ * because `findIssueCreateStatements` supplies the per-statement units and the
+ * exemption is classified per statement too. Revisit this
  * choice if the overflow triage of a per-session counter file
  * (`.orchestrator/runtime/issue-budget/<hash>.json`) shows operators routinely
  * hitting this deny on loops over a KNOWN literal word list; the cheap answer
@@ -176,6 +188,59 @@ function formatLoopDenyReason(config) {
   ].join('\n');
 }
 
+/**
+ * Park every chargeable statement of a command that does NOT fit under the cap,
+ * and return a `formatBlockReason`-shaped verdict for the deny envelope.
+ *
+ * ## Why this is not `chargeIssueBudget`
+ *
+ * `chargeIssueBudget` decides ONE creation against the current count, and its
+ * strict branch parks only when the count is ALREADY at the cap. A chain of
+ * statements that straddles the cap (count 11, max 12, three creates) has no
+ * single call shape in that API: the first statement would be ALLOWED and
+ * counted, and the deny that follows would leave that count standing for an
+ * issue nobody created. So the fit is judged for the chain as a whole and the
+ * whole chain is parked — count and exempt untouched, because nothing ran.
+ *
+ * The exemption CLASSIFICATION still comes from the shared core
+ * (`classifyExemption`, applied by the caller); what is local here is only the
+ * bookkeeping write, through the module's own public `writeBudgetState`.
+ *
+ * An identity-less invocation (no session key) must not write at all — the
+ * legacy flat path is shared across sessions and writing it would reset a live
+ * session's count and drop its parked overflow. Same rule `chargeIssueBudget`'s
+ * `persist` applies; the deny still happens, only unrecorded.
+ *
+ * @param {{ projectDir: string, sessionId: string|null,
+ *           state: { count: number, exempt: number, overflow: object[], sessionId: string|null },
+ *           chargeable: Array<{ text: string, title: string|null }>,
+ *           config: { "max-per-session": number, mode: string, overflow: string },
+ *           now?: string }} opts
+ * @returns {{ count: number, max: number, overflowPath: string,
+ *             overflowSink: string, overflowCount: number }}
+ */
+function parkOverflow({
+  projectDir,
+  sessionId,
+  state,
+  chargeable,
+  config,
+  now = new Date().toISOString(),
+}) {
+  state.sessionId = sessionId;
+  for (const s of chargeable) {
+    state.overflow.push({ title: s.title ?? null, command: String(s.text).slice(0, 500), at: now });
+  }
+  if (sessionId !== null) writeBudgetState(projectDir, state);
+  return {
+    count: state.count,
+    max: config['max-per-session'],
+    overflowPath: budgetStatePath(projectDir, sessionId),
+    overflowSink: config.overflow,
+    overflowCount: state.overflow.length,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -191,8 +256,11 @@ async function main() {
   const command = input?.tool_input?.command;
   if (typeof command !== 'string' || command.length === 0) return emitAllow();
 
-  // G3 — shared matcher. Only ISSUE creation is capped; `pr`/`mr` create pass.
-  if (!isIssueCreate(command)) return emitAllow();
+  // G3 — shared matcher, PER STATEMENT (#1163). Only ISSUE creation is capped;
+  // `pr`/`mr` create pass. An empty list is the old `!isIssueCreate(command)`
+  // short-circuit, unchanged.
+  const statements = findIssueCreateStatements(command);
+  if (statements.length === 0) return emitAllow();
 
   const projectDir = resolveProjectDir() || process.cwd();
 
@@ -202,9 +270,12 @@ async function main() {
 
   // G3b — bulk creation whose multiplicity is not computable (#1145). The
   // exemption is asked FIRST, through the same classifier chargeIssueBudget
-  // uses, so a looped carryover sweep keeps its unconditional pass.
+  // uses, so a looped carryover sweep keeps its unconditional pass. It is asked
+  // on the FIRST issue-create statement's text, which is the very statement
+  // `isLoopedIssueCreate` judges — classifying it on the whole command would
+  // let an exempt NEIGHBOUR statement lift the loop deny.
   const uncountableBulk =
-    isLoopedIssueCreate(command) && !classifyExemption(command).exempt;
+    isLoopedIssueCreate(command) && !classifyExemption(statements[0].text).exempt;
   if (uncountableBulk && config.mode === 'strict') {
     // Nothing is charged and nothing is parked — the command is handed back
     // whole, which is what makes unrolling it the correct next action.
@@ -213,26 +284,50 @@ async function main() {
 
   const sessionId = await resolveSessionId(input, projectDir);
 
-  // G5 + G6 — exemption check and counter charge live in the shared core so
-  // the programmatic path (scripts/lib/spiral-carryover.mjs runCli) decides
-  // identically.
-  const verdict = chargeIssueBudget({
-    repoRoot: projectDir,
-    sessionId,
-    command,
-    title: extractTitle(command),
-    config,
-  });
+  // G5 pre-flight — a Bash call is ATOMIC from this hook's point of view: a
+  // deny refuses the WHOLE command, so not one of its statements runs. Charging
+  // statement-by-statement until one blocks would therefore count creations
+  // that never happened (and double-count them when the operator re-issues the
+  // command unrolled). So the fit is decided BEFORE any charge, and a command
+  // that does not fit parks every chargeable statement without counting any.
+  const chargeable = statements.filter((s) => !classifyExemption(s.text).exempt);
+  if (config.mode === 'strict' && chargeable.length > 0) {
+    const state = readBudgetState(projectDir, sessionId);
+    if (state.count + chargeable.length > config['max-per-session']) {
+      return emitDeny(formatBlockReason(parkOverflow({
+        projectDir, sessionId, state, chargeable, config,
+      })));
+    }
+  }
+
+  // G6 — charge ONE unit per issue-create STATEMENT. The decision itself stays
+  // in the shared core (scripts/lib/issue-budget.mjs), so the programmatic path
+  // (scripts/lib/spiral-carryover.mjs runCli) decides identically; what changed
+  // in #1163 is only HOW MANY times it is asked. Each statement is judged on
+  // its OWN text: `glab issue create --title REAL && glab issue create
+  // --label carryover --title X` is 1 charge + 1 exemption, never 2 exemptions.
+  const verdicts = statements.map((s) =>
+    chargeIssueBudget({
+      repoRoot: projectDir,
+      sessionId,
+      command: s.text,
+      title: s.title,
+      config,
+    }),
+  );
+  const verdict = verdicts[verdicts.length - 1];
+  const exemptions = verdicts.filter((v) => v.decision === 'exempt');
+  const blocked = verdicts.find((v) => v.decision === 'block');
 
-  if (verdict.decision === 'exempt') {
+  if (exemptions.length > 0) {
+    const reasons = [...new Set(exemptions.map((v) => v.reason))].join(', ');
     process.stderr.write(
-      `ℹ pre-bash-issue-budget: exempt (${verdict.reason}) — cap not charged ` +
-        `(${verdict.count}/${verdict.max})\n`,
+      `ℹ pre-bash-issue-budget: ${exemptions.length} exempt statement(s) (${reasons}) — ` +
+        `cap not charged (${verdict.count}/${verdict.max})\n`,
     );
-    return emitAllow();
   }
 
-  if (verdict.decision === 'warn') {
+  if (verdicts.some((v) => v.decision === 'warn')) {
     process.stderr.write(
       `⚠ pre-bash-issue-budget: session cap exceeded — ${verdict.count}/${verdict.max} ` +
         `issues created (mode: warn — allowing). Set \`issue-budget.mode: strict\` to enforce.\n`,
@@ -240,7 +335,9 @@ async function main() {
     return emitAllow();
   }
 
-  if (verdict.decision === 'block') {
+  if (exemptions.length === statements.length) return emitAllow();
+
+  if (blocked) {
     // Single channel (#906). formatBlockReason's multi-line text — overflow
     // store path, the [Backlog-Sammel] fold-in promise, the exemption list and
     // the cap-raising hint — used to go to stderr AND to a duplicated `exit 2`
@@ -249,7 +346,7 @@ async function main() {
     // to Claude (the actor that must re-file or defer the issue), while the
     // operator gets the first line as the systemMessage headline. Under exit 0
     // a stderr write would only reach the debug log — dead, but alive-looking.
-    emitDeny(formatBlockReason(verdict));
+    return emitDeny(formatBlockReason(blocked));
   }
 
   // A PERMITTED bulk create is charged ONCE, which is an undercount by

package/hooks/subagent-telemetry.mjs

@@ -64,6 +64,33 @@
  * `subagent_transcript_found: true` as token-bearing; summing across the
  * history double-counts the parent once per subagent.
  *
+ * TOKEN-DATA PROVENANCE — SERIES BREAK 2026-09-09 (schema_version 2, #1244).
+ * Until this fix `token_input` was the raw `usage.input_tokens` sum only, and
+ * `cache_read_input_tokens` / `cache_creation_input_tokens` were read nowhere in
+ * the repo. Under prompt caching virtually the whole prompt is cache traffic, so
+ * that number described a rounding error rather than the run: measured
+ * 2026-09-09 on agent af50d1eda37099e17, the ledger recorded token_input 56
+ * where its transcript holds 56 + 3,528,536 cache_read + 147,587 cache_creation
+ * = 3,676,179 — an understatement of 65,646×; session-wide 1,518 vs 85,271,214.
+ * (token_output was within ~11% and is unaffected.)
+ *
+ * From schema_version 2 onward:
+ *   token_input            = uncached + cache_read + cache_creation
+ *                            (BILLABLE PROMPT VOLUME — a redefinition, not a
+ *                            widening: v1 and v2 values are not comparable)
+ *   token_input_uncached   = raw usage.input_tokens          (additive)
+ *   token_cache_read       = usage.cache_read_input_tokens   (additive)
+ *   token_cache_creation   = usage.cache_creation_input_tokens (additive)
+ *   model                  = message.model, or null          (additive; enables pricing)
+ *   gen_ai.usage.input_tokens stays the RAW UNCACHED value (OTel semantic), so
+ *   it is deliberately ≠ token_input under v2. Two new OTel aliases carry the
+ *   cache buckets.
+ *
+ * FORWARD-ONLY. Nothing recomputes the v1 history, so consumers MUST gate any
+ * v2 sum on `schema_version >= 2` — `scripts/lib/session-token-rollup.mjs` does
+ * exactly that and reports the excluded v1 records as `legacy_v1_records`
+ * rather than silently folding them in.
+ *
  * A SECOND, independent defect rode along until #950: the requestId dedup kept
  * the FIRST usage block per id, which on a streaming transcript is a partial
  * snapshot (typically `output_tokens: 1`). Any record written before #950 —
@@ -391,13 +418,27 @@ function readStdinJson() {
  * so the present side still sums and the aggregate stays valid.
  *
  * NEVER throws. Any failure (missing/unreadable path, 0 assistant turns, parse
- * error) yields { tokenInput: null, tokenOutput: null } so the hook still exits 0.
+ * error) yields an all-null result so the hook still exits 0.
+ *
+ * Four buckets, not two (#1244 / schema_version 2): `input_tokens`,
+ * `cache_read_input_tokens`, `cache_creation_input_tokens` and `output_tokens`
+ * are accumulated SEPARATELY per deduped turn, because they are billed at three
+ * different rates. `model` is captured from `message.model` of the last kept
+ * block that carries one (null when absent) — it is what makes a cost estimate
+ * possible at all downstream.
  *
  * @param {string|undefined|null} transcriptPath — absolute path from stdin
- * @returns {{ tokenInput: number|null, tokenOutput: number|null }}
+ * @returns {{ tokenInputUncached: number|null, tokenCacheRead: number|null,
+ *   tokenCacheCreation: number|null, tokenOutput: number|null, model: string|null }}
  */
 function extractTranscriptUsage(transcriptPath) {
-  const nullResult = { tokenInput: null, tokenOutput: null };
+  const nullResult = {
+    tokenInputUncached: null,
+    tokenCacheRead: null,
+    tokenCacheCreation: null,
+    tokenOutput: null,
+    model: null,
+  };
   try {
     if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return nullResult;
     if (!fs.existsSync(transcriptPath)) return nullResult;
@@ -447,9 +488,15 @@ function extractTranscriptUsage(transcriptPath) {
       // Dedup by requestId — keep the LAST usage block per id (#950). The
       // repeats are cumulative streaming snapshots, so overwriting is what
       // promotes the partial first snapshot to the response's real total.
+      // Model id rides along with the usage block (#1244): it is per-turn data
+      // and the only thing that makes the record priceable downstream.
+      const turnModel = typeof obj.message?.model === 'string' && obj.message.model
+        ? obj.message.model
+        : null;
+
       const requestId = obj.requestId;
       if (typeof requestId === 'string' && requestId) {
-        byRequestId.set(requestId, usage);
+        byRequestId.set(requestId, { usage, model: turnModel });
         continue;
       }
 
@@ -461,9 +508,9 @@ function extractTranscriptUsage(transcriptPath) {
       // usable identity; anything else falls through to the individual count.
       const messageId = obj.message?.id;
       if (typeof messageId === 'string' && messageId) {
-        byMessageId.set(messageId, usage);
+        byMessageId.set(messageId, { usage, model: turnModel });
       } else {
-        unkeyable.push(usage);
+        unkeyable.push({ usage, model: turnModel });
       }
     }
 
@@ -472,23 +519,34 @@ function extractTranscriptUsage(transcriptPath) {
     // No assistant turns with usage → leave fields null (forward-compat).
     if (kept.length === 0) return nullResult;
 
-    let tokenInput = 0;
+    let tokenInputUncached = 0;
+    let tokenCacheRead = 0;
+    let tokenCacheCreation = 0;
     let tokenOutput = 0;
-    for (const usage of kept) {
+    let model = null;
+    for (const { usage, model: turnModel } of kept) {
       // Per-turn clamp (#624): add a turn's value ONLY when it is a non-negative
       // integer. A poisoned value (negative, NaN, float like 10.5) is skipped so
       // the good turns survive. An absent side contributes 0, not null.
       const inTok = usage.input_tokens;
+      const cacheRead = usage.cache_read_input_tokens;
+      const cacheCreation = usage.cache_creation_input_tokens;
       const outTok = usage.output_tokens;
-      if (Number.isInteger(inTok) && inTok >= 0) tokenInput += inTok;
+      if (Number.isInteger(inTok) && inTok >= 0) tokenInputUncached += inTok;
+      if (Number.isInteger(cacheRead) && cacheRead >= 0) tokenCacheRead += cacheRead;
+      if (Number.isInteger(cacheCreation) && cacheCreation >= 0) tokenCacheCreation += cacheCreation;
       if (Number.isInteger(outTok) && outTok >= 0) tokenOutput += outTok;
+      if (turnModel !== null) model = turnModel;
     }
 
-    // The aggregate is guaranteed a non-negative integer by per-turn clamping
-    // above (Σ of non-negative integers), so emit it directly.
+    // The aggregates are guaranteed non-negative integers by per-turn clamping
+    // above (Σ of non-negative integers), so emit them directly.
     return {
-      tokenInput,
+      tokenInputUncached,
+      tokenCacheRead,
+      tokenCacheCreation,
       tokenOutput,
+      model,
     };
   } catch {
     return nullResult;
@@ -657,7 +715,7 @@ async function main() {
     timestamp: new Date().toISOString(),
     event,
     agent_id: agentId,
-    schema_version: 1,
+    schema_version: 2,
     ...(agentType !== null ? { agent_type: agentType } : {}),
     ...(parentSessionId !== null ? { parent_session_id: parentSessionId } : {}),
   };
@@ -705,23 +763,51 @@ async function main() {
     // NO fallback to input.transcript_path: that path is the parent session
     // transcript, and reading it is the #949 defect (every stop inherited the
     // parent's running totals). A phantom stop gets null — the honest value.
-    const { tokenInput, tokenOutput } = subagentTranscriptFound
-      ? extractTranscriptUsage(subagentTranscriptPath)
-      : { tokenInput: null, tokenOutput: null };
-    if (tokenInput !== null) record.token_input = tokenInput;
+    const { tokenInputUncached, tokenCacheRead, tokenCacheCreation, tokenOutput, model } =
+      subagentTranscriptFound
+        ? extractTranscriptUsage(subagentTranscriptPath)
+        : {
+            tokenInputUncached: null,
+            tokenCacheRead: null,
+            tokenCacheCreation: null,
+            tokenOutput: null,
+            model: null,
+          };
+
+    // schema_version 2 (#1244): `token_input` is now BILLABLE PROMPT VOLUME —
+    // uncached + cache_read + cache_creation — and the three components are
+    // written additively beside it. See the file header § TOKEN-DATA PROVENANCE
+    // for the 2026-09-09 series break this creates.
+    if (tokenInputUncached !== null) {
+      record.token_input =
+        tokenInputUncached + (tokenCacheRead ?? 0) + (tokenCacheCreation ?? 0);
+      record.token_input_uncached = tokenInputUncached;
+      record.token_cache_read = tokenCacheRead;
+      record.token_cache_creation = tokenCacheCreation;
+    }
     if (tokenOutput !== null) record.token_output = tokenOutput;
 
+    // Model id (#1244) — null when the transcript exposes none. Cost is NOT
+    // computed here: pricing lives in scripts/lib/telemetry/pricing.mjs and is
+    // applied by the session rollup, so this hot-path hook keeps its import
+    // graph unchanged.
+    record.model = model;
+
     // 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 — use the native cost only, default null when absent.
+    // table is applied HERE — use the native cost only, default null when absent.
     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;
 
-    // OTel alias — #411 additive, schema_version=1 backwards-compat
-    record['gen_ai.usage.input_tokens'] = tokenInput;
+    // OTel alias — #411 additive. `gen_ai.usage.input_tokens` stays the RAW
+    // UNCACHED value (OTel semantic), which is why it is deliberately NOT equal
+    // to `token_input` under schema_version 2.
+    record['gen_ai.usage.input_tokens'] = tokenInputUncached;
+    record['gen_ai.usage.cache_read_input_tokens'] = tokenCacheRead;
+    record['gen_ai.usage.cache_creation_input_tokens'] = tokenCacheCreation;
     record['gen_ai.usage.output_tokens'] = tokenOutput;
     record['gen_ai.system'] = 'anthropic';
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "4.0.1",
+  "version": "4.2.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -69,7 +69,7 @@
   "dependencies": {
     "@babel/parser": "^7.26.0",
     "ajv": "^8.17.1",
-    "js-yaml": "^4.3.1",
+    "js-yaml": "^4.3.2",
     "mdast-util-to-string": "^4.0.0",
     "picomatch": "^4.0.4",
     "remark": "^15.0.0",
@@ -83,12 +83,12 @@
     "@commitlint/cli": "^19.6.0",
     "@commitlint/config-conventional": "^19.6.0",
     "@eslint/js": "^10.0.1",
-    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^10.2.1",
     "husky": "^9.1.7",
     "lint-staged": "^15.2.10",
     "prettier": "^3.0.0",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.11"
   },
   "overrides": {
     "vite": "^8.0.16",

package/scripts/baseline-archetypes.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/** Data-only lookup for the configured local bootstrap baseline. */
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { loadBaselineArchetypes } from './lib/baseline-archetypes.mjs';
+
+export async function main(argv = process.argv.slice(2)) {
+  const options = {};
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write('Usage: node scripts/baseline-archetypes.mjs [--repo PATH] [--archetype ID]\nOffline, read-only JSON lookup. Exit 0: public/private; exit 2: invalid configuration or contract.\n');
+      return 0;
+    }
+    if (!['--repo', '--archetype'].includes(arg) || !argv[index + 1] || argv[index + 1].startsWith('--')) {
+      process.stdout.write(`${JSON.stringify({ status: 'error', reason: 'invalid-arguments', archetypes: [], selected: null })}\n`);
+      return 2;
+    }
+    options[arg === '--repo' ? 'repoRoot' : 'archetype'] = argv[++index];
+  }
+  if (options.repoRoot) options.repoRoot = path.resolve(options.repoRoot);
+  const result = await loadBaselineArchetypes(options);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return result.status === 'error' ? 2 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exitCode = await main();

package/scripts/ci/assert-coverage-green.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Repository CI only: requires the checkout's Vitest config and dev dependencies.
+// Test-result JSON does not prove coverage. Check the structured coverage summary
+// against the same global percentage thresholds Vitest uses before writing a marker.
+// The caller removes both reports and the marker before starting the current run.
+
+import { readFileSync } from 'node:fs';
+import config from '../../vitest.config.mjs';
+
+const metrics = ['lines', 'functions', 'statements', 'branches'];
+const [summaryPath = 'coverage/coverage-summary.json', xmlPath = 'coverage/cobertura-coverage.xml'] = process.argv.slice(2);
+
+function requireValid(condition, reason) {
+  if (!condition) throw new Error(reason);
+}
+
+// Check completeness of the XML emitted by the configured Istanbul reporter.
+// This is an artifact check, not a DTD/schema evaluator; never fetch the DOCTYPE.
+function checkCobertura(xml, total) {
+  const stack = [];
+  let root;
+  let hasClassLine = false;
+  const parts = xml.match(/<[^>]*>|[^<]+/g) ?? [];
+  requireValid(parts.join('') === xml, 'malformed Cobertura artifact');
+  for (const part of parts) {
+    if (/^<\?xml\s[^<>]*\?>$|^<!DOCTYPE coverage SYSTEM "[^"<>]*">$/.test(part)) {
+      requireValid(!root, 'unexpected Cobertura declaration');
+      continue;
+    }
+    if (!part.startsWith('<')) {
+      requireValid(!part.trim() || stack.at(-1) === 'source', 'unexpected Cobertura content');
+      continue;
+    }
+    const tag = part.match(/^<(\/?)([A-Za-z][\w.-]*)((?:\s+[\w:-]+="[^"<>]*")*)\s*(\/?)>$/);
+    requireValid(tag, 'malformed Cobertura tag');
+    const [, closing, name, attributes, selfClosing] = tag;
+    if (closing) {
+      requireValid(!attributes && !selfClosing && stack.pop() === name, 'unbalanced Cobertura tags');
+    } else {
+      const entries = [...attributes.matchAll(/([\w:-]+)="([^"]*)"/g)].map((match) => [match[1], match[2]]);
+      requireValid(new Set(entries.map(([key]) => key)).size === entries.length, 'duplicate Cobertura attributes');
+      const values = Object.fromEntries(entries);
+      if (stack.length === 0) {
+        requireValid(!root && name === 'coverage' && !selfClosing, 'invalid Cobertura root');
+        root = values;
+      }
+      const path = [...stack, name].join('/');
+      if (path === 'coverage/packages/package/classes/class') {
+        requireValid(typeof values.filename === 'string' && values.filename.trim(), 'Cobertura class is missing a filename');
+      }
+      if (path === 'coverage/packages/package/classes/class/lines/line') {
+        requireValid(/^\d+$/.test(values.number) && Number(values.number) > 0
+          && /^\d+$/.test(values.hits), 'invalid Cobertura line record');
+        hasClassLine = true;
+      }
+      if (!selfClosing) stack.push(name);
+    }
+  }
+  requireValid(root && stack.length === 0, 'empty or incomplete Cobertura artifact');
+  requireValid(total.lines.total === 0 || hasClassLine, 'Cobertura artifact contains no class line records');
+  for (const [attribute, expected] of Object.entries({
+    'lines-valid': total.lines.total,
+    'lines-covered': total.lines.covered,
+    'line-rate': total.lines.pct / 100,
+    'branches-valid': total.branches.total,
+    'branches-covered': total.branches.covered,
+    'branch-rate': total.branches.pct / 100,
+  })) {
+    requireValid(root[attribute] !== undefined && root[attribute] !== ''
+      && Number(root[attribute]) === expected, `Cobertura ${attribute} disagrees with coverage summary`);
+  }
+}
+
+try {
+  const thresholds = config.test?.coverage?.thresholds;
+  requireValid(thresholds && Object.keys(thresholds).every((key) => metrics.includes(key)),
+    'unsupported coverage thresholds: expected global percentage thresholds');
+  const { total } = JSON.parse(readFileSync(summaryPath, 'utf8'));
+  requireValid(total && typeof total === 'object', 'missing coverage totals');
+  for (const metric of metrics) {
+    const threshold = thresholds[metric];
+    requireValid(Number.isFinite(threshold) && threshold >= 0 && threshold <= 100,
+      `missing or invalid configured ${metric} threshold`);
+    const data = total[metric];
+    requireValid(data && ['total', 'covered', 'skipped'].every((key) => Number.isSafeInteger(data[key]) && data[key] >= 0)
+      && data.total > 0 && data.covered <= data.total && data.skipped <= data.total
+      && Number.isFinite(data.pct) && data.pct >= 0 && data.pct <= 100,
+    `missing or invalid ${metric} coverage data`);
+    // Istanbul truncates percentages to two decimals; compare the reported
+    // percentage (Vitest's threshold input) only after checking its counters.
+    const percentage = Math.floor((100000 * data.covered / data.total) / 10) / 100;
+    requireValid(data.pct === percentage, `inconsistent ${metric} coverage percentage`);
+    requireValid(data.pct >= threshold, `${metric} coverage ${data.pct}% is below configured ${threshold}%`);
+  }
+  checkCobertura(readFileSync(xmlPath, 'utf8'), total);
+  console.log(`[ci] coverage verified: ${metrics.map((metric) => `${metric}=${total[metric].pct}%`).join(' ')}`);
+} catch (error) {
+  console.error(`[ci] coverage NOT VERIFIED: ${error.message}`);
+  process.exitCode = 1;
+}