# Transcript usage source

REQ-LIMIT-4, interface version 1. Enable with
`"plugins": { "usage-source": ["transcript"] }` in the organization file,
keeping its other plug-in kinds. Human changes use `mosaic plugins set` and
the current revision. No agent edits the live organization file.

`readTurn({ harness, root })` returns `{status:'known', entries}` or
`{status:'unknown', code}`. Entries map assistant message identities to
`{input, output, cacheWrite, cacheRead}`. This is a snapshot; the bus stores a
baseline and computes the turn's new entries. No known new entry means unknown,
not zero. The bus attributes records to the bound run/instance/provider/model;
the account is null. No token limit or enforcement ships here.

For Pi, root is the run's session directory, or a resumed thread's persistent
session directory. JSONL `message` entries with `message.role === 'assistant'`
have `id` and `message.usage` input/output/cacheWrite/cacheRead counters.
For Claude Code, root is `home/.claude/projects`, or the thread's persistent
`claude-projects` directory: one project-directory level, then session JSONL
files. Assistant entries have message.id and message.usage input_tokens,
output_tokens, cache_creation_input_tokens and cache_read_input_tokens. Claude's
absent optional cache fields mean no reported cache usage; missing required
input/output is unknown. Duplicate identical identities count once; conflicting
counters refuse the snapshot.

The source follows no user symlink: root components and project directories
are opened with directory descriptors and O_NOFOLLOW; final opens add
O_NONBLOCK. Files must be regular and single-link. Both fstat size and bytes
actually read are bounded, and edits during a read refuse the snapshot. Limits:
8 MiB total bytes, 1 MiB per line, 512 directory entries and 20,000 JSON records
per snapshot. These are parser resource bounds, not policy token ceilings.
Invalid UTF-8, malformed/cut JSONL or invalid counters return unknown, never
zero. Reads/logs return no transcript text or parser exception text.

A session can edit its own transcript. Counts are the stack's best reading,
not proof. Resumed history present before a run's next turn is excluded by its
baseline. Rewriting that baseline makes the turn unknown. Missing data or a
source disabled/failed at a restart leaves its pending turn visibly unknown.