session-orchestrator 4.1.0 → 5.0.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,17 @@
 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,
+  buildOverflowRecord,
 } from '../scripts/lib/issue-budget.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
@@ -114,6 +121,25 @@ async function resolveSessionId(input, projectDir) {
   return resolveIssueBudgetSessionId(nativeRawId, currentSession);
 }
 
+/**
+ * The harness's id for THIS tool call, when it publishes one — the first half of
+ * a charge record's identity (see `chargeIssueBudget`). Several spellings are
+ * accepted because the payload key is the harness's to choose, and a missed id
+ * silently degrades to the deterministic command key rather than failing.
+ *
+ * Kept byte-identical in shape to the refund hook's copy: the two must resolve
+ * the same id from the same payload or the refund cannot find the charge.
+ *
+ * @param {object} input
+ * @returns {string|null}
+ */
+function resolveToolCallId(input) {
+  for (const value of [input?.tool_use_id, input?.toolUseId, input?.tool_call_id, input?.tool_id]) {
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+  return null;
+}
+
 /**
  * THE CHOICE (#1145) — stated once, so the loop behaviour is explicit rather
  * than emergent.
@@ -145,7 +171,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 +208,73 @@ 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, description: string|null,
+ *                               descriptionFile: string|null, repo: string|null,
+ *                               cwdChanged: boolean }>,
+ *           cwd?: 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,
+  cwd = null,
+  now = new Date().toISOString(),
+}) {
+  state.sessionId = sessionId;
+  for (const s of chargeable) {
+    state.overflow.push(buildOverflowRecord({
+      repoRoot: projectDir,
+      title: s.title,
+      description: s.description,
+      descriptionFile: s.descriptionFile,
+      repo: s.repo,
+      cwd,
+      cwdChanged: s.cwdChanged,
+      command: s.text,
+      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 +290,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 +304,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 +318,63 @@ 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, cwd: input.cwd,
+      })));
+    }
+  }
+
+  // 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.
+  // `toolCallId` + the statement index are the CHARGE RECORD's identity (#1347):
+  // the refund hook may only give back a slot it can find in `charged[]`, so the
+  // charge has to be recorded under the same pair the PostToolUseFailure payload
+  // for this very call will present. Absent an id, the deterministic
+  // session+command+index key carries it.
+  const toolCallId = resolveToolCallId(input);
+  const verdicts = statements.map((s, i) =>
+    chargeIssueBudget({
+      repoRoot: projectDir,
+      sessionId,
+      command: s.text,
+      title: s.title,
+      description: s.description,
+      descriptionFile: s.descriptionFile,
+      repo: s.repo,
+      cwd: input.cwd,
+      cwdChanged: s.cwdChanged,
+      toolCallId,
+      statementIndex: i,
+      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 +382,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 +393,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.1.0",
+  "version": "5.0.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",
@@ -36,6 +36,7 @@
     "output-styles/",
     "monitors/",
     "assets/",
+    "!assets/marketing/**",
     ".claude-plugin/",
     ".codex-plugin/",
     ".cursor-plugin/",
@@ -69,7 +70,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 +84,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/pi/prompts/ux-grill.md

@@ -0,0 +1,12 @@
+---
+description: Grill a running web app's UX — a deterministic mechanical pass (axe, target size, overflow, journeys) followed by a screenshot-grounded interrogation of the operator.
+argument-hint: "[url | manifest-path]"
+---
+
+# /ux-grill
+
+Use the Session Orchestrator command definition at `commands/ux-grill.md`.
+
+Arguments: $@
+
+Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

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-vitest-green.mjs

@@ -258,8 +258,10 @@ if (isMain) {
     const inFlight = inFlightFilesFromLogFile(logPath);
     if (inFlight.length > 0) {
       console.error(
-        `[ci] hint: ${inFlight.length} test file(s) in-flight when killed ` +
-          `(likely hang/slowdown): ${inFlight.join(', ')}`,
+        `[ci] KILL ARTEFACT — the shard timed out or was killed before vitest wrote its ` +
+          `result file (NOT a test failure). ${inFlight.length} file(s) were merely in-flight ` +
+          `at the kill: ${inFlight.join(', ')}. Re-run the shard; if it repeats, check runner ` +
+          `load/sharding before suspecting these files.`,
       );
     }
   }

package/scripts/dialectic-deriver.mjs

@@ -182,13 +182,21 @@ function countContentLines(body) {
  * dry-run mode, where there is no `mergePeerCard()` stats object to read).
  * Pure function — no I/O.
  *
- * Counts `<!-- BEGIN MANAGED: <name> -->` sentinels (the same grammar
- * `scripts/lib/peer-cards/merger.mjs` parses). A proposed body that carries
- * none — the LLM emits a bare full-body replacement per the current prompt
- * contract in {@link buildPrompt}, not per-section sentinels — still counts
- * as ONE delta: a non-empty full-body replacement is a real change to the
- * target, and an empty proposed body counts as zero (nothing to report for a
- * target the response never touched).
+ * Resolution order:
+ *   1. non-string or empty body → 0 (the response never touched the target);
+ *   2. `<!-- BEGIN MANAGED: <name> -->` sentinels present (the grammar
+ *      `scripts/lib/peer-cards/merger.mjs` parses) → their count;
+ *   3. otherwise the count of level-2 `## ` headings — the deriver's actual
+ *      output contract per {@link buildPrompt} is a bare full-body
+ *      replacement structured by `## ` headings, not sentinels (#1319: the
+ *      old sentinel-or-1 rule reported 1 for a 12-section body). Headings
+ *      inside ``` / ~~~ code fences are NOT counted;
+ *   4. a non-empty body with neither → 1 (a full-body replacement is still a
+ *      real change to the target).
+ *
+ * Dry-run only. Apply mode counts `mergePeerCard()` stats instead
+ * (`replaced + appended`, i.e. merged sentinel sections) — the two modes
+ * measure different quantities on the same event field.
  *
  * @param {string | undefined} diffText — `diff.user` or `diff.agent` from
  *   {@link parseResponse}; `undefined` when the target was not emitted.
@@ -197,7 +205,23 @@ function countContentLines(body) {
 export function countManagedSections(diffText) {
   if (typeof diffText !== 'string' || diffText.length === 0) return 0;
   const matches = diffText.match(/<!--\s*BEGIN\s+MANAGED:\s*[\w-]+\s*-->/g);
-  return matches && matches.length > 0 ? matches.length : 1;
+  if (matches && matches.length > 0) return matches.length;
+  let headings = 0;
+  let fence = null; // { char, len } while inside a code fence
+  for (const line of diffText.split(/\r?\n/)) {
+    const f = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (fence) {
+      // CommonMark close: same char, at least as long, no info string.
+      if (f && f[1][0] === fence.char && f[1].length >= fence.len && f[2].trim() === '') fence = null;
+      continue;
+    }
+    if (f) {
+      fence = { char: f[1][0], len: f[1].length };
+      continue;
+    }
+    if (/^## /.test(line)) headings += 1;
+  }
+  return headings > 0 ? headings : 1;
 }
 
 /**