@attalabs/vinaya 0.22.0 → 0.23.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/registry-parse.ts

@@ -0,0 +1,164 @@
+/**
+ * registry-parse.ts — pure, no-I/O parser for `aeg-root/enforcement.md`'s
+ * three ring markdown tables (Ring 0/1/2). enforcement.md's tables ARE the
+ * gate registry (no live file duplicates forge state); this
+ * parses them rather than maintaining a second copy.
+ *
+ * The generic markdown-table extraction lives in `./markdown-table` — the one
+ * aeg-core-owned parser every doctrine consumer shares. This module
+ * imports `findTable`/`findHeadingLine` from there rather than re-deriving
+ * them; it adds only the enforcement-specific normalization on top (the
+ * ring-heading list, `stripBackticks`, and the last-two-columns rule).
+ *
+ * Each ring's table has a different header wording (Ring 0: Action/Gate/...;
+ * Ring 1: CI check/Re-verifies; Ring 2: Mechanism/Runs/Catches). The FIRST
+ * column is always the row's identifying label; `implementation` and
+ * `description` are resolved BY HEADER NAME, since those two are spelled
+ * identically in all three tables. Positional reads are used only where no
+ * shared header name exists.
+ *
+ * The one exception is `Description`, which IS looked up by header name: it is
+ * the only column spelled identically in all three tables, and the only one a
+ * table can legitimately lack. Position cannot express that difference (a
+ * 7-column table means two different shapes depending on the ring), so the
+ * name is the only honest key. See the lookup in `parseEnforcementRegistry`.
+ */
+
+import { findHeadingLine, findTable } from './markdown-table'
+
+export type GateRing = 'ring0' | 'ring1' | 'ring2'
+
+export type GateRow = {
+  ring: GateRing
+  action: string
+  summary: string
+  category: 'ci' | 'hook' | 'event'
+  /** One plain sentence: what this gate does, for a reader. Present in all
+   * three ring tables and resolved by header name (see the lookup below).
+   *
+   * The counterpart to `spec`, and not interchangeable with it — `spec` is
+   * written to ENFORCE: 17 of the 31 real rows cite an Issue number, a
+   * task number or a file path, and the longest runs 2708 chars. That is
+   * correct for a gate and unreadable on a page. This column is the same fact
+   * addressed to a person, and is what a row's `summary` question gets
+   * answered by. The same bar `roles/*.md`/`contracts/*.md` hold via
+   * `description:` frontmatter and `ACTIONS` holds via its `description`
+   * field, so a reader gets one register whatever they click.
+   *
+   * Optional on the type only so a malformed table degrades instead of
+   * throwing — every real row carries one, asserted against the live file. */
+  description?: string
+  /** The substantive middle column — "What must be true..." (ring0),
+   * "Re-verifies" (ring1), "Catches" (ring2) — always the column
+   * immediately before `implementation`. Each ring names it differently,
+   * but structurally it's always the same slot: the normative spec, written
+   * for enforcement. Distinct from `summary`'s rhetorical question and from
+   * `description`'s plain-language answer to it. Undefined when a table has
+   * no such column. */
+  spec?: string
+  implementation: string
+  /**
+   * `product` — this row's implementation is a check registered in
+   * `coreCheckRegistry()` (`apps/cli/src/checks/registry.ts`), so it ships to
+   * every adopter through `vinaya check`. `repo-own` — everything else: a
+   * mechanism specific to how this repository enforces itself on top of the
+   * product (a hand-written CI job, the check runner/resolver, a forge-write
+   * command, or a check this repo runs on its own doctrine but has not
+   * registered). Read from an `Audience` column, by header name like
+   * `description`. A table carrying no such column, or a cell holding
+   * anything other than the literal `product`, resolves to `repo-own` — the
+   * safe default, since it makes no shipped claim for G6 to verify.
+   */
+  audience: 'product' | 'repo-own'
+  line: number
+}
+
+const RING_HEADINGS: Array<{ ring: GateRing; pattern: RegExp }> = [
+  { ring: 'ring0', pattern: /^##\s+Ring 0\b/ },
+  { ring: 'ring1', pattern: /^##\s+Ring 1\b/ },
+  { ring: 'ring2', pattern: /^##\s+Ring 2\b/ }
+]
+
+function stripBackticks(cell: string): string {
+  const trimmed = cell.trim()
+  if (trimmed.length >= 2 && trimmed.startsWith('`') && trimmed.endsWith('`')) {
+    return trimmed.slice(1, -1)
+  }
+  return trimmed
+}
+
+/** Strips markdown `**bold**` markers from a gate/check row's own name.
+ * `action` is the one cell this parser has never sanitized — most rows are
+ * plain text, but a real row can legitimately bold its name for doctrine-
+ * prose emphasis, and that literal `**...**` was leaking straight through
+ * to `DiagramNode.label` (visible asterisks in the how-it-works UI; every
+ * label already renders bold via CSS where it matters, so the markdown
+ * marker carries zero information downstream). Root-cause fix, not a
+ * per-row doctrine patch — the next accidentally-bolded name is covered
+ * too, not just the ones caught so far. */
+function stripBold(cell: string): string {
+  return cell.trim().replace(/\*\*/g, '')
+}
+
+/**
+ * Parses the three ring tables out of `enforcement.md`'s raw content into a
+ * flat, normalized `GateRow[]`. Each row's `action` is its table's first
+ * column; `implementation` is resolved by header name, falling back to the
+ * last column.
+ */
+export function parseEnforcementRegistry(content: string): GateRow[] {
+  const lines = content.split('\n')
+  const result: GateRow[] = []
+
+  for (const { ring, pattern } of RING_HEADINGS) {
+    const headingLine = findHeadingLine(lines, pattern)
+    if (headingLine === null) continue
+    const table = findTable(lines, headingLine + 1)
+    if (!table) continue
+    // `description`/`Audience` are found BY HEADER NAME, never by position —
+    // the two columns here that can be. Every other column is positional out
+    // of necessity: the three ring tables name their first column
+    // differently ("Action"/"CI check"/"Mechanism") and their middle columns
+    // differently again ("Gate" + "What must be true" / "Re-verifies" /
+    // "Runs" + "Catches"), so only the ends are reliable. "Description" and
+    // "Audience" are spelled the same in all three, which makes a name
+    // lookup possible — and a name lookup is what keeps a table WITHOUT the
+    // column from having some other column silently read as its value. By
+    // index that is undetectable: a 7-column table means "has Description"
+    // in one ring and "has Gate" in another, and the parser cannot tell
+    // which. -1 here simply means the table doesn't have that column.
+    const descriptionIndex = table.headers.findIndex((h) => h.trim().toLowerCase() === 'description')
+    const implementationIndex = table.headers.findIndex((h) => h.trim().toLowerCase() === 'implementation')
+    const audienceIndex = table.headers.findIndex((h) => h.trim().toLowerCase() === 'audience')
+    for (const row of table.rows) {
+      const cells = row.cells
+      if (cells.length < 3) continue
+      const action = stripBold(cells[0] ?? '')
+      const summary = stripBackticks(cells[1] ?? '')
+      const category = stripBackticks(cells[2] ?? '') as GateRow['category']
+      const implementation = stripBackticks(
+        (implementationIndex === -1 ? cells[cells.length - 1] : cells[implementationIndex]) ?? ''
+      )
+      const description =
+        descriptionIndex === -1 ? undefined : stripBackticks(cells[descriptionIndex] ?? '') || undefined
+      // `spec` is the ring-specific column immediately before `implementation`
+      // — normally the last cell, but `Audience`, when present, now sits
+      // between them. `specIndex` follows whichever of the two comes first:
+      // one before `Audience` if the table carries one, one before the last
+      // cell (`implementation`'s positional fallback) if it doesn't — so a
+      // table predating this column (a fixture, an un-upgraded adopter copy)
+      // still resolves `spec` exactly as it did before `Audience` existed.
+      const specIndex = (audienceIndex === -1 ? cells.length - 1 : audienceIndex) - 1
+      const spec = specIndex >= 3 ? stripBackticks(cells[specIndex] ?? '') || undefined : undefined
+      const audience: GateRow['audience'] =
+        audienceIndex === -1
+          ? 'repo-own'
+          : stripBackticks(cells[audienceIndex] ?? '') === 'product'
+            ? 'product'
+            : 'repo-own'
+      result.push({ ring, action, summary, category, description, spec, implementation, audience, line: row.line })
+    }
+  }
+
+  return result
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/registry-scaffold.ts

@@ -0,0 +1,216 @@
+/**
+ * registry-scaffold.ts — pure insertion logic that turns a G2 "orphan
+ * hook/CLI" finding into a stub row, instead of leaving it a drift warning a
+ * human has to notice and fix by hand.
+ *
+ * Purity contract identical to `registry-checks.ts`'s: no fs/git/gh here.
+ * The caller (`bin/verify-registry.ts`) supplies the parsed rows, the
+ * already-globbed candidate files, and the raw `enforcement.md` content to
+ * rewrite; this module only ever reads `GATE_AUDIENCE` (a same-package,
+ * aeg-core-local data table — see its own doc comment for why aeg-core
+ * cannot instead import `apps/cli`'s `CORE_CHECK_RING` directly).
+ *
+ * Three derivation classes, per Issue #104's Principal decision (extended
+ * by Issue #307 for the second registry-backed location):
+ *   - a `packages/aeg-core/bin/*.ts` candidate that IS a registered check
+ *     (its basename resolves in `GATE_AUDIENCE` to a `ShippedGate`) gets a
+ *     stub in the ring `GATE_AUDIENCE` names for it;
+ *   - an `apps/cli/src/checks/bin/*.ts` candidate that IS a registered check
+ *     (its `check-`-stripped basename resolves in `CLI_CHECK_RING`) gets a
+ *     stub in the ring `CLI_CHECK_RING` names for it — most core check bins
+ *     live here, not under `packages/aeg-core/bin/` (Issue #307: 22 of 27 at
+ *     the time it was filed);
+ *   - a `.husky/*` or `.claude/hooks/*.sh` candidate is a managed hook by
+ *     construction — ring 0, no registry lookup needed.
+ * Anything else (a bin with no registry entry — `internal`, `NON_GATE_BINS`,
+ * or simply undeclared) gets NO stub: ring is genuinely underivable there,
+ * and guessing is exactly what this task's Stop-and-escalate condition
+ * forbids. It stays a plain G2 finding, same as today.
+ *
+ * Never touches an existing row: stubs are computed only for candidates
+ * whose path is absent from every parsed row's `implementation` — the
+ * identical predicate `checkG2` itself uses — so a candidate already
+ * documented (including every row `#67` wrote by hand) is left alone, and
+ * running the scaffold twice inserts nothing the second time (the first
+ * run's own stubs are now present, so the same predicate excludes them).
+ *
+ * Only mechanical facts are filled: the check name / candidate path
+ * (`Action`/`CI check`/`Mechanism`), `Category` (fixed per ring — matches
+ * every existing row: ring 0 is `hook`, ring 1 is `ci`, ring 2 is `event`),
+ * `Audience` (`product` for a registered check, `repo-own` for a bare hook
+ * script), and `implementation` (the path itself). A ring-0 stub also gets a
+ * mechanical `Gate` cell naming the check/its invocation — never the
+ * substantive "what must be true"/"re-verifies"/"catches" reasoning, which
+ * (along with `Summary`/`Description`) is the placeholder marker, verbatim,
+ * on every stub this module ever produces.
+ */
+
+import { CLI_CHECK_RING, GATE_AUDIENCE, isShipped } from './gate-audience'
+import { findHeadingLine, findTable } from './markdown-table'
+import type { GateRing, GateRow } from './registry-parse'
+
+/** The literal marker a stub's every non-mechanical cell carries. Never
+ * synthesized reasoning — `checkG2`'s placeholder scan (registry-checks.ts)
+ * looks for this exact string. */
+export const PLACEHOLDER = '[undocumented — fill in why]'
+
+const HUSKY_PREFIX = '.husky/'
+const CLAUDE_HOOKS_PREFIX = '.claude/hooks/'
+const AEG_CORE_BIN_PREFIX = 'packages/aeg-core/bin/'
+const CLI_BIN_PREFIX = 'apps/cli/src/checks/bin/'
+
+const RING_CATEGORY: Record<GateRing, string> = { ring0: 'hook', ring1: 'ci', ring2: 'event' }
+
+const RING_HEADING_PATTERN: Record<GateRing, RegExp> = {
+  ring0: /^##\s+Ring 0\b/,
+  ring1: /^##\s+Ring 1\b/,
+  ring2: /^##\s+Ring 2\b/
+}
+
+export type ScaffoldStub = {
+  ring: GateRing
+  path: string
+  checkName?: string
+  /** Ordered cell values, matching that ring table's own column count/order. */
+  cells: string[]
+}
+
+export type ScaffoldSkip = { path: string; reason: string }
+
+export type ScaffoldPlan = {
+  stubs: ScaffoldStub[]
+  skipped: ScaffoldSkip[]
+}
+
+function ringFromNumber(n: 0 | 1 | 2): GateRing {
+  if (n === 0) return 'ring0'
+  if (n === 1) return 'ring1'
+  return 'ring2'
+}
+
+/** Classifies one G2-orphan candidate path. Returns null when no ring is
+ * derivable — the candidate must remain a plain G2 finding, never guessed. */
+function classify(path: string): { ring: GateRing; checkName?: string } | null {
+  if (path.startsWith(HUSKY_PREFIX) || path.startsWith(CLAUDE_HOOKS_PREFIX)) {
+    return { ring: 'ring0' }
+  }
+  if (path.startsWith(AEG_CORE_BIN_PREFIX) && path.endsWith('.ts')) {
+    const base = path.slice(AEG_CORE_BIN_PREFIX.length, -'.ts'.length)
+    const audience = GATE_AUDIENCE[base]
+    if (audience && isShipped(audience)) {
+      const checkName = Array.isArray(audience.shippedAs) ? audience.shippedAs[0] : audience.shippedAs
+      return { ring: ringFromNumber(audience.ring), checkName }
+    }
+    return null
+  }
+  if (path.startsWith(CLI_BIN_PREFIX) && path.endsWith('.ts')) {
+    const base = path.slice(CLI_BIN_PREFIX.length, -'.ts'.length)
+    if (!base.startsWith('check-')) return null
+    const checkName = base.slice('check-'.length)
+    const ring = CLI_CHECK_RING[checkName]
+    if (ring === undefined) return null
+    return { ring: ringFromNumber(ring), checkName }
+  }
+  return null
+}
+
+function gateCell(path: string, checkName: string | undefined): string {
+  if (checkName) return `\`${checkName}\` check (\`vinaya check ${checkName}\`)`
+  return `managed hook script (\`${path}\`)`
+}
+
+function buildCells(ring: GateRing, path: string, checkName: string | undefined): string[] {
+  const action = checkName ?? path
+  const category = RING_CATEGORY[ring]
+  const audience = checkName ? 'product' : 'repo-own'
+  const implementation = `\`${path}\``
+  if (ring === 'ring0') {
+    return [
+      action,
+      PLACEHOLDER,
+      category,
+      PLACEHOLDER,
+      gateCell(path, checkName),
+      PLACEHOLDER,
+      audience,
+      implementation
+    ]
+  }
+  if (ring === 'ring1') {
+    return [action, PLACEHOLDER, category, PLACEHOLDER, PLACEHOLDER, audience, implementation]
+  }
+  return [action, PLACEHOLDER, category, PLACEHOLDER, PLACEHOLDER, PLACEHOLDER, audience, implementation]
+}
+
+/** Computes which G2-orphan candidates get a stub row, and where. Pure: no
+ * I/O, deterministic over its inputs. Idempotent by construction — a
+ * candidate already present in `rows` (including one from a prior scaffold
+ * run) is excluded before classification ever runs. */
+export function computeScaffoldPlan(rows: GateRow[], candidateFiles: string[]): ScaffoldPlan {
+  const implementations = new Set(rows.map((r) => r.implementation).filter((p) => p !== ''))
+  const stubs: ScaffoldStub[] = []
+  const skipped: ScaffoldSkip[] = []
+  for (const path of candidateFiles) {
+    if (implementations.has(path)) continue
+    const classified = classify(path)
+    if (!classified) {
+      skipped.push({ path, reason: 'no derivable ring — remains a plain G2 finding' })
+      continue
+    }
+    stubs.push({
+      ring: classified.ring,
+      path,
+      checkName: classified.checkName,
+      cells: buildCells(classified.ring, path, classified.checkName)
+    })
+  }
+  return { stubs, skipped }
+}
+
+function formatRow(cells: string[]): string {
+  return `| ${cells.join(' | ')} |`
+}
+
+/**
+ * Rewrites `content` to append the plan's stub rows to their ring tables.
+ * Only ever APPENDS new lines after a ring table's last existing row —
+ * never edits, reorders, or removes an existing line, so a hand-written row
+ * (including every row task `#67` wrote) is untouched byte-for-byte.
+ *
+ * Rings are processed from the bottom of the file upward (ring 2 first,
+ * then ring 1, then ring 0) so an earlier insertion's line numbers, computed
+ * once up front from the ORIGINAL `rows`, stay valid throughout — a later
+ * ring's insertion never shifts an earlier ring's already-resolved splice
+ * point.
+ *
+ * Throws if a ring with stubs to insert has no existing table/rows to
+ * anchor on — the caller (`bin/verify-registry.ts`) must not write anything
+ * to disk when this throws; computing this in memory before any write is
+ * what keeps the round-trip guard restore-free (nothing is ever written
+ * badly in the first place).
+ */
+export function applyScaffoldPlan(content: string, plan: ScaffoldPlan): string {
+  if (plan.stubs.length === 0) return content
+  const lines = content.split('\n')
+
+  const byRing: Record<GateRing, ScaffoldStub[]> = { ring0: [], ring1: [], ring2: [] }
+  for (const stub of plan.stubs) byRing[stub.ring].push(stub)
+
+  for (const ring of ['ring2', 'ring1', 'ring0'] as const) {
+    const stubs = byRing[ring]
+    if (stubs.length === 0) continue
+    const headingLine = findHeadingLine(lines, RING_HEADING_PATTERN[ring])
+    if (headingLine === null) {
+      throw new Error(`registry-scaffold: no "${ring}" heading found in enforcement.md`)
+    }
+    const table = findTable(lines, headingLine + 1)
+    if (!table || table.rows.length === 0) {
+      throw new Error(`registry-scaffold: ${ring} table has no existing rows to insert after`)
+    }
+    const lastRowLine = table.rows[table.rows.length - 1]?.line ?? headingLine
+    const newLines = stubs.map((s) => formatRow(s.cells))
+    lines.splice(lastRowLine, 0, ...newLines)
+  }
+
+  return lines.join('\n')
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/report-tokens.ts

@@ -0,0 +1,261 @@
+/**
+ * report-tokens — the **portable** half of the token-report contract
+ * (`aeg-root/tranche-model.md` §12, layers 1 and 3). No value this file reads,
+ * computes or emits is host-specific: it defines the summary shape every
+ * collection adapter must produce, and renders that shape into the frozen
+ * `Tokens: …` grammar `parse-token-report.ts` reads back. A host is named
+ * below only to point at the one shipped adapter and to record a retraction —
+ * never to branch on, and never in rendered output.
+ *
+ * `TranscriptSummary` **is the seam.** A host adapter's whole job is to
+ * produce one — from a session transcript, an API usage response, a meter the
+ * harness exposes, or figures an operator supplies by hand. AEG ships exactly
+ * one such adapter, for Claude Code, in `claude-code-transcript.ts`; a repo
+ * on another harness writes its own and reuses everything here unchanged.
+ * Adding host knowledge to this file would silently re-couple the portable
+ * layers to one vendor — that coupling is the defect the split exists to
+ * prevent, and this file is where it would reappear first.
+ *
+ * Historical note (misc-hardening-v1 task 1, #675): this module retracted
+ * §12's earlier claim that a role reports exact tokens "from `/cost`" — an
+ * operator-typed slash command no unattended agent session can invoke, in
+ * that host or any other. §12 records the retraction; the fix was to collect
+ * from a real per-turn source instead.
+ *
+ * Pure — no `fs`, no `process.env`. The CLI shim (`bin/report-tokens.ts`)
+ * does the I/O; these functions take values and produce the report.
+ */
+
+/**
+ * The four usage figures a role reports, in host-neutral terms. Every
+ * collection adapter maps its host's own field names onto these, so no field
+ * name from a host's own API or transcript format appears downstream of the
+ * adapter — including in this file.
+ */
+export type UsageComponents = {
+  inputTokens: number
+  outputTokens: number
+  cacheCreationInputTokens: number
+  cacheReadInputTokens: number
+}
+
+/**
+ * **The adapter seam.** What a host's collection step must produce for one
+ * role-turn, and the only thing the portable layers below consume. Named for
+ * the shipped adapter's source (a session transcript), but the shape is not
+ * transcript-specific: an adapter that reads an API usage response or takes
+ * operator-supplied figures produces this same object.
+ */
+export type TranscriptSummary = {
+  components: UsageComponents
+  /** The model id for the turn, or `null` when the host does not report one. */
+  model: string | null
+  /**
+   * How many distinct usage records were summed. Callers use `0` as the
+   * "nothing usable was collected" signal — a real turn always has at least
+   * one — rather than letting a zeroed summary format as a plausible `0/0/—`.
+   */
+  messageCount: number
+}
+
+export type TokensLineInput = {
+  phase: string
+  role: string
+  /**
+   * `null` only when the role is operator-metered — its host exposes no
+   * usage to the agent at all — which produces the all-`—` numbers segment
+   * the parser already tolerates. Never a convenience escape for a
+   * self-metering role whose collection step merely failed: that case is an
+   * error to report, not a blank to emit (`aeg-root/tranche-model.md` §12).
+   */
+  summary: TranscriptSummary | null
+  /** Overrides the model the adapter derived, if given. */
+  modelOverride?: string
+}
+
+/**
+ * Format the one-line `Tokens: <phase> — <role> — <model> — <in>/<out>/<cost>`
+ * report that `parse-token-report.ts`'s `parseTokensLines` consumes. The
+ * grammar is frozen (three parsers depend on it) — this function must never
+ * change its shape, only what feeds it.
+ *
+ * `Tokens in` is the full input-side total (`inputTokens +
+ * cacheCreationInputTokens + cacheReadInputTokens`) — genuinely every
+ * token that went in, not a partial figure. Cache reads can outweigh fresh
+ * input by two orders of magnitude on a long session, so that total is
+ * never the whole story on its own; `formatBreakdown` reports the four
+ * components separately for anyone reading the reporter's own output,
+ * rather than letting the single blended cell stand as if it were.
+ *
+ * Cost is always reported as `—`: no maintained, accurate $/token pricing
+ * table for current models lives in this package (the one in
+ * `@atta/adapter-langgraph` is a different product's provider-pricing
+ * table, out of this task's surface, and does not cover these model ids) —
+ * an unverified guess baked into a PR's permanent history is worse than an
+ * honest unknown.
+ */
+/**
+ * An embedded newline could forge a synthetic row/line neither writer ever
+ * intended, regardless of which grammar's own delimiter is in play — shared
+ * by both sanitizers below.
+ */
+function stripNewlines(value: string): string {
+  return value.replace(/\r?\n/g, ' ')
+}
+
+/**
+ * Table-row sanitizer: escapes `|` (the cell delimiter `splitTableRow`
+ * already expects `\|` for on read — the same escape convention, applied on
+ * write) on top of `stripNewlines`. Used by `formatTokenReportRow` for every
+ * free-text cell — `phase`, `role`, the derived `model`, and `date` —
+ * because any of them can arrive from an untrusted CLI flag or a git branch
+ * name, both of which can legally contain `|` and newlines (found live: a
+ * crafted branch name produced a row whose columns silently shifted past
+ * `parseTokenReportEntries`, discarding real measured usage with no error).
+ */
+function sanitizeForTableCell(value: string): string {
+  return stripNewlines(value).replace(/\|/g, '\\|')
+}
+
+/**
+ * `Tokens: …` line sanitizer. `parse-token-report.ts`'s `SEGMENT_SEP`
+ * (`/\s+[—–-]\s+/`) is a whitespace-flanked dash — and a field-local fix
+ * (removing the flanking whitespace around a dash the field itself
+ * contains) is provably incomplete: the JOIN ITSELF contributes whitespace
+ * on both sides of every field (the literal `" — "` between segments), so a
+ * field merely ENDING or STARTING with a dash reconstructs the exact same
+ * pattern from the boundary alone — `"9 -"` joined with the next field's
+ * leading `" — "` reads back as `"...9 - — ..."`, a real `SEGMENT_SEP`
+ * match, with no dash-adjacent whitespace inside the field at all to strip
+ * (found live: `--phase "9 -" --role "Dev -"` silently dropped the real
+ * `tokensIn`). No amount of field-local whitespace-stripping closes this —
+ * the hazard is the CHARACTER, reachable from any position once anything
+ * joins around it, not a particular spacing.
+ *
+ * The fix that actually closes it: remove the character itself from the
+ * field's vocabulary, but ONLY where it's actually reachable by
+ * `SEGMENT_SEP` — a dash counts as reachable on a given side when that
+ * side is whitespace, OR is the very edge of the field (every field in
+ * this grammar sits directly against a `" — "` join or the `"Tokens: "`
+ * prefix, so an edge is guaranteed adjacent to boundary whitespace once
+ * concatenated). A dash is substituted only when BOTH sides are reachable
+ * — matching exactly what `SEGMENT_SEP` itself requires (whitespace on
+ * both sides) once the guaranteed boundary whitespace is accounted for.
+ * An ordinary hyphenated identifier like `"claude-sonnet-5"` has
+ * non-whitespace, non-edge neighbors on both sides of every hyphen and is
+ * left completely untouched — a whole-field substitution (an earlier draft
+ * of this fix) needlessly mangled every such identifier, which is why this
+ * checks each dash's actual neighbors instead of blanket-replacing the
+ * class. This is also less lossy than the whitespace-stripping this
+ * replaces: two phase labels that only differed in spacing around a
+ * hazardous hyphen (`"9-fix"` — never hazardous, untouched — vs.
+ * `"9 - fix"` — hazardous, substituted) used to sanitize to byte-identical
+ * output; substitution preserves spacing, changing only the one character
+ * that must never survive verbatim in a hazardous position.
+ */
+const DASH_LOOKALIKES: Record<string, string> = {
+  '-': '‑', // U+2011 NON-BREAKING HYPHEN
+  '–': '‒', // U+2012 FIGURE DASH
+  '—': '―' // U+2015 HORIZONTAL BAR
+}
+const DASH_CHARS = new Set(Object.keys(DASH_LOOKALIKES))
+
+/**
+ * `formatTokenReportRow`'s own table cells escape `|` as `\|` because
+ * `splitTableRow` reads that convention back on the other side (`#313`).
+ * This line has no such reader — nothing unescapes a backslash out of it —
+ * so a literal `\|` here would just be a backslash followed by a visible
+ * bar, one more hazardous character rather than fewer. A same-glyph
+ * lookalike, matching `DASH_LOOKALIKES`'s own approach, neutralizes the
+ * delimiter unconditionally (unlike a dash, no ordinary model id legitimately
+ * contains a pipe, so there is no adjacency case to preserve): an
+ * attacker-controlled `model` field (`#313`'s live reproduction: a transcript
+ * whose `message.model` read `attacker | evil-injected-cell | extra`) must
+ * not survive with a real `|` if this line is later quoted verbatim inside
+ * an actual markdown table cell by anything downstream — `pr report --write`
+ * already escapes correctly at its own render step (`formatTokenReportRow`),
+ * but this line, not that one, is what `#313`'s reproduction actually
+ * printed, and it carries no such guarantee of its own once it leaves here.
+ */
+const PIPE_LOOKALIKE = '｜' // U+FF5C FULLWIDTH VERTICAL LINE
+
+function sanitizeForTokensLine(value: string): string {
+  const stripped = stripNewlines(value)
+  let result = ''
+  for (let i = 0; i < stripped.length; i++) {
+    const ch = stripped[i] as string
+    if (ch === '|') {
+      result += PIPE_LOOKALIKE
+      continue
+    }
+    if (DASH_CHARS.has(ch)) {
+      const leftReachable = i === 0 || /\s/.test(stripped[i - 1] as string)
+      const rightReachable = i === stripped.length - 1 || /\s/.test(stripped[i + 1] as string)
+      if (leftReachable && rightReachable) {
+        result += DASH_LOOKALIKES[ch]
+        continue
+      }
+    }
+    result += ch
+  }
+  return result
+}
+
+/** Shared by `formatTokensLine` and `formatTokenReportRow` — one place that turns a summary into the model/tokensIn/tokensOut cells both grammars report, so the two shapes can never drift on the arithmetic. `model` is `null` rather than the `—` placeholder when neither `modelOverride` nor the summary supplies one — that placeholder is a sentinel THIS module emits, never untrusted content, and must never be run through either grammar's sanitizer (which would rewrite its `—` into something that no longer reads as "unknown"). Each caller substitutes the literal `—` for `null` itself, after sanitizing everything that came from `input`. */
+function renderCells(input: TokensLineInput): { model: string | null; tokensIn: string; tokensOut: string } {
+  const model = input.modelOverride ?? input.summary?.model ?? null
+  if (!input.summary) return { model, tokensIn: '—', tokensOut: '—' }
+  const { inputTokens, cacheCreationInputTokens, cacheReadInputTokens, outputTokens } = input.summary.components
+  const tokensIn = inputTokens + cacheCreationInputTokens + cacheReadInputTokens
+  return { model, tokensIn: String(tokensIn), tokensOut: String(outputTokens) }
+}
+
+export function formatTokensLine(input: TokensLineInput): string {
+  const { model, tokensIn, tokensOut } = renderCells(input)
+  const phase = sanitizeForTokensLine(input.phase)
+  const role = sanitizeForTokensLine(input.role)
+  const safeModel = model === null ? '—' : sanitizeForTokensLine(model)
+  if (!input.summary) {
+    return `Tokens: ${phase} — ${role} — ${safeModel} — —`
+  }
+  return `Tokens: ${phase} — ${role} — ${safeModel} — ${tokensIn}/${tokensOut}/—`
+}
+
+export type TokenReportRowInput = TokensLineInput & {
+  /** `YYYY-MM-DD`. Caller-supplied, never derived here — this file stays `Date.now()`-free per its purity charter above. */
+  date: string
+}
+
+/**
+ * The same cells `formatTokensLine` reports, rendered as one `| Phase | Role
+ * | Agent/Model | Tokens in | Tokens out | Cost | Date |` markdown-table row
+ * — the shape `aeg-root/roles/developer.md`'s "Token report" heading and
+ * `parse-token-report.ts`'s `parseTokenReportEntries` (table form) both
+ * already expect. `Cost` is always `—`, same reasoning as `formatTokensLine`'s
+ * own Cost cell: no maintained per-model pricing table exists in this package.
+ */
+export function formatTokenReportRow(input: TokenReportRowInput): string {
+  const { model, tokensIn, tokensOut } = renderCells(input)
+  const phase = sanitizeForTableCell(input.phase)
+  const role = sanitizeForTableCell(input.role)
+  const safeModel = model === null ? '—' : sanitizeForTableCell(model)
+  const date = sanitizeForTableCell(input.date)
+  return `| ${phase} | ${role} | ${safeModel} | ${tokensIn} | ${tokensOut} | — | ${date} |`
+}
+
+/**
+ * Human-readable component breakdown for the reporter's own console output
+ * — never folded silently into the single `Tokens in` cell. Not parsed by
+ * anything; informational only.
+ */
+export function formatBreakdown(summary: TranscriptSummary): string {
+  const { inputTokens, cacheCreationInputTokens, cacheReadInputTokens, outputTokens } = summary.components
+  return [
+    `  fresh input tokens:    ${inputTokens}`,
+    `  cache creation tokens: ${cacheCreationInputTokens}`,
+    `  cache read tokens:     ${cacheReadInputTokens}`,
+    `  output tokens:         ${outputTokens}`,
+    `  model:                 ${summary.model ?? '—'}`,
+    `  messages summed:       ${summary.messageCount}`
+  ].join('\n')
+}