baldart 3.35.1 → 3.36.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.
+
+> **Forward-looking by nature.** This cannot retroactively fix CLIs *already* installed at a pre-3.35.2 version — their commander still throws before any code we control runs. The fix rescues flags introduced *after* this release for anyone on 3.35.2+. For older installs the only path remains `npm i -g baldart@latest` (now surfaced by the helpful error + the update notifier).
+
+### Fixed — self-upgrade survives flags newer than the installed CLI
+
+- **[bin/baldart.js](bin/baldart.js)**: the `update` command gains `.allowUnknownOption()` + `.allowExcessArguments()` (scoped to `update` only — every other command keeps strict validation). Unknown tokens now land in `command.args` instead of throwing `commander.unknownOption` during parse; they are forwarded to `update(options, command.args)`.
+- **[src/commands/update.js](src/commands/update.js)** (`update`): an early unknown-flag block runs **before** any work. When unknown tokens are present it relaunches under `npx baldart@latest`, forwarding `process.argv.slice(3)` (raw flags, with the leading `update` subcommand token stripped so the child isn't spawned as `update update …`). The unrecognized flag never enters `options`, so raw-argv forwarding is the only faithful path.
+- **[src/commands/update.js](src/commands/update.js)** (`maybeRelaunchUnderLatest`): accepts `extra.rawArgs` (forward verbatim instead of reconstructing from parsed `options`) and `extra.unknown` (skip the interactive "proceed with current CLI" prompt — pointless when the CLI literally can't parse the flag; relaunch whenever a newer version exists). The normal stale-CLI relaunch path is unchanged (still reconstructs known flags, still forwards `--on-divergence` / `--json`).
+- **[src/commands/update.js](src/commands/update.js)** (`failOnUnknownArgs`): new helpful terminal error replacing commander's cryptic message — hedges between "recently-added flag → `npm i -g baldart@latest`" and "typo", and **suppresses the upgrade suggestion** when `BALDART_RELAUNCHED=1` (we are already the `@latest` child, so a typo is the only explanation). `--json`-aware: emits a `usage-error` JSON object on stdout.
+- **[src/commands/update.js](src/commands/update.js)**: `--json` mode is now **armed before** the unknown-flag block so the relaunch notice / helpful error route to STDERR — preserving the single-object STDOUT contract for `update --json --yes --<new-flag>` (the agent/CI scenario this machinery exists for).
+
 ## [3.35.1] - 2026-05-30
 
 Fixes a **HIGH-severity** bug where `baldart update --reset` could leave a consumer **committed-without-`.framework/`** (broken install, manual recovery only). The reset path wiped `.framework/`, committed the deletion, then handed off to `add()` **programmatically with no repository** — the bin-layer default (`antbald/BALDART`) only applies on the CLI path, so `repo` arrived `undefined`, crashing at `repo.startsWith(...)` ("Cannot read properties of undefined") *after* the wipe was already committed. Three layers now make this unreachable: (1) repo resolved **before** any destructive step, (2) reinstall failures roll back to the pre-reset backup tag, (3) defensive guards + legible errors. **No new `baldart.config.yml` keys** — the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.35.1
+3.36.0

package/bin/baldart.js

@@ -81,9 +81,24 @@ program
   .option('--i-know', 'Acknowledges --reset will wipe untracked/ignored files inside .framework/ (required to use --reset --yes).')
   .option('--on-divergence <strategy>', 'Non-interactive resolution when the consumer has local commits on .framework/ (for agents / CI): "scaffold-overlays" (auto-create overlay skeletons, then stop), "pull" (keep commits + merge — non-destructive), or "abort".')
   .option('--json', 'Machine-readable output (agents / CI): emit a single JSON result object on stdout, route all human output to stderr. Requires --yes (non-interactive); rejects --reset.')
-  .action(async (options) => {
+  // Parse permissively so an UNKNOWN flag does not crash commander before the
+  // CLI self-upgrade can kick in (v3.35.2+). The whole point of `update` is to
+  // be the self-healing entrypoint: when a flag introduced in a newer release
+  // reaches an older-but-still-this-or-later CLI, commander used to throw
+  // `error: unknown option` during parse — i.e. BEFORE the action handler runs,
+  // so the auto-relaunch under `npx baldart@latest` (which lives in the action)
+  // never got a chance. With both guards set, unknown tokens land in
+  // `command.args` instead of throwing; the action forwards them to a newer CLI
+  // (or emits a helpful error). Scoped to `update` only — every other command
+  // keeps strict validation.
+  .allowUnknownOption()
+  .allowExcessArguments()
+  .action(async (options, command) => {
     const updateCommand = require('../src/commands/update');
-    await updateCommand(options);
+    // command.args holds any tokens commander could not match to a known
+    // option/positional — for `update` (no positionals) that means unknown
+    // flags + their values. Forward them so update() can self-upgrade.
+    await updateCommand(options, command.args || []);
   });
 
 program

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.1",
+  "version": "3.36.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/update.js

@@ -406,7 +406,16 @@ function snapshotCustomEntries(dir) {
 // child inherits stdio (preserves prompts), and BALDART_RELAUNCHED=1 in env
 // is a loop guard: if npm cache somehow serves an older version, the child
 // sees the flag and skips its own relaunch check.
-async function maybeRelaunchUnderLatest(options) {
+// `extra.rawArgs` — when set, forward these verbatim to the child instead of
+// reconstructing flags from the parsed `options`. Used by the unknown-flag path
+// (v3.35.2+): an option this CLI doesn't recognize never lands in `options`, so
+// reconstruction would silently drop it — only the raw argv carries it intact.
+// The caller MUST have already stripped the leading `update` subcommand token.
+// `extra.unknown` — true when triggered by an unknown flag rather than a plain
+// stale-CLI check. In that case the interactive "proceed with current CLI"
+// branch is pointless (the current CLI literally cannot honor the flag), so we
+// relaunch whenever a newer version exists and skip the prompt.
+async function maybeRelaunchUnderLatest(options, extra = {}) {
   if (process.env.BALDART_RELAUNCHED === '1') return false;
   if (process.env.BALDART_NO_RELAUNCH === '1') return false;
 
@@ -424,7 +433,13 @@ async function maybeRelaunchUnderLatest(options) {
 
   const autoYes = options.yes === true;
   let proceed = autoYes;
-  if (!autoYes) {
+  if (extra.unknown) {
+    // Unknown flag + a newer CLI exists: relaunch unconditionally. Asking
+    // "proceed with current CLI?" makes no sense — it can't parse the flag.
+    proceed = true;
+    UI.newline();
+    UI.warning(`Unknown option for the installed CLI (v${cliVersion}); a newer release (v${info.latest}) may support it.`);
+  } else if (!autoYes) {
     UI.newline();
     UI.warning(`The installed CLI is older than npm latest: v${cliVersion} → v${info.latest}.`);
     const choice = await UI.select('How would you like to proceed?', [
@@ -440,17 +455,24 @@ async function maybeRelaunchUnderLatest(options) {
   }
   if (!proceed) return false;
 
-  // Reconstruct the original argv flags for the child.
-  const flags = [];
-  if (options.yes === true) flags.push('--yes');
-  if (options.autoStash === true && options.yes !== true) flags.push('--auto-stash');
-  if (options.commit === false) flags.push('--no-commit');
-  if (options.reset === true) flags.push('--reset');
-  if (options.iKnow === true) flags.push('--i-know');
-  // Forward the non-interactive resolution + machine-readable flags too, else
-  // a stale-CLI self-relaunch would silently drop them (v3.32.0+).
-  if (options.onDivergence) flags.push('--on-divergence', options.onDivergence);
-  if (options.json === true) flags.push('--json');
+  // Build the child argv. The unknown-flag path forwards the raw argv (already
+  // stripped of the `update` token); the normal stale-CLI path reconstructs
+  // from parsed options.
+  let flags;
+  if (Array.isArray(extra.rawArgs)) {
+    flags = extra.rawArgs;
+  } else {
+    flags = [];
+    if (options.yes === true) flags.push('--yes');
+    if (options.autoStash === true && options.yes !== true) flags.push('--auto-stash');
+    if (options.commit === false) flags.push('--no-commit');
+    if (options.reset === true) flags.push('--reset');
+    if (options.iKnow === true) flags.push('--i-know');
+    // Forward the non-interactive resolution + machine-readable flags too, else
+    // a stale-CLI self-relaunch would silently drop them (v3.32.0+).
+    if (options.onDivergence) flags.push('--on-divergence', options.onDivergence);
+    if (options.json === true) flags.push('--json');
+  }
 
   const spawn = require('child_process').spawnSync;
   UI.info(`Auto-relaunching via npx baldart@${info.latest}…`);
@@ -466,7 +488,30 @@ async function maybeRelaunchUnderLatest(options) {
   process.exit(res.status || 0);
 }
 
-async function update(options = {}) {
+// Helpful terminal error when an unknown flag reached this CLI and a relaunch
+// under a newer version was not possible (already on latest / offline / opted
+// out, or we ARE the relaunched child). Replaces commander's cryptic
+// `error: unknown option` with actionable guidance. (v3.35.2+)
+function failOnUnknownArgs(unknownArgs, options) {
+  const tokens = unknownArgs.filter((a) => typeof a === 'string');
+  const firstOpt = tokens.find((a) => a.startsWith('-')) || tokens[0] || '(unknown)';
+  // In the relaunched child we are already on @latest, so "upgrade" is wrong —
+  // an unknown flag here means a genuine typo.
+  const alreadyLatest = process.env.BALDART_RELAUNCHED === '1';
+  const reason = alreadyLatest
+    ? `Unknown option ${firstOpt}. Even the latest CLI does not recognize it — check for a typo.`
+    : `Unknown option ${firstOpt}. If it is a recently-added flag, upgrade with \`npm i -g baldart@latest\`; otherwise check for a typo.`;
+  if (options.json === true) {
+    emitUpdateJson({ ok: false, action: 'usage-error', reason }, 2);
+  }
+  UI.error(reason);
+  if (!alreadyLatest) {
+    UI.info(`Then retry: npx baldart update ${tokens.join(' ')}`.trim());
+  }
+  process.exit(2);
+}
+
+async function update(options = {}, unknownArgs = []) {
   const git = new GitUtils();
   const symlinks = new SymlinkUtils();
   const repo = 'antbald/BALDART'; // Default repo
@@ -478,13 +523,35 @@ async function update(options = {}) {
   const autoStash = autoYes || options.autoStash === true;
   const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
 
+  // Arm machine-readable mode FIRST (v3.35.2+). The unknown-flag handling below
+  // can emit human lines (relaunch notice / helpful error); they must route to
+  // STDERR before anything reaches STDOUT, or a `--json --yes --new-flag` run
+  // would pollute the single-object stdout contract.
+  JSON_MODE = options.json === true;
+  if (JSON_MODE) UI.setJsonMode(true);
+
+  // Unknown-flag self-upgrade (v3.35.2+). Commander now parses `update`
+  // permissively (see bin/baldart.js), so a flag this CLI doesn't know lands
+  // in `unknownArgs` instead of crashing the parser. That flag was almost
+  // certainly introduced in a newer release — transparently relaunch under
+  // `npx baldart@latest`, forwarding the RAW argv (the unknown token never made
+  // it into `options`, so only raw argv carries it). If we can't relaunch
+  // (already latest / offline / opted out / we ARE the child), fail with an
+  // actionable message instead of a cryptic crash.
+  if (Array.isArray(unknownArgs) && unknownArgs.length > 0) {
+    // process.argv = [node, baldart, 'update', ...flags] — drop the first 3 so
+    // the child isn't spawned as `update update …` (it already gets 'update').
+    const rawArgs = process.argv.slice(3);
+    await maybeRelaunchUnderLatest(options, { rawArgs, unknown: true });
+    // Relaunch did not happen → this (latest-or-offline) CLI can't honor it.
+    failOnUnknownArgs(unknownArgs, options);
+  }
+
   // Machine-readable mode (v3.32.0+). Must be fully non-interactive: --json
   // requires --yes (so no UI.select/confirm can block) and rejects --reset
   // (the nuclear path is a deliberate destructive human escape hatch, not an
   // agent flow — see the autonomous /baldart-update skill, which never resets).
-  JSON_MODE = options.json === true;
   if (JSON_MODE) {
-    UI.setJsonMode(true);
     if (options.reset === true) {
       emitUpdateJson({ ok: false, action: 'usage-error',
         reason: '--json does not support --reset. Reset is an interactive destructive escape hatch; run it manually.' }, 2);