baldart 3.35.2 → 3.36.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.36.0] - 2026-05-30
+
+Adds **opt-in session telemetry** to `/new` and `/prd`: append `-stats` (or `--stats`) to a run and, at the end, the skill writes a per-**agent-role** breakdown of REAL token consumption and wall-clock time. This finally answers "what took the most time and tokens in a `/new` run" — and feeds the v3.35.0 Review Profile Selector **data gate** (still pending precisely because `docs/metrics/` carried no per-role cost data). **No new `baldart.config.yml` keys** — the opt-in is a flag, not a config feature, so the schema-propagation rule does not apply.
+
+> **Zero model-token overhead.** The measurement is a **post-hoc Node script**, not a hook and not LLM self-reporting (the model has no reliable token counter). It reads the Claude Code session transcripts — the orchestrator's `<session>.jsonl` plus every `subagents/agent-*.jsonl` — which already carry `message.usage` (the four token counters) and per-message `timestamp`. On a real `/new` run the bulk of cost lives in the subagents (measured ~53M cumulative subagent tokens vs ~47k orchestrator output), and it is all captured. Cache-read tokens are kept **separate** from fresh input (they bill ~10×cheaper) so the breakdown doesn't mislead.
+
+### Added — `-stats` / `--stats` opt-in session telemetry
+
+- **[framework/scripts/analyze-session-tokens.js](framework/scripts/analyze-session-tokens.js)** (new): post-hoc aggregator. Locates the live transcripts from `$CLAUDE_CODE_SESSION_ID` + the cwd slug, sums the four `usage` counters (`fresh_input` / `cache_read` / `cache_creation` / `output`) **kept separate**, computes per-file wall-clock spans, and maps each subagent file → its role by matching the subagent's first prompt to the `Agent` tool_use `subagent_type` in the main transcript (verified 20/20 on a real `/new` batch; unmatched files bucket as `unknown`). Emits a human-readable `docs/metrics/sessions/<run_id>.md` (per-role table sorted by a weighted `cost_units` figure + totals + caveats) and a machine-readable `TELEMETRY_JSON=` line. **Fail-safe**: any error prints `stats: SKIPPED (<reason>)` and exits 0 — it can never abort a run.
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: arg parser strips `-stats` / `--stats` like `-full` and sets an internal `STATS` flag (composes with `-full`). **Phase 8 — Metrics Log** gains a `STATS`-gated step that invokes the script and enriches the same `skill-runs.jsonl` row with a `"cost"` object (`by_role` + `totals` + `run_wall_ms`). Without `-stats`, Phase 8 is byte-for-byte unchanged.
+- **[framework/.claude/skills/prd/SKILL.md](framework/.claude/skills/prd/SKILL.md)**: new **HARD RULE 18** — since `/prd` is conversational (no flag parser), the opt-in is detected once at **Step 1 (Kickoff)** from `$ARGUMENTS` and persisted as `stats_enabled` in the session state file (survives context compression / Step 0 resume). The **Step 7 Metrics Log** reads it and runs the same script (`--skill prd`), enriching its JSONL row identically.
+- **[framework/.claude/skills/prd/assets/state-template.md](framework/.claude/skills/prd/assets/state-template.md)**: new `stats_enabled` header field.
+
+### Notes & caveats
+
+- **Accurate in sequential mode.** Team-mode L0/L1 orchestrators can spawn background / nested sub-orchestrators in *separate* session dirs; their subagents are not under the top-level `<session>/subagents/`. The script detects the gap (Agent spawns in main with no local subagent file) and prints an explicit caveat with the excluded count rather than silently undercounting.
+- The per-role `wall(sum)` reflects active compute time; the headline run wall-clock is the orchestrator span and **includes human idle gaps** — both are labelled in the report.
+
 ## [3.35.2] - 2026-05-30
 
 Resolves the **3.35.1 known follow-up**: a flag introduced in a newer release (e.g. `--on-divergence`, v3.29.0) was rejected by an older global CLI with a cryptic `error: unknown option` **before** the `npx baldart@latest` auto-relaunch could self-upgrade — commander validates options during `program.parse()`, which runs *before* the action handler where the relaunch lives. The `update` command now parses **permissively**, so an unknown flag is captured instead of crashing the parser; the action then transparently relaunches under `@latest` (forwarding the raw argv so the unrecognized flag survives) or, when that isn't possible, emits an **actionable** error instead of commander's cryptic one. **No new `baldart.config.yml` keys** — the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.35.2
