@attalabs/vinaya 0.21.0 → 0.23.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/milestone-validation.ts

@@ -0,0 +1,240 @@
+/**
+ * Milestone-shape validation for `vinaya milestone create` (vinaya-milestone-model-v1
+ * task 2). Pure — no `fs`, no `gh`. The command calls `checkMilestoneShape` before
+ * any forge write, so a malformed body never reaches GitHub.
+ *
+ * A Milestone's description carries three independent things, each parsed and
+ * removed from the remainder in turn: an optional `Release:` field (the sole
+ * authority for the milestone's version — never the title), an optional
+ * `### Tranche intents` section (one bullet per tranche this milestone will
+ * eventually hold, `- <slug>: <intent text>`), and the goal (whatever prose is
+ * left once both are removed). The goal is mandatory; `Release:` and the
+ * intents section are each optional but must parse if present.
+ */
+
+import { stripCode } from '@attalabs/aeg-forge-state'
+
+export type MilestoneIntent = { slug: string; goal: string }
+
+export type ReleaseField = {
+  /** A `Release:` field line exists outside code. Says nothing about whether its value parsed. */
+  declared: boolean
+  /** The parsed version string, or `null` when absent or malformed. */
+  value: string | null
+}
+
+export type MilestoneShapeResult =
+  | { status: 'pass'; goal: string; release: string | null; intents: MilestoneIntent[] }
+  | { status: 'fail'; errors: string[] }
+
+/**
+ * Line-anchored, `**`-optional on both sides, same shape as `PROJECT_FIELD`
+ * (`@attalabs/aeg-forge-state`'s `list-tasks.ts`) — the reference grammar this
+ * field is deliberately matched against rather than approximated. Un-global
+ * and `.exec`'d once: first match wins.
+ */
+const RELEASE_FIELD = /^\s*(?:\*\*)?Release(?:\*\*)?\s*:\s*(?:\*\*)?\s*(.+)$/im
+
+/** Peels the markup/punctuation a field value carries in prose — same edge set as `unwrapValue`. */
+const VALUE_EDGE_MARKUP = /^[`.;\s]+|[`.;\s]+$/g
+
+function unwrapValue(raw: string): string {
+  return raw.replace(/\*\*/g, '').replace(VALUE_EDGE_MARKUP, '')
+}
+
+/** A semver-shaped version: optional `v` prefix, `MAJOR.MINOR.PATCH`, optional pre-release/build. */
+const RELEASE_VALUE = /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?(?:\+[0-9A-Za-z][0-9A-Za-z.-]*)?$/
+
+/** Text with code fences/indented blocks stripped, inline spans kept — same reading `PROJECT_FIELD` uses. */
+function pathText(body: string): string {
+  return stripCode(body, { inlineSpans: 'keep' })
+}
+
+/** The actual reader, over already-stripped text — shared so `checkMilestoneShape` (which already holds `text`) never pays for a second `stripCode` pass over the same body. */
+function releaseFieldFromText(text: string): ReleaseField {
+  const m = text.match(RELEASE_FIELD)
+  if (!m) return { declared: false, value: null }
+  const raw = unwrapValue(m[1] ?? '')
+  return { declared: true, value: RELEASE_VALUE.test(raw) ? raw : null }
+}
+
+/**
+ * Reads the `Release:` field. `declared: true, value: null` is the malformed
+ * case — the field exists but its value isn't a version — distinct from
+ * `declared: false` (no field at all, which is a valid, versionless milestone).
+ */
+export function releaseFieldFromBody(body: string): ReleaseField {
+  return releaseFieldFromText(pathText(body))
+}
+
+const INTENTS_HEADING = /^#{1,6}\s*Tranche intents\s*$/im
+const NEXT_HEADING = /^#{1,6}\s+\S/m
+const INTENT_BULLET = /^-\s+([a-z0-9][a-z0-9-]*)\s*:\s*(.+)$/i
+
+/** The intents heading's own span plus its section body — `null` when there is no heading at all. */
+function intentsBlock(text: string): { start: number; end: number; section: string } | null {
+  const start = text.match(INTENTS_HEADING)
+  if (!start || start.index === undefined) return null
+  const rest = text.slice(start.index + start[0].length)
+  const next = rest.match(NEXT_HEADING)
+  const sectionEnd = next && next.index !== undefined ? next.index : rest.length
+  return { start: start.index, end: start.index + start[0].length + sectionEnd, section: rest.slice(0, sectionEnd) }
+}
+
+/** Slices the intents section out of `pathText(body)` — from just after the heading to the next heading or end. */
+function intentsSectionText(text: string): string | null {
+  return intentsBlock(text)?.section ?? null
+}
+
+/**
+ * Parses the `### Tranche intents` section, if present. `null` means no
+ * heading at all (a valid, intent-less milestone). A heading whose non-blank
+ * lines don't all match the bullet grammar is malformed — reported via
+ * `malformed: true` rather than silently dropping the bad line, mirroring
+ * `ProjectField.unparsed`'s fail-closed discipline.
+ */
+function parseIntents(text: string): { intents: MilestoneIntent[]; malformed: boolean } {
+  const section = intentsSectionText(text)
+  if (section === null) return { intents: [], malformed: false }
+
+  const intents: MilestoneIntent[] = []
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0) continue
+    const m = trimmed.match(INTENT_BULLET)
+    if (!m) return { intents: [], malformed: true }
+    intents.push({ slug: (m[1] ?? '').toLowerCase(), goal: (m[2] ?? '').trim() })
+  }
+  return { intents, malformed: false }
+}
+
+/** Removes the first `Release:` line and the whole intents section (heading included) from `pathText(body)`. */
+function goalRemainder(text: string): string {
+  const withoutRelease = text.replace(RELEASE_FIELD, '')
+  const block = intentsBlock(withoutRelease)
+  const remainder = block ? withoutRelease.slice(0, block.start) + withoutRelease.slice(block.end) : withoutRelease
+  return remainder.trim()
+}
+
+/**
+ * Refuses a milestone body before any forge write: the goal absent, `Release:`
+ * present but malformed, or the intents section unparseable. Shape-guarded
+ * only — like `checkIssueRationale`, this checks presence/well-formedness,
+ * never whether the content is right.
+ */
+export function checkMilestoneShape(body: string): MilestoneShapeResult {
+  const errors: string[] = []
+  const text = pathText(body)
+
+  const release = releaseFieldFromText(text)
+  if (release.declared && release.value === null) {
+    errors.push(
+      'milestone-validation Release: the `Release:` field is present but is not a version — ' +
+        'write a semver value (e.g. `Release: 1.2.0`), or omit the field entirely for a milestone that declares no version.'
+    )
+  }
+
+  const { intents, malformed } = parseIntents(text)
+  if (malformed) {
+    errors.push(
+      'milestone-validation intents: the `### Tranche intents` section does not parse — every non-blank ' +
+        'line under it must read `- <slug>: <intent text>`.'
+    )
+  }
+
+  const goal = goalRemainder(text)
+  if (goal.length === 0) {
+    errors.push(
+      'milestone-validation goal: no goal text — a milestone description must carry prose beyond its ' +
+        '`Release:` field and `### Tranche intents` section.'
+    )
+  }
+
+  if (errors.length > 0) return { status: 'fail', errors }
+  return { status: 'pass', goal, release: release.value, intents }
+}
+
+// ---------------------------------------------------------------------------
+// `vinaya milestone adopt` (vinaya-milestone-migration-v1 task 1) — checkAdoptable
+// ---------------------------------------------------------------------------
+
+/**
+ * One requested slug's forge facts, gathered by the CLI before any write.
+ * `checkAdoptable` never fetches — the caller does one bounded round of
+ * reads (the repo's label list, the repo's Milestone list, and one
+ * `vinaya/tranche:<slug>`-labeled Issue list per requested slug) and hands
+ * the results in as plain data.
+ */
+export type AdoptSlugFacts = {
+  slug: string
+  /** Whether `vinaya/tranche:<slug>` exists as a real label in this repo. */
+  labelExists: boolean
+  /** Issue numbers currently carrying the label, any state. */
+  issueNumbers: number[]
+  /**
+   * Native-milestone titles this slug's Issues are CURRENTLY attached to,
+   * excluding `null` (unattached — the ordinary state for a label-only
+   * tranche that has never been adopted), the slug itself (its own legacy
+   * 1:1 tranche-Milestone — the ordinary pre-adopt state for a
+   * legacy-titled tranche), and the requested target (already adopted here,
+   * a harmless no-op re-run). What remains is exactly "attached to some
+   * OTHER Milestone" — evidence of a prior `adopt` into a different target.
+   * Empty when none.
+   */
+  adoptedElsewhere: string[]
+}
+
+/** The target Milestone's forge facts. */
+export type AdoptTargetFacts = {
+  title: string
+  exists: boolean
+  state: 'open' | 'closed' | null
+}
+
+export type AdoptFacts = {
+  target: AdoptTargetFacts
+  slugs: AdoptSlugFacts[]
+}
+
+export type AdoptResult = { status: 'pass' } | { status: 'fail'; errors: string[] }
+
+/**
+ * Refuses an `adopt` invocation before any forge write. Four independent
+ * checks — an unknown slug, a slug whose label carries no Issues, a target
+ * that does not exist or is closed, and a slug already adopted into a
+ * different Milestone — evaluated over the WHOLE batch of requested slugs at
+ * once, so one bad slug in a multi-slug invocation blocks every slug in that
+ * invocation, not just its own: a half-applied adopt leaves Issues split
+ * across two Milestones with no undo. Pure: takes already-gathered facts,
+ * fetches nothing, writes nothing.
+ */
+export function checkAdoptable(facts: AdoptFacts): AdoptResult {
+  const errors: string[] = []
+
+  if (!facts.target.exists) {
+    errors.push(
+      `milestone-adopt target: Milestone "${facts.target.title}" does not exist — create it first with \`vinaya milestone create\`.`
+    )
+  } else if (facts.target.state === 'closed') {
+    errors.push(`milestone-adopt target: Milestone "${facts.target.title}" is closed — adopt requires an open target.`)
+  }
+
+  for (const s of facts.slugs) {
+    if (!s.labelExists) {
+      errors.push(`milestone-adopt unknown-slug: no \`vinaya/tranche:${s.slug}\` label exists in this repo.`)
+      continue
+    }
+    if (s.issueNumbers.length === 0) {
+      errors.push(`milestone-adopt no-issues: \`vinaya/tranche:${s.slug}\` carries no Issues — nothing to adopt.`)
+      continue
+    }
+    if (s.adoptedElsewhere.length > 0) {
+      errors.push(
+        `milestone-adopt already-adopted: "${s.slug}" is already adopted into "${s.adoptedElsewhere.join('", "')}" — adopt it from there, not from here.`
+      )
+    }
+  }
+
+  if (errors.length > 0) return { status: 'fail', errors }
+  return { status: 'pass' }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/no-disk-state.ts

@@ -0,0 +1,50 @@
+/**
+ * New-on-disk-state guard (#512 Part D). Pure — no `fs`, no `git`/`gh` I/O.
+ * Flags a diff-touched path as a disk-state offender given its change
+ * status (`added` — the path didn't exist on the base ref — or `modified`
+ * — it already did):
+ *
+ * (a) A live tranche topology file directly under `aeg-root/tranches/`
+ *     (not a subdirectory) — the residue class this task's own Part B proved
+ *     unnecessary (forge derivation already covers it, see
+ *     `aeg-drift-prevention-v1.md`'s deletion). Fails on `added` OR
+ *     `modified`: this file class shouldn't exist at all post-cutover,
+ *     whether newly created or resurrected via an edit.
+ *
+ * (b) Any `.md` file anywhere under `aeg-root/tranches/` (any depth,
+ *     including `completed/**`) — but ONLY when
+ *     `added`. `completed/**`'s existing files are legacy archive
+ * (explicitly excludes them, per `tranche-model.md` §4/§11 —
+ *     they're never deleted or migrated, and editing one to fix a typo
+ *     must stay legal); this rule instead closes the gap a path-shape-only
+ *     exemption would leave open — a BRAND NEW file smuggled directly into
+ *     `completed/` (or any other subdirectory) to dodge rule (a)'s
+ *     top-level check. Deliberately status-based, not a hardcoded filename
+ *     allowlist: the legacy set only grows via the (currently-dormant,
+ *     forge-native-cutover-pending) Archivist move-to-completed flow, never
+ *     via this gate's own exemption logic.
+ *
+ * (c) Any `*.tokens.md` file, anywhere in the repo — the pre- ledger
+ *     shape `Tokens-in-PR-body` superseded — but ONLY when `added` (an
+ *     edit to one of the 4 existing legacy `completed/*.tokens.md` files
+ *     must stay legal, same reasoning as (b)).
+ */
+
+export type DiskStateFileStatus = 'added' | 'modified'
+
+const TOP_LEVEL_TOPOLOGY_FILE = /^aeg-root\/tranches\/[^/]+\.md$/
+const ANY_DEPTH_TRANCHES_MD = /^aeg-root\/tranches\/.*\.md$/
+const TOKENS_FILE = /\.tokens\.md$/
+
+export function isNewDiskStateFile(path: string, status: DiskStateFileStatus): boolean {
+  // The tranche model doc used to live at `aeg-root/tranches/README.md`
+  // and needed an explicit carve-out here so editing it never read as new disk
+  // state. It is now `aeg-root/tranche-model.md`, outside the directory this
+  // guard watches, so the carve-out is gone rather than left as a line that
+  // can never fire.
+  if (TOP_LEVEL_TOPOLOGY_FILE.test(path)) return true
+
+  if (status !== 'added') return false
+
+  return ANY_DEPTH_TRANCHES_MD.test(path) || TOKENS_FILE.test(path)
+}

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

@@ -0,0 +1,77 @@
+import { readMarkdownTable } from './parse-registry'
+import type { LedgerRow } from './types'
+
+/**
+ * Parse the append-only token/cost ledger for a tranche. See
+ * `aeg-root/tranche-model.md` §12 for the canonical format.
+ *
+ * The ledger lives in a sibling file `aeg-root/tranches/<name>.tokens.md`
+ * (the recommended home, since two roles appending rows do not collide with
+ * a Planner editing the topology file) but the parser also accepts a
+ * `## Token ledger` section inside any markdown — so a future tranche that
+ * chose the inline form still parses.
+ *
+ * Pure: no I/O. The caller reads the file contents and hands them in.
+ *
+ * Tolerant by design: a malformed row is skipped rather than throwing, so a
+ * typo does not crash Studio's display of a tranche's other rows.
+ */
+export function parseLedger(md: string): LedgerRow[] {
+  const rows = readMarkdownTable(md, /^#{1,6}\s+Token\s+ledger\b/i)
+  const out: LedgerRow[] = []
+  for (const row of rows) {
+    const parsed = rowFromCells(row)
+    if (parsed) out.push(parsed)
+  }
+  return out
+}
+
+/**
+ * Turn one 7-cell row (`Phase | Role | Agent/Model | Tokens in | Tokens out |
+ * Cost | Date`) into a `LedgerRow`, or `null` when the row is unusable.
+ * Exported so other sources that produce the same row-shape from a different
+ * layout (e.g. `parse-token-report.ts`'s PR-body/verdict-comment sources)
+ * reuse this exact cell-parsing/null-tolerance semantics rather than
+ * re-implementing it — see that file's module docstring.
+ */
+export function rowFromCells(cells: string[]): LedgerRow | null {
+  // Expected 7 columns: Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date.
+  if (cells.length < 7) return null
+  const phase = (cells[0] ?? '').trim()
+  // Phase is the row's identity — every other cell may be unknown, but a
+  // row without a phase is unusable (it can't be located on a re-pivot).
+  if (!phase) return null
+  return {
+    phase,
+    role: (cells[1] ?? '').trim(),
+    agentModel: (cells[2] ?? '').trim(),
+    tokensIn: parseIntCell(cells[3] ?? ''),
+    tokensOut: parseIntCell(cells[4] ?? ''),
+    cost: parseCostCell(cells[5] ?? ''),
+    date: (cells[6] ?? '').trim()
+  }
+}
+
+function parseIntCell(cell: string): number | null {
+  const trimmed = cell.replace(/`/g, '').trim()
+  if (!trimmed || isEmDashOrDash(trimmed)) return null
+  // Tolerate thousand-separator commas and underscores so a hand-written
+  // `184,327` or `184_327` still resolves.
+  const normalized = trimmed.replace(/[,_\s]/g, '')
+  if (!/^-?\d+$/.test(normalized)) return null
+  return Number(normalized)
+}
+
+function parseCostCell(cell: string): number | null {
+  const trimmed = cell.replace(/`/g, '').trim()
+  if (!trimmed || isEmDashOrDash(trimmed)) return null
+  // Strip a leading `$` and any thousand-separators; preserve the decimal.
+  const normalized = trimmed.replace(/^\$/, '').replace(/[,_\s]/g, '')
+  if (!/^-?\d+(\.\d+)?$/.test(normalized)) return null
+  return Number(normalized)
+}
+
+function isEmDashOrDash(s: string): boolean {
+  const t = s.trim()
+  return t === '—' || t === '-' || t === '–'
+}

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

@@ -0,0 +1,105 @@
+import type { Project, Registry } from './types'
+
+/**
+ * Parse `aeg-root/projects.md` and return its `## Registry` table as a typed
+ * `Registry`. Surrounding prose is ignored.
+ *
+ * Tolerates a prose last-cell (e.g. "(state tracked globally for now)") by
+ * setting `statePath: null`. A real path is detected by the backtick wrapping
+ * (`<path>`) used in the live file's columns 2 + 3 + (when present) 4.
+ *
+ * The function is forgiving: a malformed row is skipped rather than throwing,
+ * so a typo in the markdown does not crash all of Studio. Validation of
+ * `Project:` references against the result is a separate concern.
+ */
+export function parseRegistry(md: string): Registry {
+  const rows = readMarkdownTable(md, /^##\s+Registry\b/i)
+  const projects: Project[] = []
+  for (const row of rows) {
+    // Expect 4 columns: Project | Path | Specs | Per-project state.
+    if (row.length < 4) continue
+    const name = stripBackticks(row[0] ?? '').trim()
+    const path = stripBackticks(row[1] ?? '').trim()
+    const specsPath = stripBackticks(row[2] ?? '').trim()
+    const stateCell = (row[3] ?? '').trim()
+    if (!name || !path || !specsPath) continue
+    projects.push({
+      name,
+      path,
+      specsPath,
+      statePath: parseStateCell(stateCell)
+    })
+  }
+  return projects
+}
+
+function parseStateCell(cell: string): string | null {
+  if (!cell) return null
+  // Prose state cell — anything that doesn't look like a backtick-wrapped path.
+  // The live file uses `apps/<x>/aeg-project/` for tracked state and
+  // parenthesized prose like "(state tracked globally for now)" otherwise.
+  const stripped = stripBackticks(cell).trim()
+  // If we stripped backticks and got a path-shaped string, return it.
+  if (/^[\w./@-]+\/?$/.test(stripped) && cell.includes('`')) {
+    return stripped
+  }
+  return null
+}
+
+function stripBackticks(s: string): string {
+  return s.replace(/`/g, '')
+}
+
+/**
+ * Generic markdown-table reader: finds the first `| … |` table block following
+ * the `headingMatcher` regex, skips the header + separator rows, and returns
+ * each body row as an array of trimmed cell strings.
+ *
+ * Pipes can be escaped inline as `\|`; this is unescaped after the split.
+ * Leading/trailing pipes are tolerated. Lines outside the table block end
+ * iteration.
+ */
+export function readMarkdownTable(md: string, headingMatcher: RegExp): string[][] {
+  const lines = md.split(/\r?\n/)
+  let i = 0
+  // Advance to the section heading.
+  for (; i < lines.length; i++) {
+    if (headingMatcher.test(lines[i] ?? '')) {
+      i++
+      break
+    }
+  }
+  if (i >= lines.length) return []
+  // Advance to the first table line.
+  for (; i < lines.length; i++) {
+    if ((lines[i] ?? '').trim().startsWith('|')) break
+  }
+  // Skip header + separator.
+  if (i + 1 >= lines.length) return []
+  i += 2
+  const out: string[][] = []
+  for (; i < lines.length; i++) {
+    const trimmed = (lines[i] ?? '').trim()
+    if (!trimmed.startsWith('|')) break
+    out.push(splitTableRow(trimmed))
+  }
+  return out
+}
+
+/** Exported for reuse by parsers that read a table body outside `readMarkdownTable`'s single-section-per-call model (e.g. `parse-token-report.ts`'s multi-entry "Token report" sections). */
+export function splitTableRow(row: string): string[] {
+  // Use a placeholder for escaped pipes, split, then restore.
+  // The sentinel is a NUL, escaped rather than typed literally. A raw NUL byte
+  // in the source makes git classify this whole FILE as binary: `git diff`
+  // reports `Bin 3715 -> 3716 bytes, 0 insertions(+), 0 deletions(-)` instead
+  // of a reviewable diff, and `git grep -n` answers `Binary file ... matches`
+  // with no line number, so every sweep that greps this repo silently skipped
+  // it. `\u0000` is the same byte at runtime and keeps the file text.
+  const PLACEHOLDER = '\u0000PIPE\u0000'
+  const escaped = row.replace(/\\\|/g, PLACEHOLDER)
+  const parts = escaped.split('|').map((s) => s.trim())
+  // Strip the empty cells produced by leading and trailing `|`.
+  if (parts.length && parts[0] === '') parts.shift()
+  if (parts.length && parts[parts.length - 1] === '') parts.pop()
+  return parts.map((p) => p.split(PLACEHOLDER).join('|'))
+}

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

@@ -0,0 +1,165 @@
+import { rowFromCells } from './parse-ledger'
+import { splitTableRow } from './parse-registry'
+import type { LedgerRow } from './types'
+
+/**
+ * Live-source token parsing (aeg-forge-state-v1 task 4b, #445). Where
+ * `parse-ledger.ts` reads the Archivist's hand-assembled `<name>.tokens.md`
+ * ledger, this file extracts the same `LedgerRow` shape directly from the
+ * artifacts says every role already produces on its own turn — the
+ * Developer's "Token report" section in a PR body, and the Reviewer's /
+ * Security's / Planner's one-line `Tokens: …` report in a verdict comment,
+ * PR body, or planning report. Nothing here does I/O — the caller (Studio's
+ * forge adapter, `apps/vinaya/web/src/lib/forge/fetch-token-ledger.ts`)
+ * fetches the PR bodies/comments and hands them to `aggregateTaskTokenRows`.
+ *
+ * Cell parsing (`—`/null tolerance, thousand-separator commas, `$` cost
+ * prefix) is NOT reimplemented here — every row is built through
+ * `parse-ledger.ts`'s `rowFromCells`, so a live-fetched row and a
+ * `.tokens.md`-parsed row for the same underlying report are byte-identical
+ * in how their cells resolve.
+ */
+
+// A "Token report" heading, alone on its line: `## Token report`,
+// `### Token report`, or the bold-inline `**Token report**` form seen in the
+// wild (real PRs use both — #412 uses `## Token report`, #454 uses the bold
+// form). A PR re-pushed after `CHANGES_REQUESTED` carries this heading more
+// than once — every occurrence is parsed as its own entry (roles/developer.md:
+// re-entry appends a new "Token report" entry, never edits the first).
+const TOKEN_REPORT_HEADING = /^\s*(?:#{1,6}\s*Token report\s*|\*\*Token report\*\*)\s*$/i
+
+// Inline field-list form, a real drift already present in this repo's own
+// history (PR #374, #362) alongside the table form: one line reading
+// `Phase: … | Role: … | Agent/Model: … | Tokens in: … | Tokens out: … |
+// Cost: … | Date: …`. Tolerated as a second recognized shape rather than
+// treated as malformed, since both are real, current, human-authored output.
+const INLINE_FIELD_LIST =
+  /Phase:\s*([^|]+?)\s*\|\s*Role:\s*([^|]+?)\s*\|\s*Agent\/Model:\s*([^|]+?)\s*\|\s*Tokens in:\s*([^|]+?)\s*\|\s*Tokens out:\s*([^|]+?)\s*\|\s*Cost:\s*([^|]+?)\s*\|\s*Date:\s*(.+?)\s*$/im
+
+/**
+ * Extract every "Token report" entry from a Developer's PR body. Each
+ * occurrence of the heading is parsed independently (table form preferred;
+ * falls back to the inline field-list form when no table follows), and
+ * every occurrence found contributes a row — a re-pushed PR undercounts if
+ * only the first/last match is read, per this task's own Traps section.
+ */
+export function parseTokenReportEntries(body: string): LedgerRow[] {
+  const lines = body.split(/\r?\n/)
+  const headingIdxs: number[] = []
+  lines.forEach((line, i) => {
+    if (TOKEN_REPORT_HEADING.test(line)) headingIdxs.push(i)
+  })
+
+  const out: LedgerRow[] = []
+  for (let h = 0; h < headingIdxs.length; h++) {
+    const start = (headingIdxs[h] as number) + 1
+    const end = h + 1 < headingIdxs.length ? (headingIdxs[h + 1] as number) : lines.length
+    const section = lines.slice(start, end).join('\n')
+
+    const tableRows = parseTableSection(section)
+    if (tableRows.length > 0) {
+      out.push(...tableRows)
+      continue
+    }
+    const inlineRow = parseInlineFieldList(section)
+    if (inlineRow) out.push(inlineRow)
+  }
+  return out
+}
+
+/** Same table-body-reading contract as `parse-registry.ts`'s `readMarkdownTable`, minus the heading search (already sliced to a single "Token report" section, which may repeat within one body — the thing `readMarkdownTable` cannot express). */
+function parseTableSection(section: string): LedgerRow[] {
+  const lines = section.split(/\r?\n/)
+  let i = 0
+  for (; i < lines.length; i++) {
+    if ((lines[i] ?? '').trim().startsWith('|')) break
+  }
+  if (i + 1 >= lines.length) return []
+  i += 2 // skip header + separator row
+  const out: LedgerRow[] = []
+  for (; i < lines.length; i++) {
+    const trimmed = (lines[i] ?? '').trim()
+    if (!trimmed.startsWith('|')) break
+    const row = rowFromCells(splitTableRow(trimmed))
+    if (row) out.push(row)
+  }
+  return out
+}
+
+function parseInlineFieldList(section: string): LedgerRow | null {
+  const m = section.match(INLINE_FIELD_LIST)
+  if (!m) return null
+  return rowFromCells([m[1], m[2], m[3], m[4], m[5], m[6], m[7]] as string[])
+}
+
+// `Tokens: <phase> — <Role> — <model> — <in>/<out>/<cost or — if unknown>`
+// (`roles/reviewer.md`, `roles/security.md`, `roles/planner.md` — identical
+// shape, phase/role text differs per role). Segments are separated by a dash
+// with a space on both sides so an agent/model name's own internal hyphens
+// (`claude-sonnet-5`) never split — a real separator always has surrounding
+// whitespace. Tolerates `-`/`–` alongside the docs' own `—`, since no real
+// verdict-comment example exists yet to confirm which glyph a live Reviewer
+// turn actually reproduces.
+const TOKENS_LINE_PREFIX = /^\s*(?:\*\*)?Tokens:(?:\*\*)?\s*(.+)$/i
+const SEGMENT_SEP = /\s+[—–-]\s+/
+
+/**
+ * Extract every Reviewer/Security/Planner `Tokens: …` line from a body of
+ * text (a verdict comment, a PR body, or a planning report). A re-review or
+ * re-planning reports again without editing the prior line, so more than one
+ * match is expected and every one is returned. A line that doesn't split
+ * into exactly the 4 documented segments is skipped, not guessed at — same
+ * discipline as `parse-ledger.ts`'s malformed-row tolerance.
+ */
+export function parseTokensLines(text: string): LedgerRow[] {
+  const out: LedgerRow[] = []
+  for (const rawLine of text.split(/\r?\n/)) {
+    const m = rawLine.match(TOKENS_LINE_PREFIX)
+    if (!m) continue
+    const rest = (m[1] as string).trim()
+    const segments = rest.split(SEGMENT_SEP)
+    if (segments.length !== 4) continue
+    const [phase, role, agentModel, numbers] = segments as [string, string, string, string]
+    const [tokensInCell, tokensOutCell, costCell] = splitNumbers(numbers)
+    const row = rowFromCells([phase.trim(), role.trim(), agentModel.trim(), tokensInCell, tokensOutCell, costCell, ''])
+    if (row) out.push(row)
+  }
+  return out
+}
+
+function splitNumbers(numbers: string): [string, string, string] {
+  const trimmed = numbers.trim()
+  if (isDashOnly(trimmed)) return ['—', '—', '—']
+  const parts = trimmed.split('/')
+  return [parts[0] ?? '—', parts[1] ?? '—', parts[2] ?? '—']
+}
+
+function isDashOnly(s: string): boolean {
+  return s === '—' || s === '-' || s === '–'
+}
+
+/** One merged PR's body + top-level comments — the caller's fetch result, no I/O here. */
+export type TokenSourcePr = {
+  number: number
+  body: string
+  comments: string[]
+}
+
+/**
+ * Pure aggregation over every merged PR associated with a task (its own
+ * branch's PR(s), plus any plan/cross-referenced PR carrying the Planner's
+ * report) — Developer "Token report" entries and `Tokens: …` lines from
+ * each PR body, and `Tokens: …` lines from each PR's comments. Missing or
+ * malformed reports simply produce no row for that report — never a
+ * fabricated figure — matching `archivist.md`'s own "flag it under DANGLING
+ * instead" discipline; the caller decides how to surface an empty result.
+ */
+export function aggregateTaskTokenRows(prs: TokenSourcePr[]): LedgerRow[] {
+  const out: LedgerRow[] = []
+  for (const pr of prs) {
+    out.push(...parseTokenReportEntries(pr.body))
+    out.push(...parseTokensLines(pr.body))
+    for (const comment of pr.comments) out.push(...parseTokensLines(comment))
+  }
+  return out
+}