@attalabs/vinaya 0.22.0 → 0.23.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/leftover-detection.ts

@@ -0,0 +1,68 @@
+/**
+ * Leftover-worktree/branch classification (aeg-governance-hardening task 11,
+ * #324). Pure — no `fs`, no `git` shell-outs. The CLI shim
+ * (`bin/verify-dispatch.ts`) gathers the three facts (does the remote branch
+ * exist, does a local worktree exist, how many commits is the branch ahead
+ * of main) and passes them in.
+ *
+ * Exists to answer, deterministically, "is it safe to run Step 0's
+ * `git worktree add -b <branch> origin/main` for this task?" — Step 0 itself
+ * never creates a commit, so ANY commit already ahead of main on this branch
+ * is real prior work, never an artifact of re-running Step 0. Silently
+ * recreating a branch that already has commits ahead of main would discard
+ * that work — the failure this module exists to prevent.
+ */
+
+export type LeftoverInput = {
+  /** A `task/<tranche>/<n>` branch already exists on the forge remote. */
+  branchExistsRemote: boolean
+  /** A local worktree for this task already exists on disk. */
+  worktreeExistsLocal: boolean
+  /** Commits on the task branch that are not yet on `origin/main`. */
+  commitsAheadOfMain: number
+  /**
+   * An OPEN pull request already exists for this task's branch, or `null`/
+   * omitted when unknown or none exists. Optional and additive — a caller
+   * that has no PR-number fact (e.g. `verify-dispatch.ts`'s existing call
+   * site, which only ever needed the three fields above) is unaffected.
+   */
+  openPrNumber?: number | null
+}
+
+export type LeftoverVerdict = 'clean' | 'resume' | 'stop'
+
+export type LeftoverResult = { verdict: LeftoverVerdict; reason: string }
+
+/**
+ * `clean`  — no branch, no worktree, zero commits ahead: safe to run Step 0 fresh.
+ * `resume` — a branch or worktree already exists but carries zero commits
+ *            ahead of main (e.g. a prior Step 0 ran but no work was
+ *            committed yet): reuse the existing worktree rather than
+ *            recreating it, but there is nothing to lose either way.
+ * `stop`   — commits already ahead of main exist: real work is already on
+ *            this branch. Never silently discard it — the Developer must
+ *            resume in the existing worktree, not re-run Step 0.
+ */
+export function classifyLeftover(input: LeftoverInput): LeftoverResult {
+  const { branchExistsRemote, worktreeExistsLocal, commitsAheadOfMain, openPrNumber } = input
+  const prSuffix = openPrNumber ? ` PR #${openPrNumber} is already open for this task.` : ''
+
+  if (commitsAheadOfMain > 0) {
+    return {
+      verdict: 'stop',
+      reason: `${commitsAheadOfMain} commit(s) already ahead of origin/main on this task branch — real work exists.${prSuffix} Do not re-run Step 0 (which would branch fresh from origin/main and orphan that work); resume in the existing worktree instead.`
+    }
+  }
+
+  if (branchExistsRemote || worktreeExistsLocal) {
+    return {
+      verdict: 'resume',
+      reason: `A ${branchExistsRemote ? 'remote branch' : ''}${branchExistsRemote && worktreeExistsLocal ? ' and a ' : ''}${worktreeExistsLocal ? 'local worktree' : ''} already exist for this task, with zero commits ahead of main — reuse it rather than recreating (\`git worktree add\` on an existing branch/dir will fail anyway).`
+    }
+  }
+
+  return {
+    verdict: 'clean',
+    reason: 'No branch, no worktree, no commits ahead of main — safe to run Step 0 fresh.'
+  }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/local-anchor-coverage.ts

@@ -0,0 +1,245 @@
+/**
+ * local-anchor-coverage.ts — a generic, regex-parameterized "dangling
+ * anchor" checker.
+ *
+ * The pattern this generalizes: `reader-resolvable-prose.ts`'s Class 1
+ * (`checkUnresolvableReferences`) flags a reference a reader cannot resolve
+ * at all — the pattern (a forge number, a tranche slug) IS the finding, full
+ * stop. This module handles the one-step-further case Issue #730 names: a
+ * reference that is FINE as long as something else nearby resolves it — an
+ * ordinal task mention ("Task 2") is fine beside a citation shaped
+ * `(task N, #issue)`, and only a finding when that citation is missing from
+ * its scope. Same "pattern is an input, not a constant" discipline as
+ * `reader-resolvable-prose.ts`, carried one step further: the CITATION
+ * pattern and its co-occurrence SCOPE are inputs too. This file has no
+ * `/Task \d+/` literal, no citation-shape regex, no product name — that
+ * knowledge belongs to whoever configures an instance (see
+ * `scripts/vinaya-checks/task-anchor.ts` for attalabs' own).
+ *
+ * Zero I/O: mirrors `reader-resolvable-prose.ts`'s in-memory-content shape
+ * (`files: { path, content }[]`, adapter-read) rather than
+ * `vocabulary-citation.ts`'s `grepFn`/`matchFn` injection. Reason: co-occurrence
+ * scoping (§ below) needs the whole file's line structure to group lines into
+ * blocks — a per-line grep-hit model would force the adapter to pre-chunk
+ * paragraphs itself before calling in, which is exactly the structural work
+ * this primitive exists to own.
+ *
+ * `pattern`/`mustCoOccurWith` are real `RegExp` objects, not POSIX-ERE
+ * strings — unlike `vocabulary-citation.ts`, nothing here shells out to
+ * `grep -E`, so the `\d`/`\w`/`\s`-avoidance caution that applies there (GNU
+ * grep reads those as literal characters) does not apply to this file; native
+ * `RegExp` supports them. A consumer that itself uses `grep` for file
+ * discovery (as `task-anchor.ts` does not — it reads files directly) would
+ * still need that caution on its own end, independent of this primitive.
+ */
+
+export type AnchorSourceFile = { path: string; content: string }
+
+/**
+ * `'line'` — the citation must appear on the same line as the anchor.
+ * `'block'` — the citation must appear anywhere in the anchor's enclosing
+ * block (see `splitIntoBlocks` below): a markdown paragraph, or a list item
+ * together with its nested sub-items and wrapped continuation lines. A
+ * blank line, or a new top-level (non-indented) bullet/heading, starts a new
+ * block — so two adjacent list items are two different blocks, never one.
+ */
+export type AnchorCoverageScope = 'line' | 'block'
+
+export type LocalAnchorCoverageOptions = {
+  pattern: RegExp
+  mustCoOccurWith: RegExp
+  scope: AnchorCoverageScope
+  /** Non-vacuity self-test (optional): `pattern` must match this string. */
+  sample?: string
+  /** Non-vacuity self-test (optional): `mustCoOccurWith` must match this string. */
+  coOccurSample?: string
+}
+
+export type AnchorCoverageFinding = {
+  file: string
+  line: number
+  match: string
+}
+
+export type LocalAnchorCoverageResult = {
+  findings: AnchorCoverageFinding[]
+  /**
+   * Names of whichever supplied sample(s) failed to self-match —
+   * `'pattern'` and/or `'mustCoOccurWith'`. A config bug reported loud
+   * instead of silently returning clean, same discipline as
+   * `vocabulary-citation.ts`'s `vacuousPatterns`.
+   */
+  vacuous: ('pattern' | 'mustCoOccurWith')[]
+}
+
+/** Strips `g`/`y` flags so a caller-supplied global/sticky regex can't leak `lastIndex` state into a one-shot `.test()`. */
+function testFresh(re: RegExp, text: string): boolean {
+  const flags = re.flags.replace(/[gy]/g, '')
+  return new RegExp(re.source, flags).test(text)
+}
+
+/** Ensures the regex used to iterate every match carries the `g` flag, without mutating the caller's object. */
+function toGlobalIterator(re: RegExp): RegExp {
+  const flags = re.flags.includes('g') ? re.flags : `${re.flags}g`
+  return new RegExp(re.source, flags)
+}
+
+/** Total match count of `re` in `text` — the co-occurrence "supply" a scope offers. */
+function countMatches(re: RegExp, text: string): number {
+  const iter = toGlobalIterator(re)
+  let count = 0
+  iter.lastIndex = 0
+  let m = iter.exec(text)
+  while (m !== null) {
+    count++
+    if (m.index === iter.lastIndex) iter.lastIndex++
+    m = iter.exec(text)
+  }
+  return count
+}
+
+function computeLineStarts(content: string): number[] {
+  const starts = [0]
+  for (let i = 0; i < content.length; i++) {
+    if (content.charCodeAt(i) === 10) starts.push(i + 1)
+  }
+  return starts
+}
+
+/** 1-based line number containing character offset `index`, via binary search over `lineStarts`. */
+function lineNumberAt(lineStarts: number[], index: number): number {
+  let lo = 0
+  let hi = lineStarts.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if ((lineStarts[mid] as number) <= index) lo = mid
+    else hi = mid - 1
+  }
+  return lo + 1
+}
+
+const BLANK_LINE = /^\s*$/
+/** A top-level (non-indented) list marker — `-`/`*`/`+` or `N.` — starts a new block; an indented nested item does not. */
+const TOP_LEVEL_BULLET = /^(?:[-*+]|[0-9]+\.)\s/
+const HEADING_LINE = /^#{1,6}\s/
+
+type Block = { startLine: number; endLine: number; text: string }
+
+/**
+ * Groups a file's lines into scope blocks: a blank line ends the current
+ * block; a new top-level bullet or heading also ends it (and starts its
+ * own); every other line — including an indented/nested bullet, or a
+ * wrapped continuation line — extends the current block. This is what makes
+ * "same paragraph/bullet" well-defined rather than a guess: two sibling
+ * list items on adjacent lines with no blank line between them are still
+ * two separate blocks (each starts its own on hitting the next top-level
+ * marker), while a nested sub-bullet stays part of its parent's block (an
+ * elaboration of the same anchor, not a separate one).
+ */
+function splitIntoBlocks(content: string): Block[] {
+  const lines = content.split('\n')
+  const blocks: Block[] = []
+  let current: string[] = []
+  let currentStartIdx = 0
+
+  const flush = (): void => {
+    if (current.length === 0) return
+    blocks.push({
+      startLine: currentStartIdx + 1,
+      endLine: currentStartIdx + current.length,
+      text: current.join('\n')
+    })
+    current = []
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] as string
+    if (BLANK_LINE.test(line)) {
+      flush()
+      continue
+    }
+    const isHeading = HEADING_LINE.test(line)
+    const startsNewBlock = TOP_LEVEL_BULLET.test(line) || isHeading
+    if (startsNewBlock && current.length > 0) flush()
+    if (current.length === 0) currentStartIdx = i
+    current.push(line)
+    // A heading is always a single-line block — it never absorbs the prose
+    // that follows it (that prose's own citation does not clear an anchor
+    // inside the heading's own text).
+    if (isHeading) flush()
+  }
+  flush()
+  return blocks
+}
+
+/**
+ * Flags every match of `pattern` that has no `mustCoOccurWith` match within
+ * its scope. Pure — takes file contents, returns findings; performs no I/O
+ * and knows nothing about what `pattern`/`mustCoOccurWith` mean.
+ *
+ * **Co-occurrence is counted, not merely detected.** A scope with two
+ * `pattern` matches and only one `mustCoOccurWith` match must flag one of
+ * them — checking "does a citation exist anywhere in this scope" lets a
+ * SINGLE real citation silently clear every other, unrelated anchor sharing
+ * the same block (found live in review: `"Task 2 did X, and Task 5 (task 5,
+ * #999) wrapped it up."` reported zero findings under a presence-only test,
+ * because "Task 5"'s citation cleared the unrelated "Task 2" anchor too).
+ * Each scope's citation matches are a fixed SUPPLY; each pattern match in
+ * that scope, in document order, consumes one — the first `N` matches (`N` =
+ * the scope's citation count) are covered, everything past that is a
+ * finding. This does not verify WHICH citation belongs to WHICH anchor
+ * (this primitive has no product-specific notion of "the same number") —
+ * only that supply meets demand, which is exactly what a purely structural,
+ * product-agnostic primitive can promise.
+ */
+export function checkLocalAnchorCoverage(
+  files: readonly AnchorSourceFile[],
+  options: LocalAnchorCoverageOptions
+): LocalAnchorCoverageResult {
+  const vacuous: ('pattern' | 'mustCoOccurWith')[] = []
+  if (options.sample !== undefined && !testFresh(options.pattern, options.sample)) vacuous.push('pattern')
+  if (options.coOccurSample !== undefined && !testFresh(options.mustCoOccurWith, options.coOccurSample)) {
+    vacuous.push('mustCoOccurWith')
+  }
+
+  const findings: AnchorCoverageFinding[] = []
+  const iterPattern = toGlobalIterator(options.pattern)
+
+  for (const file of files) {
+    const lineStarts = computeLineStarts(file.content)
+    const lines = file.content.split('\n')
+    const blocks = options.scope === 'block' ? splitIntoBlocks(file.content) : null
+
+    // Scope key: the block object itself (`'block'` scope) or the line
+    // number (`'line'` scope) — matches sharing a key share one citation
+    // supply, consumed in document order.
+    const remainingSupply = new Map<Block | number, number>()
+    const supplyFor = (key: Block | number, scopeText: string): number => {
+      const cached = remainingSupply.get(key)
+      if (cached !== undefined) return cached
+      const supply = countMatches(options.mustCoOccurWith, scopeText)
+      remainingSupply.set(key, supply)
+      return supply
+    }
+
+    iterPattern.lastIndex = 0
+    let match: RegExpExecArray | null = iterPattern.exec(file.content)
+    while (match !== null) {
+      const line = lineNumberAt(lineStarts, match.index)
+      const block = blocks ? (blocks.find((b) => line >= b.startLine && line <= b.endLine) ?? null) : null
+      const scopeText = block ? block.text : (lines[line - 1] ?? '')
+      const key: Block | number = block ?? line
+      const supply = supplyFor(key, scopeText)
+      if (supply > 0) {
+        remainingSupply.set(key, supply - 1)
+      } else {
+        findings.push({ file: file.path, line, match: match[0] })
+      }
+      // Guard against a zero-width match looping forever.
+      if (match.index === iterPattern.lastIndex) iterPattern.lastIndex++
+      match = iterPattern.exec(file.content)
+    }
+  }
+
+  return { findings, vacuous }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/main-branch-refusal.ts

@@ -0,0 +1,64 @@
+/**
+ * Ring-0 main-branch refusal (task 9, Issue #58). Mechanizes the
+ * worktree-plus-PR rule at ring 0 for adopters: refuses a commit or push
+ * whose current branch IS the repo's default branch — today enforced only
+ * by attalabs' hand-written husky shell (which `init` never generates) and
+ * detected post-merge by `audit --only=direct-push`. Pure — no `git`/`fs`
+ * I/O; the caller derives both branch facts and passes them in, same
+ * discipline as `no-disk-state.ts`.
+ *
+ * The discriminator that makes this safe: refusal keys on the SYMBOLIC
+ * current branch equaling the default branch. A detached HEAD (every CI
+ * checkout, or a deliberate `git checkout --detach`) has no symbolic branch
+ * name at all — `currentSymbolicBranch` is `null` — and always passes,
+ * never refused. Any branch other than the default passes too. Only a
+ * real, named local branch that literal-matches the default branch name
+ * refuses. A plain `vinaya check --all` run while parked on the default
+ * branch locally WILL refuse — that is the intended behavior (work belongs
+ * in worktrees), not a bug.
+ *
+ * `defaultBranch: null` means the caller could not derive the default
+ * branch (no resolvable `origin/HEAD`, no forge answer) — this predicate
+ * fails OPEN with a `warning` finding naming why, never a false refusal: a
+ * check whose job is refusing risky actions must not itself risk refusing
+ * a legitimate one it cannot actually evaluate.
+ */
+
+export type MainBranchRefusalReason = 'on-default-branch' | 'default-branch-undetermined'
+
+export type MainBranchRefusalFinding = {
+  reason: MainBranchRefusalReason
+  severity: 'error' | 'warning'
+  currentBranch: string
+  defaultBranch: string | null
+}
+
+export function checkMainBranchRefusal(facts: {
+  currentSymbolicBranch: string | null
+  defaultBranch: string | null
+}): MainBranchRefusalFinding | null {
+  const { currentSymbolicBranch, defaultBranch } = facts
+
+  // Detached HEAD — no symbolic branch to compare. Never refuse.
+  if (currentSymbolicBranch === null) return null
+
+  if (defaultBranch === null) {
+    return {
+      reason: 'default-branch-undetermined',
+      severity: 'warning',
+      currentBranch: currentSymbolicBranch,
+      defaultBranch: null
+    }
+  }
+
+  if (currentSymbolicBranch === defaultBranch) {
+    return {
+      reason: 'on-default-branch',
+      severity: 'error',
+      currentBranch: currentSymbolicBranch,
+      defaultBranch
+    }
+  }
+
+  return null
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/manifest-validity.ts

@@ -0,0 +1,81 @@
+/**
+ * doc-owners manifest validity checks (M1/M2/M3) plus the `# no-doc:` allow-list
+ * parser. Pure — file-existence is injected by the caller.
+ */
+
+import { DOC_OWNERS_PATH, globToRegex, isUrlPointer, parseDocOwners, pointerToPath } from './doc-owners'
+
+export type NoDocRule = { glob: string; reason: string }
+
+/**
+ * Parse `# no-doc: <glob> — <reason>` allow-list lines from doc-owners content.
+ * These lines exempt a surface from the completeness scoreboard.
+ */
+export function parseNoDocRules(content: string): NoDocRule[] {
+  const rules: NoDocRule[] = []
+  for (const line of content.split('\n')) {
+    const m = line.match(/^#\s+no-doc:\s+(\S+)(?:\s+[—–]\s+|\s+-\s+)(.+)$/)
+    if (m) rules.push({ glob: (m[1] ?? '').trim(), reason: (m[2] ?? '').trim() })
+  }
+  return rules
+}
+
+/**
+ * Validate the doc-owners manifest file (all bindings, not just fired ones).
+ * M1 (hard-fail): in-repo pointer does not exist on disk.
+ * M2 (advisory): glob fails to produce a valid regex (extremely unlikely with our simple grammar).
+ * M3 (hard-fail): same glob appears more than once.
+ */
+export function checkManifestValidity(
+  content: string | null,
+  fileExists: (p: string) => boolean
+): { m1Errors: string[]; m2Notes: string[]; m3Errors: string[]; noDocRules: NoDocRule[] } {
+  if (content === null) return { m1Errors: [], m2Notes: [], m3Errors: [], noDocRules: [] }
+
+  const { bindings, errors: parseErrors } = parseDocOwners(content)
+  const m1Errors: string[] = [...parseErrors]
+  const m2Notes: string[] = []
+  const m3Errors: string[] = []
+  const noDocRules = parseNoDocRules(content)
+
+  // M2: glob syntax (advisory — our grammar is permissive so failures are very rare)
+  for (const b of bindings) {
+    if (!b.glob) {
+      m2Notes.push(`M2 manifest-bad-glob: ${DOC_OWNERS_PATH}:${b.lineNum} — empty glob.`)
+      continue
+    }
+    try {
+      globToRegex(b.glob)
+    } catch (e) {
+      m2Notes.push(`M2 manifest-bad-glob: ${DOC_OWNERS_PATH}:${b.lineNum} — glob "${b.glob}" failed: ${e}`)
+    }
+  }
+
+  // M3: duplicate globs
+  const globLines = new Map<string, number[]>()
+  for (const b of bindings) {
+    const list = globLines.get(b.glob) ?? []
+    list.push(b.lineNum)
+    globLines.set(b.glob, list)
+  }
+  for (const [glob, lines] of globLines) {
+    if (lines.length > 1) {
+      m3Errors.push(
+        `M3 manifest-duplicate-glob: ${DOC_OWNERS_PATH} — glob "${glob}" appears ${lines.length} times (lines ${lines.join(', ')}).`
+      )
+    }
+  }
+
+  // M1: every in-repo pointer exists on disk (checks ALL bindings, not just fired ones)
+  for (const b of bindings) {
+    if (isUrlPointer(b.pointer)) continue
+    const pointerPath = pointerToPath(b.pointer)
+    if (!fileExists(pointerPath)) {
+      m1Errors.push(
+        `M1 manifest-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} — pointer ${b.pointer} does not exist on disk.`
+      )
+    }
+  }
+
+  return { m1Errors, m2Notes, m3Errors, noDocRules }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/markdown-table.ts

@@ -0,0 +1,76 @@
+/**
+ * Pure, no-I/O extraction of GitHub-flavored-markdown tables from raw text.
+ * The single, aeg-core-owned parser every doctrine consumer reads tables
+ * through — the Vinaya `/aeg` renderer, `registry-parse.ts`, and the
+ * DiagramModel derivation all sit on this one implementation, so no consumer
+ * can silently drift from the real file the moment a row's wording changes
+ * (one parser, N consumers).
+ */
+
+export type TableRow = {
+  /** Raw cell text per column, in header order. */
+  cells: string[]
+  /** 1-indexed line number of this row in the source file. */
+  line: number
+}
+
+export type ParsedTable = {
+  headers: string[]
+  rows: TableRow[]
+}
+
+function splitRow(line: string): string[] {
+  const trimmed = line.trim().replace(/^\|/, '').replace(/\|$/, '')
+  return trimmed.split('|').map((cell) => cell.trim())
+}
+
+const TABLE_ROW_PATTERN = /^\s*\|.*\|\s*$/
+const SEPARATOR_ROW_PATTERN = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/
+
+/**
+ * Finds the FIRST markdown table appearing at or after `fromLine` (1-indexed,
+ * inclusive) in `lines`. Returns null if none is found before the next `## `
+ * heading (or end of file) when `stopAtHeading` is true.
+ */
+export function findTable(lines: string[], fromLine: number, stopAtHeading = true): ParsedTable | null {
+  let i = fromLine - 1
+  while (i < lines.length) {
+    const line = lines[i] ?? ''
+    if (stopAtHeading && i > fromLine - 1 && /^##\s/.test(line)) return null
+    if (TABLE_ROW_PATTERN.test(line)) {
+      const headerLine = line
+      const sepLine = lines[i + 1] ?? ''
+      if (!SEPARATOR_ROW_PATTERN.test(sepLine)) {
+        i++
+        continue
+      }
+      const headers = splitRow(headerLine)
+      const rows: TableRow[] = []
+      let j = i + 2
+      while (j < lines.length && TABLE_ROW_PATTERN.test(lines[j] ?? '')) {
+        rows.push({ cells: splitRow(lines[j] ?? ''), line: j + 1 })
+        j++
+      }
+      return { headers, rows }
+    }
+    i++
+  }
+  return null
+}
+
+/** Finds the 1-indexed line of the first heading matching `pattern`, or null. */
+export function findHeadingLine(lines: string[], pattern: RegExp): number | null {
+  for (let i = 0; i < lines.length; i++) {
+    if (pattern.test(lines[i] ?? '')) return i + 1
+  }
+  return null
+}
+
+/** Convenience: row cells as a keyed object using `headers` as keys. */
+export function rowToRecord(headers: string[], row: TableRow): Record<string, string> {
+  const record: Record<string, string> = {}
+  headers.forEach((h, idx) => {
+    record[h] = row.cells[idx] ?? ''
+  })
+  return record
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/metering-io-guard.ts

@@ -0,0 +1,119 @@
+/**
+ * Hardened I/O for `MeteringCapabilityDeps` (CWE-59, `#313`). Every real
+ * caller of `resolveMeteringCapability` fills `exists`/`readFile` with the
+ * factory here rather than hand-rolling `existsSync`/`readFileSync`, so the
+ * guard lives once at the shared seam instead of being re-derived (or
+ * missed) at each call site.
+ *
+ * `claude-code-transcript.ts` stays pure (no `fs`, no `process.env`) — this
+ * sibling module is `aeg-core`'s one deliberate exception, exported
+ * alongside it rather than living in `bin/`: `apps/cli` only ever sees this
+ * package's `src/index.ts` surface, and `bin/` is not part of it (see that
+ * file's own header on the `bin/` vs `src/` split).
+ *
+ * The pointer path this guards (`$TMPDIR/claude-transcript-<key>.txt`) is
+ * fully predictable and, on the usual CI/Linux default with `TMPDIR` unset,
+ * sits in a directory other local users can typically write to. The write
+ * side of this exact path was hardened already
+ * (`apps/cli/src/lib/claude-stop-hook-emitter.ts`, CWE-59: `wx` +
+ * `renameSync`, refusing to write through a symlink). This is the read
+ * side's turn, against the same threat model.
+ *
+ * Mechanism: open with `O_NOFOLLOW | O_NONBLOCK`, then `fstat` the
+ * resulting descriptor — never a separate `lstat`-then-`open` pair, which
+ * still races between the two calls (a symlink or FIFO planted in the gap
+ * defeats the earlier check). `O_NOFOLLOW` makes the kernel refuse an open
+ * through a symlink outright (`ELOOP`) rather than trusting a stat taken a
+ * moment earlier. `O_NONBLOCK` is what actually closes the FIFO hang:
+ * opening a FIFO for reading in the default blocking mode waits for a
+ * writer that may never come — the reviewer's finding, 20+ seconds, killed
+ * by their own alarm rather than by the process. With `O_NONBLOCK` the open
+ * returns immediately regardless of whether a writer exists, and `fstat`'s
+ * `isFile()` then refuses the descriptor before any read is attempted, so
+ * the read call this guards never has a FIFO to block on in the first
+ * place. Neither flag changes behavior for a genuine regular file.
+ * Confirmed against a live planted symlink and a live FIFO, on both Node
+ * and Bun, before writing this comment.
+ */
+
+import { closeSync, constants as fsConstants, fstatSync, openSync, readFileSync } from 'node:fs'
+import type { MeteringCapabilityDeps } from './claude-code-transcript'
+
+const GUARD_OPEN_FLAGS = fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW
+
+/**
+ * The one property both `exists` and `readFile` require of an already-open
+ * descriptor before its content is trusted: a regular file (never a FIFO,
+ * device, directory, or — moot once `O_NOFOLLOW` has run — a symlink),
+ * owned by this process's own user on a platform that reports one at all.
+ *
+ * Split out from the `openSync`/`fstatSync` pair so the foreign-owner
+ * refusal — not constructible in CI without a second real local user — stays
+ * unit-testable by handing this function a faked stat directly, rather than
+ * needing an actual cross-user fixture.
+ */
+export function isTrustedMeteringStat(stat: { isFile(): boolean; uid: number }, ownUid: number | undefined): boolean {
+  if (!stat.isFile()) return false
+  if (typeof ownUid === 'number' && stat.uid !== ownUid) return false
+  return true
+}
+
+function ownUid(): number | undefined {
+  return typeof process.getuid === 'function' ? process.getuid() : undefined
+}
+
+function guardedOpen(path: string): number | undefined {
+  try {
+    return openSync(path, GUARD_OPEN_FLAGS)
+  } catch {
+    // Covers a missing path (`ENOENT`), a symlink (`ELOOP`, `O_NOFOLLOW`),
+    // and anything else the platform refuses to open under these flags —
+    // all degrade to "not usable", never a throw. An attacker must not be
+    // able to turn a probe into a crash either.
+    return undefined
+  }
+}
+
+function hardenedExists(path: string): boolean {
+  const fd = guardedOpen(path)
+  if (fd === undefined) return false
+  try {
+    return isTrustedMeteringStat(fstatSync(fd), ownUid())
+  } finally {
+    closeSync(fd)
+  }
+}
+
+function hardenedReadFile(path: string): string {
+  const fd = guardedOpen(path)
+  if (fd === undefined) {
+    throw new Error(`refusing to read ${path}: not openable as a plain, non-symlinked file`)
+  }
+  try {
+    if (!isTrustedMeteringStat(fstatSync(fd), ownUid())) {
+      throw new Error(`refusing to read ${path}: not a regular file owned by this user`)
+    }
+    // Reads the already-open, already-checked descriptor directly — never
+    // reopens by path, which would reintroduce the exact TOCTOU gap this
+    // module exists to close.
+    return readFileSync(fd, 'utf8')
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/**
+ * The hardened `MeteringCapabilityDeps` every real caller of
+ * `resolveMeteringCapability` should build from, in place of hand-rolled
+ * `existsSync`/`readFileSync`. `env`/`cwd` carry no I/O hazard of their own;
+ * every current call site reads them the same way, so this reads them
+ * directly rather than taking them as parameters no caller would vary.
+ */
+export function hardenedMeteringDeps(): MeteringCapabilityDeps {
+  return {
+    env: process.env,
+    cwd: process.cwd(),
+    exists: hardenedExists,
+    readFile: hardenedReadFile
+  }
+}