+3.36.0

package/framework/.claude/skills/new/SKILL.md

@@ -37,6 +37,8 @@ Parse the card IDs from the arguments. Cards can be specified as:
 
 If no card IDs are provided, ask the user which cards to implement.
 
+**Opt-in session telemetry (`-stats` / `--stats`)**: strip `-stats` / `--stats` from the args list exactly like `-full` (it is NOT a card ID), and set an internal flag `STATS=true` for this run. When present, Phase 8 additionally measures REAL token + wall-clock cost per agent role (coder, code-reviewer, …) by post-processing the session transcripts — zero model-token overhead, runs in Bash after the work is done. When absent, Phase 8 behaves exactly as before. The flag is batch-scoped and composes with `-full` (`/new FEAT-005 -full -stats`).
+
 ---
 
 ## Context Tracking (CRITICAL)
@@ -2287,6 +2289,19 @@ and QA quality over time.
 
 5. Note in tracker: `## Metrics Log: WRITTEN (run_id: batch-<FIRST-CARD-ID>)`
 
+6. **Session token telemetry (ONLY when `STATS=true`)** — if the run was invoked with `-stats` / `--stats`:
+
+   Measure REAL per-role token + wall-clock cost by post-processing the session transcripts (zero model-token cost — runs in Bash). Invoke:
+
+   ```bash
+   node .framework/framework/scripts/analyze-session-tokens.js \
+     --skill new --run-id "batch-<FIRST-CARD-ID>" --out-dir docs/metrics
+   ```
+
+   The script reads `$CLAUDE_CODE_SESSION_ID` from the environment and derives the transcript paths itself (do NOT pass `--session` / `--project-dir` — those are test-only overrides). It writes a human-readable breakdown to `docs/metrics/sessions/batch-<FIRST-CARD-ID>.md` and prints a summary plus a final `TELEMETRY_JSON=<json>` line.
+
+   Parse the `TELEMETRY_JSON=` line and **enrich the same skill-runs.jsonl row** you wrote in step 3 by adding a `"cost"` key holding that JSON object (`by_role` + `totals` + `run_wall_ms`). If the script printed `stats: SKIPPED (...)` instead, add `"cost":{"skipped":"<reason>"}` and continue. Echo the script's summary to the user so they see the per-role breakdown.
+
 **If `docs/metrics/skill-runs.jsonl` does not exist**: create it first with `touch docs/metrics/skill-runs.jsonl`.
 **If batch tracker is missing or unreadable**: log "Metrics Log: SKIPPED (tracker not found)" and proceed without blocking.
-**This phase is NON-BLOCKING** — if it fails for any reason, do not abort the run.
+**This phase is NON-BLOCKING** — if it fails for any reason, do not abort the run. The `-stats` step in particular is best-effort: the script is fail-safe (always exits 0), so never let it block the commit.

package/framework/.claude/skills/prd/SKILL.md

@@ -199,6 +199,16 @@ message. You ask questions, wait for answers, and iterate.
     repository, or the consumer has explicitly disabled docs worktrees via
     overlay), STOP and report the error to the user. Do NOT silently fall back
     to writing on the main repo — that defeats the entire purpose of this rule.
+18. **Opt-in session telemetry (`-stats` / `--stats`).** Unlike `/new`, this skill
+    has no flag parser — it is conversational. So detect the opt-in ONCE at **Step 1
+    (Kickoff)**: inspect `$ARGUMENTS` for the token `-stats` or `--stats`. If present,
+    set `stats_enabled: true` in the state-file header (the field exists in
+    `assets/state-template.md`); otherwise `false`. Persisting it in the state file is
+    what makes it survive context compression and Step 0 resume. The Metrics Log step
+    (inside Step 7) reads this field and, when `true`, post-processes the session
+    transcripts for REAL per-role token + wall-clock cost. The token itself is NOT part
+    of the feature description — strip it before recording the user's verbatim feature
+    text in `## Feature Description`.
 
 ---
 
