session-orchestrator 5.10.0 → 5.11.0

package/scripts/validate-wave-scope.mjs

@@ -92,6 +92,7 @@ import {
   assertFileScopeSubset,
   assertTestSiblingCoverage,
   testSiblingExpansionApplies,
+  testSiblingsFor,
   TEST_SIBLING_EXPANSION_ROLES,
   findScopeCollisions,
   unionFileScopes,
@@ -663,6 +664,44 @@ function knownRepoFiles() {
   }
 }
 
+/**
+ * WARN — never fail — when two agents' RAW scopes are disjoint but test-sibling
+ * expansion hands both the same synthesized glob (#1026 point 2, owner decision
+ * option a). `scripts/lib/foo.mjs` and `hooks/foo.mjs` share no file, yet both
+ * expand to `tests/**\/foo*.test.mjs`, so the union grants each agent the
+ * other's tests. Exit code is unchanged: the glob is a GRANT that may match no
+ * file at all, so failing the wave on it would block plans that never collide.
+ *
+ * `role` gates expansion exactly as `--union` does; `undefined` (sidecar-only
+ * `--no-manifest`, or a manifest without a role) checks anyway, because there
+ * the expansion that will run later is unknown and silence would hide it.
+ * Compares synthesized siblings only, by exact string — a sibling glob one agent
+ * DECLARED by hand is not matched (named ceiling; revisit if a wave plan is seen
+ * declaring sibling globs explicitly). Overlapping globs of DIFFERENT basenames
+ * (`foo*` also covers `foo-bar.test.mjs`) are not matched either.
+ *
+ * @param {Array<{id?: string, files: string[]}>} agentScopes
+ * @param {string|undefined} role
+ */
+function warnSiblingGlobCollisions(agentScopes, role) {
+  if (role !== undefined && !testSiblingExpansionApplies({ role })) return;
+  const owners = new Map(); // sibling glob -> agent ids, first-seen order
+  agentScopes.forEach((rec, i) => {
+    const id = typeof rec.id === 'string' && rec.id.length > 0 ? rec.id : `<unnamed#${i}>`;
+    for (const glob of testSiblingsFor(rec.files)) {
+      const ids = owners.get(glob) ?? [];
+      if (!ids.includes(id)) ids.push(id);
+      owners.set(glob, ids);
+    }
+  });
+  for (const [glob, ids] of owners) {
+    if (ids.length < 2) continue;
+    warn(
+      `sibling-glob: agents ${ids.map((id) => `"${id}"`).join(', ')} are disjoint as declared but test-sibling expansion grants each of them ${glob} — split the same-basename files across waves or name the tests explicitly (#1026)`,
+    );
+  }
+}
+
 /**
  * Assert that no file is claimed by two agents of the SAME wave (#1020).
  * Exits 1 with one message per collision (plus one per duplicate agent id);
@@ -670,8 +709,8 @@ function knownRepoFiles() {
  *
  * @param {string} sidecarPath
  */