@@ -372,6 +382,15 @@ exactly the correct semantics). No special handling needed.
    {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_db_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
    ```
 
-3. Add the file to the explicit stage list in validation-phase.md Step 7 point 6 (the stage list is at point 6; point 5 is the invocation of this very Metrics Log step).
+3. **Session token telemetry (ONLY when `stats_enabled: true` in the state file)** — measure REAL per-role token + wall-clock cost by post-processing the session transcripts (zero model-token cost — runs in Bash). Invoke:
 
-**This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar. The PRD merge proceeds regardless.
+   ```bash
+   node .framework/framework/scripts/analyze-session-tokens.js \
+     --skill prd --run-id "prd-<slug>" --out-dir "$WORKTREE_PATH/docs/metrics"
+   ```
+
+   The script reads `$CLAUDE_CODE_SESSION_ID` and derives the transcript paths itself (do NOT pass `--session` / `--project-dir` — test-only overrides). It writes `$WORKTREE_PATH/docs/metrics/sessions/prd-<slug>.md` and prints a summary plus a final `TELEMETRY_JSON=<json>` line. Parse that line and add its object under a `"cost"` key on the same JSONL row from step 2; on `stats: SKIPPED (...)` add `"cost":{"skipped":"<reason>"}`. Echo the summary to the user. Add the new `sessions/prd-<slug>.md` file to the explicit stage list too (point 4 below).
+
+4. Add the file(s) to the explicit stage list in validation-phase.md Step 7 point 6 (the stage list is at point 6; point 5 is the invocation of this very Metrics Log step).
+
+**This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar. The PRD merge proceeds regardless. The `-stats` script is itself fail-safe (always exits 0).

package/framework/.claude/skills/prd/assets/state-template.md

@@ -1,6 +1,7 @@
 # PRD Session: {{slug}}
 Created: {{YYYY-MM-DD HH:MM}}
 Status: discovery
+stats_enabled: {{true if invoked with -stats/--stats, else false}}
 
 ## Worktree
 - path: {{absolute worktree path returned by worktree-manager nw-docs}}

package/framework/scripts/analyze-session-tokens.js

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+// Post-hoc session telemetry for /new and /prd (opt-in via `-stats`).
+//
+// Reads the live Claude Code transcripts — the orchestrator's main transcript
+// plus every subagent transcript — and aggregates REAL token usage and wall-clock
+// time by AGENT ROLE (coder, code-reviewer, qa-sentinel, doc-reviewer, …). The
+// data already exists in the transcripts (`message.usage` + `timestamp`), so this
+// costs ZERO model tokens: it runs in Node, after the run, outside the model.
+//
+// Transcript layout (verified):
+//   ~/.claude/projects/<slug>/<session_id>.jsonl                  ← orchestrator (main)
+//   ~/.claude/projects/<slug>/<session_id>/subagents/agent-*.jsonl ← one file per subagent
+//   where slug = cwd with every "/" replaced by "-".
+//
+// Role mapping: each `Agent` tool_use in the main transcript carries
+// `input.subagent_type` (= role) and `input.prompt`. Every subagent file's first
+// user message IS that prompt, so we link file→role by prompt-prefix match
+// (verified 20/20 on a real /new run). Unlinkable files fall back to role
+// "unknown" with a slug-derived label — their token/time data stays accurate.
+//
+// Cache accounting: the four usage counters are kept SEPARATE on purpose.
+// `cache_read` is billed ~10% of fresh input; conflating them would overstate
+// cost and mislead "what consumed the most". A single headline `cost_units`
+// figure weights them: output + fresh_input + cache_creation×1.25 + cache_read×0.1.
+//
+// Usage:
+//   node analyze-session-tokens.js --skill new --run-id batch-FEAT-0001
+//   node analyze-session-tokens.js --skill prd --run-id prd-checkout --out-dir docs/metrics
+//   # test/override (bypass env + cwd derivation):
+//   node analyze-session-tokens.js --skill new --run-id X --session <id> --project-dir <path>
+//
+// Output:
+//   - <out-dir>/sessions/<run_id>.md  — human-readable per-role breakdown + totals
+//   - stdout: same summary, PLUS a final line `TELEMETRY_JSON=<json>` carrying the
+//     totals object for the skill to embed in docs/metrics/skill-runs.jsonl.
+//
+// Fail-safe: ANY error prints `stats: SKIPPED (<reason>)` and exits 0. This script
+// must NEVER abort a /new or /prd run.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// ---- arg parsing -----------------------------------------------------------
+
+function getArg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+// Bail out softly — telemetry is never allowed to break a run.
+function skip(reason) {
+  console.log(`stats: SKIPPED (${reason})`);
+  process.exit(0);
+}
+
+const skill = getArg('skill', 'new');
+const runId = getArg('run-id', null);
+const outDir = getArg('out-dir', path.join('docs', 'metrics'));
+const sessionId = getArg('session', process.env.CLAUDE_CODE_SESSION_ID || null);
+const projectDir = getArg('project-dir', null);
+
+if (!runId) skip('no --run-id provided');
+if (!sessionId) skip('no session id ($CLAUDE_CODE_SESSION_ID unset, no --session)');
+
+// ---- locate transcripts ----------------------------------------------------
+
+function projectSlug(cwd) {
+  // Claude Code stores transcripts under a slug = cwd with "/" → "-".
+  return cwd.replace(/\//g, '-');
+}
+
+let baseDir;
+if (projectDir) {
+  baseDir = projectDir;
+} else {
+  baseDir = path.join(os.homedir(), '.claude', 'projects', projectSlug(process.cwd()));
+}
+
+const mainTranscript = path.join(baseDir, `${sessionId}.jsonl`);
+const subDir = path.join(baseDir, sessionId, 'subagents');
+
+if (!fs.existsSync(mainTranscript)) skip(`main transcript not found: ${mainTranscript}`);
+
+// ---- jsonl helpers ---------------------------------------------------------
+
+function* readLines(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    return;
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch (err) {
+      continue; // tolerate partial / malformed lines
+    }
+    yield obj;
+  }
+}
+
+function contentBlocks(rec) {
+  const c = rec && rec.message && rec.message.content;
+  if (Array.isArray(c)) return c;
+  if (typeof c === 'string') return [{ type: 'text', text: c }];
+  return [];
+}
+
+function blocksText(blocks) {
+  return blocks
+    .map((b) => (typeof b === 'string' ? b : b && typeof b.text === 'string' ? b.text : ''))
+    .join('')
+    .trim();
+}
+
+// Aggregate the four usage counters + wall-clock span of one transcript file.
+function aggregateFile(file) {
+  const acc = {
+    fresh_input: 0,
+    cache_read: 0,
+    cache_creation: 0,
+    output: 0,
+    turns: 0,
+    firstTs: null,
+    lastTs: null,
+  };
+  for (const rec of readLines(file)) {
+    const ts = rec.timestamp ? Date.parse(rec.timestamp) : NaN;
+    if (!Number.isNaN(ts)) {
+      if (acc.firstTs === null || ts < acc.firstTs) acc.firstTs = ts;
+      if (acc.lastTs === null || ts > acc.lastTs) acc.lastTs = ts;
+    }
+    if (rec.type !== 'assistant') continue;
+    const u = (rec.message && rec.message.usage) || null;
+    if (!u) continue;
+    acc.fresh_input += u.input_tokens || 0;
+    acc.cache_read += u.cache_read_input_tokens || 0;
+    acc.cache_creation += u.cache_creation_input_tokens || 0;
+    acc.output += u.output_tokens || 0;
+    acc.turns += 1;
+  }
+  return acc;
+}
+
+function costUnits(a) {
+  return Math.round(a.output + a.fresh_input + a.cache_creation * 1.25 + a.cache_read * 0.1);
+}
+
+function wallMs(a) {
+  return a.firstTs !== null && a.lastTs !== null ? a.lastTs - a.firstTs : 0;
+}
+
+// ---- role map from main transcript -----------------------------------------
+
+// Collect every Agent spawn: { role, promptPrefix } in spawn order.
+const agentSpawns = [];
+for (const rec of readLines(mainTranscript)) {
+  for (const blk of contentBlocks(rec)) {
+    if (blk && blk.type === 'tool_use' && blk.name === 'Agent' && blk.input) {
+      const role = blk.input.subagent_type || 'unknown';
+      const prompt = (blk.input.prompt || '').trim();
+      agentSpawns.push({ role, prompt });
+    }
+  }
+}
+
+function matchRole(firstPrompt) {
+  if (!firstPrompt) return null;
+  for (const s of agentSpawns) {
+    if (!s.prompt) continue;
+    // bidirectional prefix match tolerates truncation on either side
+    if (firstPrompt.startsWith(s.prompt.slice(0, 50)) || s.prompt.startsWith(firstPrompt.slice(0, 50))) {
+      return s.role;
+    }
+  }
+  return null;
+}
+
+// ---- aggregate subagents + main --------------------------------------------
+
+const byRole = new Map(); // role → { agg, agents }
+function addToRole(role, agg) {
+  if (!byRole.has(role)) {
+    byRole.set(role, {
+      fresh_input: 0,
+      cache_read: 0,
+      cache_creation: 0,
+      output: 0,
+      turns: 0,
+      agents: 0,
+      wallSumMs: 0,
+    });
+  }
+  const r = byRole.get(role);
+  r.fresh_input += agg.fresh_input;
+  r.cache_read += agg.cache_read;
+  r.cache_creation += agg.cache_creation;
+  r.output += agg.output;
+  r.turns += agg.turns;
+  r.agents += 1;
+  r.wallSumMs += wallMs(agg);
+}
+
+let subFiles = [];
+if (fs.existsSync(subDir)) {
+  try {
+    subFiles = fs
+      .readdirSync(subDir)
+      .filter((f) => f.endsWith('.jsonl'))
+      .map((f) => path.join(subDir, f));
+  } catch (err) {
+    subFiles = [];
+  }
+}
+
+let unmatchedFiles = 0;
+for (const f of subFiles) {
+  const agg = aggregateFile(f);
+  if (agg.turns === 0 && wallMs(agg) === 0) continue; // empty/aborted subagent
+  // role: first user prompt of the subagent file
+  let firstPrompt = '';
+  for (const rec of readLines(f)) {
+    if (rec.type === 'user') {
+      firstPrompt = blocksText(contentBlocks(rec));
+      break;
+    }
+  }
+  const role = matchRole(firstPrompt);
+  if (!role) unmatchedFiles += 1;
+  addToRole(role || 'unknown', agg);
+}
+
+// orchestrator (main transcript) as its own row
+const mainAgg = aggregateFile(mainTranscript);
+addToRole('orchestrator', mainAgg);
+
+// team-mode nesting caveat: Agent calls in main with no local subagent file
+// (background / nested orchestrators write to a different session dir).
+const localSubCount = subFiles.length;
+const spawnedCount = agentSpawns.length;
+const missingNested = Math.max(0, spawnedCount - localSubCount);
+
+// ---- totals ----------------------------------------------------------------
+
+const totals = {
+  fresh_input: 0,
+  cache_read: 0,
+  cache_creation: 0,
+  output: 0,
+  turns: 0,
+  agents: 0,
+};
+for (const r of byRole.values()) {
+  totals.fresh_input += r.fresh_input;
+  totals.cache_read += r.cache_read;
+  totals.cache_creation += r.cache_creation;
+  totals.output += r.output;
+  totals.turns += r.turns;
+  totals.agents += r.agents;
+}
+totals.cost_units = costUnits(totals);
+
+// run wall-clock = span of the main transcript (first→last timestamp)
+const runWallMs = wallMs(mainAgg);
+
+// ---- formatting helpers -----------------------------------------------------
+
+function fmtTokens(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}k`;
+  return String(n);
+}
+function fmtDuration(ms) {
+  if (!ms || ms < 0) return '-';
+  const s = Math.round(ms / 1000);
+  const m = Math.floor(s / 60);
+  const rs = s % 60;
+  return m > 0 ? `${m}m${rs.toString().padStart(2, '0')}s` : `${rs}s`;
+}
+function pad(s, w) {
+  s = String(s);
+  return s.length >= w ? s : s + ' '.repeat(w - s.length);
+}
+function padL(s, w) {
+  s = String(s);
+  return s.length >= w ? s : ' '.repeat(w - s.length) + s;
+}
+
+// rows sorted by cost_units desc
+const roleRows = [...byRole.entries()]
+  .map(([role, r]) => ({ role, ...r, cost_units: costUnits(r) }))
+  .sort((a, b) => b.cost_units - a.cost_units);
+
+// ---- write per-run markdown summary ----------------------------------------
+
+const lines = [];
+lines.push(`# Session telemetry — ${runId}`);
+lines.push('');
+lines.push(`- **skill**: ${skill}`);
+lines.push(`- **session**: ${sessionId}`);
+lines.push(`- **run wall-clock** (orchestrator span, includes idle): ${fmtDuration(runWallMs)}`);
+lines.push(`- **agents**: ${totals.agents - 1} subagent(s) + 1 orchestrator`);
+lines.push(`- **total cost units**: ${fmtTokens(totals.cost_units)}  _(output + fresh_in + cache_creation×1.25 + cache_read×0.1)_`);
+lines.push('');
+lines.push('## By role');
+lines.push('');
+const H = ['role', 'agents', 'wall(sum)', 'output', 'fresh_in', 'cache_cr', 'cache_rd', 'cost_units', '% cost'];
+const W = [20, 7, 10, 9, 9, 9, 9, 11, 7];
+lines.push(H.map((h, i) => pad(h, W[i])).join(' | '));
+lines.push(W.map((w) => '-'.repeat(w)).join('-|-'));
+for (const r of roleRows) {
+  const pct = totals.cost_units ? `${((r.cost_units / totals.cost_units) * 100).toFixed(0)}%` : '-';
+  lines.push(
+    [
+      pad(r.role, W[0]),
+      padL(r.agents, W[1]),
+      padL(fmtDuration(r.wallSumMs), W[2]),
+      padL(fmtTokens(r.output), W[3]),
+      padL(fmtTokens(r.fresh_input), W[4]),
+      padL(fmtTokens(r.cache_creation), W[5]),
+      padL(fmtTokens(r.cache_read), W[6]),
+      padL(fmtTokens(r.cost_units), W[7]),
+      padL(pct, W[8]),
+    ].join(' | ')
+  );
+}
+lines.push(W.map((w) => '-'.repeat(w)).join('-|-'));
+lines.push(
+  [
+    pad('TOTAL', W[0]),
+    padL(totals.agents, W[1]),
+    padL(fmtDuration(runWallMs), W[2]),
+    padL(fmtTokens(totals.output), W[3]),
+    padL(fmtTokens(totals.fresh_input), W[4]),
+    padL(fmtTokens(totals.cache_creation), W[5]),
+    padL(fmtTokens(totals.cache_read), W[6]),
+    padL(fmtTokens(totals.cost_units), W[7]),
+    padL('100%', W[8]),
+  ].join(' | ')
+);
+lines.push('');
+lines.push('> wall(sum) is the sum of per-agent spans and reflects ACTIVE compute time; the');
+lines.push('> run wall-clock is the orchestrator first→last span and INCLUDES human idle gaps.');
+lines.push('> Subagents may run in parallel, so wall(sum) can exceed the run wall-clock.');
+lines.push('> cache_read tokens are ~10% the cost of fresh input — kept separate on purpose.');
+if (unmatchedFiles > 0) {
+  lines.push('>');
+  lines.push(`> ⚠ ${unmatchedFiles} subagent file(s) could not be mapped to a role (bucketed as "unknown").`);
+}
+if (missingNested > 0) {
+  lines.push('>');
+  lines.push(
+    `> ⚠ team-mode caveat: ${missingNested} Agent spawn(s) in the main transcript have no local`
+  );
+  lines.push(
+    `> subagent file (likely background / nested orchestrators in separate sessions) — their`
+  );
+  lines.push(`> tokens are NOT included in these totals. Sequential-mode runs are fully accurate.`);
+}
+lines.push('');
+
+// ---- emit ------------------------------------------------------------------
+
+const sessionsDir = path.join(outDir, 'sessions');
+try {
+  fs.mkdirSync(sessionsDir, { recursive: true });
+  fs.writeFileSync(path.join(sessionsDir, `${runId}.md`), lines.join('\n'));
+} catch (err) {
+  skip(`could not write summary: ${err.message}`);
+}
+
+// human summary to stdout
+console.log(lines.join('\n'));
+
+// machine-readable totals for the skill to embed in skill-runs.jsonl
+const jsonOut = {
+  run_wall_ms: runWallMs,
+  by_role: Object.fromEntries(
+    roleRows.map((r) => [
+      r.role,
+      {
+        agents: r.agents,
+        output: r.output,
+        fresh_input: r.fresh_input,
+        cache_creation: r.cache_creation,
+        cache_read: r.cache_read,
+        cost_units: r.cost_units,
+        wall_sum_ms: r.wallSumMs,
+      },
+    ])
+  ),
+  totals: {
+    agents: totals.agents,
+    output: totals.output,
+    fresh_input: totals.fresh_input,
+    cache_creation: totals.cache_creation,
+    cache_read: totals.cache_read,
+    cost_units: totals.cost_units,
+    turns: totals.turns,
+  },
+  unmatched_subagents: unmatchedFiles,
+  nested_agents_excluded: missingNested,
+};
+console.log(`TELEMETRY_JSON=${JSON.stringify(jsonOut)}`);
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.35.2",
+  "version": "3.36.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"