-function assertDisjointOrDie(sidecarPath) {
-  if (!reportScopeCollisions(sidecarPath)) process.exit(1);
+function assertDisjointOrDie(sidecarPath, role) {
+  if (!reportScopeCollisions(sidecarPath, role)) process.exit(1);
 }
 
 /**
@@ -683,12 +722,17 @@ function assertDisjointOrDie(sidecarPath) {
  * @param {string} sidecarPath
  * @returns {boolean} true when the wave is disjoint
  */
-function reportScopeCollisions(sidecarPath) {
+function reportScopeCollisions(sidecarPath, role) {
   const agentScopes = readAgentScopesOrDie(sidecarPath, '--assert-disjoint');
   const { ok, collisions, duplicateIds } = findScopeCollisions(agentScopes, {
     knownFiles: knownRepoFiles(),
   });
-  if (ok) return true;
+  // Only a raw-disjoint wave gets the sibling hint: its text says the scopes
+  // are disjoint as declared, which is false once a real collision exists.
+  if (ok) {
+    warnSiblingGlobCollisions(agentScopes, role);
+    return true;
+  }
 
   // Duplicate ids FIRST: they are a malformed plan, and a reader who fixes them
   // may well change which collisions remain.
@@ -708,6 +752,15 @@ function reportScopeCollisions(sidecarPath) {
   return false;
 }
 
+/**
+ * The manifest's `role` when it is a string, else `undefined` (unknown).
+ * @param {unknown} obj
+ * @returns {string|undefined}
+ */
+function roleOf(obj) {
+  return obj !== null && typeof obj === 'object' && typeof obj.role === 'string' ? obj.role : undefined;
+}
+
 /**
  * QUERY MODE (#1020): print `expandTestSiblings(unionFileScopes(scopes), {role})`
  * as JSON on stdout, using the MANIFEST'S own role. Replaces the manifest echo —
@@ -757,7 +810,7 @@ function validate(
     }
     // #1026.4 — the collision check reads only the sidecar, so a schema error
     // must not hide its findings: report both, exit 1 either way.
-    if (assertDisjointPath) reportScopeCollisions(assertDisjointPath);
+    if (assertDisjointPath) reportScopeCollisions(assertDisjointPath, roleOf(obj));
     process.exit(1);
   }
 
@@ -771,7 +824,7 @@ function validate(
   // violates BOTH the subset relation and disjointness must keep the older,
   // byte-pinned subset message. Only ever ADDS a failure mode.
   if (assertDisjointPath) {
-    assertDisjointOrDie(assertDisjointPath);
+    assertDisjointOrDie(assertDisjointPath, roleOf(obj));
   }
 
   // #1020 QUERY MODE — replaces the echo below; see the STDOUT CONTRACT note in

package/skills/claude-md-drift-check/checker.mjs

@@ -555,10 +555,11 @@ function buildSurfaceDescriptors(vaultDir, commandsDir) {
       id: 'test-count',
       noun: 'test files',
       actual: countTestFiles(vaultDir),
-      // "N test files" — the README badge claims a runtime PASS count
+      // "N test files" or "N+ test files" (an explicit lower bound).
+      // The README badge claims a runtime PASS count
       // ("9303 tests"), which a static checker cannot derive, so we match only
-      // the explicit file-count phrasing. No doc claims this today → skipped.
-      claimRe: /\b(\d+)\s+test\s+files?\b/gi,
+      // the explicit file-count phrasing.
+      claimRe: /\b(\d+)(\+)?\s+test\s+files?\b/gi,
       skipMsg: 'test-count: no tests/ directory found',
     },
   ];
@@ -1831,7 +1832,7 @@ function main() {
         }
       }
 
-      // Surface-count family: one EXACT-count drift check per active surface.
+      // Surface counts are exact, except explicit "N+ test files" lower bounds.
       // A surface only fires when the doc makes an explicit numeric claim that
       // its regex matches; an unclaimed surface produces no errors (skip).
       for (const surface of activeSurfaces) {
@@ -1840,10 +1841,11 @@ function main() {
         let m;
         while ((m = re.exec(line)) !== null) {
           const claimed = parseInt(m[1], 10);
-          if (claimed !== surface.actual) {
+          const lowerBound = surface.id === 'test-count' && m[2] === '+';
+          if (lowerBound ? surface.actual < claimed : claimed !== surface.actual) {
             const err = {
               check: surface.id, file: rel, line: lineNum,
-              message: `Narrative claims ${claimed} ${surface.noun} but actual on-disk count is ${surface.actual}`,
+              message: `Narrative claims ${claimed}${lowerBound ? '+' : ''} ${surface.noun} but actual on-disk count is ${surface.actual}`,
               extracted: m[0],
               count: { surface: surface.id, actual: surface.actual, claimed },
             };

package/skills/npm-publish/SKILL.md

@@ -39,7 +39,7 @@ The script gates mechanics. These three are yours, and it will not make them for
 
 **2. What a leak means when one is found.** A hit from the leakage gate is not a pattern to silence. Decide which of two it is: a real leak (fix `package.json` `files`, re-pack, re-check) or genuine over-matching (fix `LEAKAGE_PATTERNS` in `scripts/release.mjs` **with a test**). There is no third option, and neither is "publish anyway and clean it up in the next version" — an npm publish is not revocable, and unpublishing burns the version number permanently. Operator handling detail: `docs/distribution/npm-publish-checklist.md` § 3.
 
-**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the target-confirmed npm receipt: a red preflight row, a lagging `github` mirror, CI not green on the exact commit **on either platform** (`--check` carries both `ci-green-on-head` for GitLab and `ci-green-on-head-github` for the mirror, whose macOS matrix leg has no GitLab equivalent), a dead token, or a publish that did not issue the target receipt. These are cheap to fix and re-run from the top. Repair-in-place is only appropriate *after* that receipt, where the version is already immutable: registry propagation, a missing GitHub release, or a lagging site deploy can be reconciled because npm already has the correct artifact. When `--publish` reports **Post-publish reconciliation required**, **do not rerun `--publish`**; repair the listed state directly. `skills/release/SKILL.md` § Abort criteria is the operative list.
+**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the target-confirmed npm receipt: a red preflight row, a lagging `github` mirror, CI not green on the exact commit **on either platform** (`--check` carries both `ci-green-on-head` for GitLab and `ci-green-on-head-github` for the mirror, whose macOS matrix leg has no GitLab equivalent), a dead token, or a publish that did not issue the target receipt. These are cheap to fix and re-run from the top. Repair-in-place is only appropriate *after* that receipt, where the version is already immutable: registry availability (`--reconcile`), a missing GitHub release, or a lagging site deploy can be reconciled because npm already has the correct artifact. When `--publish` reports **Post-publish reconciliation required**, **do not rerun `--publish`**; repair the listed state directly. `skills/release/SKILL.md` § Abort criteria is the operative list.
 
 ## Failure-mode table
 
@@ -48,13 +48,13 @@ The script gates mechanics. These three are yours, and it will not make them for
 | `E403 ... Two-factor authentication or granular access token with bypass 2fa enabled is required` — no OTP prompt | Account has no 2FA enrolled AND token (if any) lacks Bypass-2FA | Create granular token with all four requirements above, or enroll 2FA |
 | Same E403 despite a fresh token | Token created without the Bypass-2FA checkbox, or Read-only, or package-scoped on a first publish | Re-create: RW + All packages + Bypass-2FA |
 | `npm whoami` silent or non-zero | Token expired, or `.env.local` missing | Re-create the token; do not proceed — the preflight fails this row on purpose |
-| `E404` on `npm view` after a target-confirmed publish receipt | Registry propagation (rare, seconds) | Let the script finish its tag/push/GitHub/site tail, then reconcile the registry result; do **not** rerun `--publish` |
+| `E404` on `npm view <pkg>@<target>` after a target-confirmed publish receipt (npm answered HTTP 202) | The upload is **accepted, not yet available**. npm scans every new publish before it becomes installable: "typically around five minutes", "up to 15 minutes or more" at peak or depending on content/size, no service guarantee; the outcome may be published, **held for manual review**, or **blocked** (GitHub changelog 2026-07-28, read 2026-10-08, npm CLI 11.19.0). 5.10.0 stayed 404 for more than 25 minutes. A 404 alone does **not** tell you which of these applies — the package token cannot see the scan state | Let the script finish its tag/push/GitHub/site tail, then run `node scripts/release.mjs --reconcile --target <target>` (read-only, resumable; exit 0 only once installable). While still `pending`, check the owner-visible side: npm says a blocked package's publisher "may receive a notification with the option to appeal" — look at the npm account notifications/e-mail of the publishing account and the package page on npmjs.com. Do **not** rerun `--publish` and do not declare it blocked from the 404 |
 | `ENEEDAUTH` | No login/token at all | Token flow above, or `npm login` |
 | OTP prompt appears but flow is non-interactive (`!`-prefix, script) | No TTY for the prompt | Use the token flow, or a real terminal |
 
 ## Post-publish — the human half
 
-`--publish` attempts registry verification and polls the live site itself. A target-confirmed receipt plus a delayed registry result is a reconciliation outcome, not a failed publish or a retry instruction. What still needs a person:
+`--publish` attempts registry verification and polls the live site itself. A target-confirmed receipt plus a delayed registry result is a reconciliation outcome, not a failed publish or a retry instruction: the receipt is persisted as `.orchestrator/runtime/release-<target>.json`, and `--reconcile` resumes from it. The proof lives in the gitignored runtime dir of the checkout or worktree that ran `--publish`: run `--reconcile` from that same checkout, because any other checkout reports `proof-missing`. What still needs a person:
 
 1. **Rotate/delete the token** at https://www.npmjs.com/settings/<user>/tokens. A token that ever transited a conversation, a screenshot, or any log is burned — rotate immediately.
 2. **pi.dev gallery**: indexing is asynchronous — check https://pi.dev/packages later; do not block on it.

package/skills/release/SKILL.md

@@ -48,7 +48,7 @@ The same reading shows the other half: the GitHub releases for 3.15/3.18/3.19/3.
 6. **Preflight.** `node scripts/release.mjs --check --json` — every row green. Run this after the release commit is pushed and its CI succeeds: the preflight requires a clean working tree, exact HEAD parity on both remotes and green CI on that commit. It derives its target from `package.json`, so checking the pre-bump version instead produces registry- and tag-collision failures.
 7. **Publish.** `node scripts/release.mjs --publish` — **give it ≥600 s of wall clock, or run it in the background.** The script sets no spawn timeout on purpose (a kill mid-`npm publish` or mid-push is the very failure the receipt boundary exists to avoid), and the tail is slow by construction: each of the two `git push` remotes re-runs the husky pre-push full gate, plus up to 120 s of live-site polling. A 3-minute default command timeout kills it mid-tail.
 
-   The target-confirmed npm receipt is the irreversible boundary. Before that receipt, any failure aborts normally. After it, never rerun `--publish`: registry propagation timeout/query/wait failures are reconciliation while the script still tags, pushes `main` + tag to both remotes, handles the GitHub release, and polls the live site. If tag/push fails after the receipt, the dependent GitHub-release and site steps are skipped and the script returns structured reconciliation guidance instead. Add the GitHub release for the new tag (`gh release create`) as part of this step, not "later" — "later" is what produced the three-second backfill above.
+   The target-confirmed npm receipt is the irreversible boundary. Before that receipt, any failure aborts normally. After it, never rerun `--publish`: the script writes the publish proof `.orchestrator/runtime/release-<target>.json` (checked archive sha256 + sha512 integrity, receipt time, commit, tag), and a registry availability timeout/query/wait failure is reconciliation while the script still tags, pushes `main` + tag to both remotes, handles the GitHub release, and polls the live site. If tag/push fails after the receipt, the dependent GitHub-release and site steps are skipped and the script returns structured reconciliation guidance instead. Add the GitHub release for the new tag (`gh release create`) as part of this step, not "later" — "later" is what produced the three-second backfill above.
 
 Steps 2–7 are one continuous act. A release left parked between step 4 and step 7 is exactly the `3.18.0` state: every surface says released, the registry disagrees.
 
@@ -68,7 +68,7 @@ Steps 2–7 are one continuous act. A release left parked between step 4 and ste
 
 ## After
 
-`--publish` reports either **Release complete** or **Post-publish reconciliation required**. The latter means npm accepted the target release but registry propagation, tag/push, GitHub-release handling, or the live-site check still needs repair; a tag/push failure explicitly skips its dependent GitHub-release and site steps. **Do not rerun `--publish`**: reconcile the listed state directly, because a second publish cannot replace the immutable version. Exit `1` means a preflight/check failure or post-publish reconciliation is required; exit `2` remains a system/usage failure before the receipt.
+`--publish` reports either **Release complete** or **Post-publish reconciliation required**. The latter means npm accepted the target release but registry propagation, tag/push, GitHub-release handling, or the live-site check still needs repair; a tag/push failure explicitly skips its dependent GitHub-release and site steps. **Do not rerun `--publish`**: reconcile the listed state directly, because a second publish cannot replace the immutable version. For the registry state run `node scripts/release.mjs --reconcile --target X.Y.Z [--json]` — read-only (no publish, tag, push or repo pack), bounded and resumable: it reports `installable` (exit 0) only when the exact version is served as `latest` with the proof's integrity AND a consumer download hashes to it, or `superseded` (exit 0: same checks pass, but `latest` already points at a later release); otherwise `pending` (rerun later), `failed` (integrity mismatch) or `proof-missing` (exit 1 — success is never inferred from `latest`). See `skills/npm-publish/SKILL.md` § Failure-mode table for why an accepted upload can stay unavailable. Exit `1` means a preflight/check failure or post-publish reconciliation is required; exit `2` remains a system/usage failure before the receipt.
 
 After a complete release, `--publish` prints the remaining manual items (token rotation, async gallery indexing). Rotate the npm token — write tokens are short-lived by policy, and a token that transited a log or a chat is burned.
 

package/skills/repo-audit/SKILL.md

@@ -118,7 +118,7 @@ Commands resolved from Session Config per Phase 1.
 | Auth-at-boundary pattern (`requireAuth`) | `grep -r 'requireAuth' --include='*.ts' src/ 2>/dev/null \|\| echo "N/A (no src/)"` |
 | Zod validation on inputs | `grep -r 'z\.object\|z\.string\|z\.parse\|safeParse' --include='*.ts' src/ 2>/dev/null \|\| echo "N/A"` |
 | No hardcoded secrets (scan for API key patterns) | `grep -r 'sk-\|api_key\s*=\s*"' --include='*.ts' --include='*.mts' --exclude-dir=node_modules . 2>/dev/null` — warn if found |
-| No PAT/token in settings-allowlist entries (`.claude/settings.json`, `.claude/settings.local.json` — on-disk, incl. untracked) | `grep -nEo 'glpat-[A-Za-z0-9_-]{20,}\|ghp_[A-Za-z0-9]{36,}\|github_pat_[A-Za-z0-9_]{22,}\|sk-ant-[A-Za-z0-9_-]{20,}\|AKIA[0-9A-Z]{16}' .claude/settings.json .claude/settings.local.json 2>/dev/null \| grep -vE 'AKIAIOSFODNN7EXAMPLE\|-PLACEHOLDER'` — **fail** if any match (hard — unlike the `sk-` heuristic above, these 5 prefixes are high-signal; see SEC-021 in `.claude/rules/security.md`). This check is required because `check-owner-leakage.mjs` scans `git ls-files` only — `settings.local.json` is gitignored/untracked by convention and structurally invisible to it. |
+| No PAT/token in settings-allowlist entries (`.claude/settings.json`, `.claude/settings.local.json` — on-disk, incl. untracked) | `grep -nEo 'glpat-[A-Za-z0-9_-]{20,}\|ghp_[A-Za-z0-9]{36,}\|github_pat_[A-Za-z0-9_]{22,}\|sk-ant-[A-Za-z0-9_-]{20,}\|AKIA[0-9A-Z]{16}' .claude/settings.json .claude/settings.local.json 2>/dev/null \| grep -vE 'AKIAIOSFODNN7EXAMPLE\|-PLACEHOLDER'` — **fail** if any match (hard — unlike the `sk-` heuristic above, these 5 prefixes are high-signal; see SEC-025 in `.claude/rules/security.md`). This check is required because `check-owner-leakage.mjs` scans `git ls-files` only — `settings.local.json` is gitignored/untracked by convention and structurally invisible to it. |
 | `.env*` files not tracked | `git ls-files | grep '\.env'` — fail if any `.env` (not `.env.example`) tracked |
 | `.env.example` documents all secrets | `ls .env.example 2>/dev/null` |
 

package/skills/session-end/metrics-collection.md

@@ -17,9 +17,9 @@ Finalize session metrics by reading the wave data accumulated during execution:
    - `total_duration_seconds`: from `started_at` to now (ISO 8601 diff)
    - `total_waves`: count of completed waves
    - `total_agents`: sum of agents across all waves
-   - `total_files_changed`: unique files changed across entire session (from `git diff --stat`)
+   - `total_files_changed`: unique files changed across entire session (from `git diff --stat`). **Not measured** (empty `$SESSION_RANGE`, #1505): the value is unknown, not zero — write `total_files_changed: 0` (`validateSession` requires a non-negative number; `null` or omitting the key is rejected) AND `_backfill_incomplete_fields: ["total_files_changed"]` (append if the array exists), which marks that 0 as a placeholder, the same pair `scripts/lib/session-record-repair.mjs` writes. A bare 0 without the marker claims a measured "no changes".
    - `agent_summary`: `{complete: N, partial: N, failed: N, spiral: N}`
-   - **Coordinator-direct fallback (#1321):** when Wave History is empty AND the session ran coordinator-direct (housekeeping — `scripts/lib/session-shape.mjs:364-376` resolves it to ONE coordinator-direct wave that `/go` never hands to wave-executor, so no wave metrics are captured — or the express path), do NOT write `waves: []` / `total_waves: 0`. Write exactly one wave entry `{wave: 1, role: "Housekeeping", agent_count: 0, coordinator_direct: true, files_changed: <N>, quality: "<pass|fail|skip — the close quality-gate result>"}` with `total_waves: 1`, `total_agents: 0`. On this path both that wave's `files_changed` and `total_files_changed` are `git diff --name-only "$SESSION_RANGE" | wc -l` (accessor: `plan-verification.md` § SESSION_START_REF accessor; an empty `$SESSION_RANGE` is a skip, not zero changes — the validator still requires a number there, so name the accessor's reason in the record's `notes` beside it). The single definition of this shape is `isCoordinatorDirectHousekeeping(record)` in `scripts/lib/session-schema/filters.mjs` (every wave `role: "Housekeeping"` AND `coordinator_direct: true`). Consumers key on it (eval gate-health, evolve effective-sizing), so write `role` and `coordinator_direct` exactly as shown. `session_type` alone never marks it.
+   - **Coordinator-direct fallback (#1321):** when Wave History is empty AND the session ran coordinator-direct (housekeeping — `scripts/lib/session-shape.mjs:364-376` resolves it to ONE coordinator-direct wave that `/go` never hands to wave-executor, so no wave metrics are captured — or the express path), do NOT write `waves: []` / `total_waves: 0`. Write exactly one wave entry `{wave: 1, role: "Housekeeping", agent_count: 0, coordinator_direct: true, files_changed: <N>, quality: "<pass|fail|skip — the close quality-gate result>"}` with `total_waves: 1`, `total_agents: 0`. On this path both that wave's `files_changed` and `total_files_changed` are `git diff --name-only "$SESSION_RANGE" | wc -l` (accessor: `plan-verification.md` § SESSION_START_REF accessor; an empty `$SESSION_RANGE` is a skip, not zero changes — write the unmeasured pair from the `total_files_changed` bullet above and name the accessor's reason in the record's `notes`). The single definition of this shape is `isCoordinatorDirectHousekeeping(record)` in `scripts/lib/session-schema/filters.mjs` (every wave `role: "Housekeeping"` AND `coordinator_direct: true`). Consumers key on it (eval gate-health, evolve effective-sizing), so write `role` and `coordinator_direct` exactly as shown. `session_type` alone never marks it.
 3. Read `.orchestrator/metrics/events.jsonl` **once** and build both event aggregates in a single pass. If the file does not exist, treat both aggregates as zero events (omit both fields per the rules below) — do NOT fail the session close.
 
    Filter all lines where `session == <session_id>`, then partition by `event` value:

package/skills/session-end/session-metrics-write.md

@@ -31,7 +31,7 @@
 
 1a. **Token Rollup (#644, #1244 — mechanical since #1436)** — no coordinator action. `scripts/emit-session.mjs` (step 2) runs `rollupSessionTokens()` itself whenever the incoming record carries no `total_tokens`: it resolves the session's raw UUID from `.orchestrator/current-session.json` (adopted only when its `semantic_session_id` equals the record's `session_id` and no process-local session id contradicts it), joins the sibling `subagents.jsonl` on `parent_session_id`, and fills `total_tokens`, `total_token_input`, `total_token_output`, the three cache buckets, `total_cost_usd`, `subagents_with_tokens`, `matched_records`, `cost_records_priced`, `cost_records_total` and `_token_schema` for every key the record does not already carry — plus `raw_session_id`. No matching records, an unreadable ledger or a foreign marker omits the fields with a WARN on stderr, never a fabricated `0`. An explicit key on `$METRICS_ENTRY` still wins. The same UUID also backs `session_start_ref` when STATE.md has none (the `head_sha` of the session's own `orchestrator.session.started` event).
 
-   **Semantics:** `null` totals mean "no token data was captured for this session" — this is NOT the same as zero cost. Do NOT coerce null to 0 when displaying or summing across sessions. The same holds for `total_cost_usd`: it is omitted whenever `cost_records_priced < cost_records_total` (#1475) — at least one cost-relevant subagent record could not be priced (a model the price table does not know, a token-bearing turn naming no model, a transcript that yielded no tokens, e.g. one over the hook's size cap, or an agent with a start record whose stop found no transcript of its own, mostly `workflow-subagent`, or an agent known only from `schema_version` 1 records — #1487 Pkt 1) — and also when `cost_records_total` is 0, because there was nothing to price. It is never "$0" for an unknown cost and never a partial sum over the v2 agents the ledger can see. Phantom stops (#939, no start record) are no agents and never count. The two counters are persisted beside it, so a missing cost says whether part of the session was unpriceable or nothing was priceable. Blind spots remain: an agent whose start record fell outside the hook's tail window looks like a phantom, an agent with neither start nor stop record is invisible. A session spanning the 2026-09-09 schema boundary therefore reports no cost (its v1 agents are unpriced candidates since 2026-10-02; before, it was priced over its v2 records only — 4 distinct fleet sessions carried such a partial sum). A subagent whose turns span several models carries a per-model `models_usage` breakdown in `subagents.jsonl` (#1470) and is priced part by part. The emit-session warning names the reason via `match_status` (ledger absent, ledger with no readable records, or records present but none for the own raw UUID); none of these means zero cost.
+   **Semantics:** `null` totals mean "no token data was captured for this session" — this is NOT the same as zero cost. Do NOT coerce null to 0 when displaying or summing across sessions. The same holds for `total_cost_usd`: it is omitted whenever `cost_records_priced < cost_records_total` (#1475) — at least one cost-relevant subagent record could not be priced (a model the price table does not know, a token-bearing turn naming no model, a transcript that yielded no tokens, e.g. one over the hook's size cap, or an agent with a start record whose stop found no transcript of its own, mostly `workflow-subagent`, or an agent known only from `schema_version` 1 records — #1487 Pkt 1) — and also when `cost_records_total` is 0, because there was nothing to price. It is never "$0" for an unknown cost and never a partial sum over the v2 agents the ledger can see. Phantom stops (#939, no start record) are no agents and never count. The two counters are persisted beside it, so a missing cost says whether part of the session was unpriceable or nothing was priceable. Blind spots remain: an agent whose start record fell outside the hook's tail window looks like a phantom, an agent with neither start nor stop record is invisible. A session spanning the 2026-09-09 schema boundary therefore reports no cost (its v1 agents are unpriced candidates since 2026-10-02; before, it was priced over its v2 records only — 4 distinct fleet sessions carried such a partial sum). A subagent whose turns span several models carries a per-model `models_usage` breakdown in `subagents.jsonl` (#1470) and is priced part by part. A written `total_cost_usd` is the **API list-price equivalent** of the metered tokens, never a payment: subscription quota, purchased credits and the amount actually billed are invisible to the rollup, and no record states any of them. Since #1470 emit-session marks this with `cost_basis: "api-list-equivalent"` beside every `total_cost_usd` it writes, and writes `pricing_table_date` (the `PRICING_TABLE_DATE` of `scripts/lib/telemetry/pricing.mjs` that priced the session) beside the cost counters. A record without these fields predates #1470; its cost is a list-price estimate too, priced by an older table, not a verified bill. The emit-session warning names the reason via `match_status` (ledger absent, ledger with no readable records, or records present but none for the own raw UUID); none of these means zero cost.
 
    **Provenance (#949):** the rollup sums ONLY records carrying `subagent_transcript_found: true` — the flag the producer sets when it read the subagent's own transcript. Pre-#949 records carry the PARENT transcript's running totals and are excluded, so a session made up entirely of them now reports `null` rather than a fabricated sum (73 historical sessions, 96,148,781 phantom tokens, measured 2026-08-11). Two consequences for readers: totals already written into `sessions.jsonl` before 2026-08-11 were produced by the unfiltered recipe and are a series break, not a trend; and `matched_records` counts start records and phantom stops alike, so it is NOT the denominator for a coverage ratio — use `subagents_with_tokens` against the session's real agent count.
 

package/skills/session-start/references/phase-1-2-session-lock.md

@@ -10,7 +10,7 @@
 
 Acquire a distributed session-lock to detect parallel sessions in the same repo before initializing STATE.md. This prevents two concurrent Claude/Codex sessions from stomping each other's wave state and metrics writes.
 
-**Mechanical wiring (Epic #583, 2026-05-27):** The SessionStart hook (`hooks/on-session-start.mjs` → `hooks/_lib/lock-bootstrap.mjs`) now writes `.orchestrator/session.lock` mechanically BEFORE this skill's prose runs. The prose Phase 1.2 becomes confirmatory — it verifies the lock exists with the expected shape via `readLock({ repoRoot: process.cwd() })`. Re-call `acquire()` only if `readLock()` returns `null` (mechanical hook failed) OR the existing lock's raw `session_id` does not exactly match the current session's raw id (a rare divergence — surface via AUQ before overwriting). A matching `semantic_session_id`, STATE.md `session`, or owner proof cannot repair that mismatch. The decision flow below still applies to all five outcomes (active / stale / corrupt / unreadable / fs-error) when the prose path needs to acquire.
+**Mechanical wiring (Epic #583, 2026-05-27):** The SessionStart hook (`hooks/on-session-start.mjs` → `hooks/_lib/lock-bootstrap.mjs`) now writes `.orchestrator/session.lock` mechanically BEFORE this skill's prose runs. The prose Phase 1.2 becomes confirmatory — it verifies the lock exists with the expected shape via `readLock({ repoRoot: process.cwd() })`. Re-call `acquire()` only if `readLock()` returns `null` (mechanical hook failed) OR the existing lock's raw `session_id` does not exactly match the current session's raw id (a rare divergence — surface via AUQ before overwriting). A matching `semantic_session_id`, STATE.md `session`, or owner proof cannot repair that mismatch. The decision flow below still applies to all five outcomes (active / stale / corrupt / unreadable / fs-error) when the prose path needs to acquire. Every `ok: true` from `acquire()` / `forceAcquire()` also rewrites `.orchestrator/runtime/lock-owner-proof.json` for the new lock (#1541), so the `/close` release stays proof-gated; a failed proof write is reported as `result.ownerProof: { ok: false, reason }`, never thrown.
 
 ```javascript
 import { acquire, forceAcquire } from 'scripts/lib/session-lock.mjs';

package/skills/wave-executor/circuit-breaker.md

@@ -50,6 +50,7 @@ The coordinator determines each agent's status after the wave completes:
 | **partial** | Agent made progress but couldn't finish | Turn limit hit, or agent reports `STATUS: partial` | Carry forward remaining work to next wave with context |
 | **failed** | Agent couldn't make meaningful progress | Tool errors, invalid assumptions, agent reports `STATUS: failed` | Re-dispatch with corrected instructions and narrower scope |
 | **spiral** | Agent got stuck in an edit loop | Same file edited 3+ times (detected post-wave) | Revert agent's changes, narrow scope, split task if needed |
+| **limit** | Agent stopped by a session/usage limit or HTTP 429 mid-wave — not by its task | Output ends in a limit/429 error instead of a `STATUS:` line | No re-dispatch, no carryover issue: read `git diff` in the agent's worktree, finish the small remaining fix passes coordinator-direct, log a Deviation via `appendDeviationOnDisk()` (`scripts/lib/state-md.mjs`) |
 
 3. **Recovery protocol**:
    - FAILED agent → log in STATE.md, add fix task to next wave with corrected instructions, AND auto-create a carryover issue (see "Carryover Auto-Create" below) the first time this task is marked FAILED (check STATE.md Wave History for a prior `→ issue #NNN` on this task before filing).