# Ledger: a read-only T3 thread source for Table 2 (Gate F brief) Brief only, no code. Darkwing wrote it on 2026-09-26 at Sage's request, issue #1506. R1 (sha256 08959a05) went to Filbert, whose review asked for revisions: `agents/filbert/work/ledger-t3-source-review-2026-09-26.md`, sha256 19dda29a. This is R2. It takes every finding, and it records Sage's rulings on the three open questions. Section 1 has one measurement that differs from the review. ## Why Table 2 counts user messages per seat from `.pi/state//sessions/*.jsonl` only. Development seats now run in T3 on the Claude and Codex harnesses, so their prompts, Jason's included, never reach a Pi log. Today the Human column can't see T3 at all, and the zero it shows for T3 seats means "no source", not "no human prompts". 6a (ef0020ad) taught `messageKind` the T3 header, but no source the ledger reads contains one. Gate F (QUEUE row 6) passes when Filbert's item closes with zero human messages from Jason. While the ledger can't see T3, a zero there proves nothing. ## Where T3 keeps messages T3 keeps its state in one SQLite database, `~/.t3/userdata/state.sqlite`, in WAL mode (`state.sqlite-wal` and `state.sqlite-shm` sit beside it). The counts need three projection tables: - `projection_projects`: `project_id`, `workspace_root`, `deleted_at`. - `projection_threads`: `thread_id`, `project_id`, `title`, `archived_at`, `deleted_at`. - `projection_thread_messages`: `message_id` (primary key), `thread_id`, `role` (`user` or `assistant`), `text`, `created_at` (ISO UTC). The JSON diagnostic reads one more. In `orchestration_events`, each `thread.message-sent` event carries `metadata_json.origin`. Messages typed in the T3 app carry an `appVersion` there. Messages sent through T3's API or MCP tools, which is how seats talk to each other, don't. The same directory also holds `secrets/`, `clerk-tokens.json` and other settings files. The reader opens `state.sqlite` and nothing else, and it selects named columns only, never `*`. ## 1. Reading it, with T3 running or not The reader uses Node's built-in `node:sqlite` (`DatabaseSync`). That needs no dependency, and Node 26.8.1 (SQLite 3.53.4) prints no warning for it. - **URI.** Build it with `pathToFileURL(dbPath)` and set `mode=ro` through `searchParams`, then pass `readOnly: true`. A `?`, `#` or `%` in the home path would break a string-built URI. - **One snapshot.** Run every query, from the schema checks through the diagnostic, inside one `BEGIN` … `COMMIT`. In autocommit mode each statement sees its own snapshot while T3 writes between them. - **Busy timeout.** Set `DatabaseSync`'s `timeout` to 5 s. A transient `SQLITE_BUSY` during a T3 checkpoint then waits instead of failing. A busy error after the timeout exits 1 like any open failure. - **No `immutable=1` and no copy.** Both lose the WAL. Filbert found worse than lost messages: with a table created inside the WAL, `immutable=1` fails with `no such table`. What happens on disk. Filbert and I both tested these in scratch directories: | State | Directory writable | Result | |---|---|---| | T3 running, writer attached, newest rows only in `-wal` | yes | reads them | | `-wal` without `-shm` (writer killed, `-shm` removed) | yes | reads the WAL rows and creates `-shm` | | `-wal` without `-shm` | no | open fails, SQLite 14 | | T3 stopped cleanly, no `-wal` or `-shm` | yes | reads, then leaves an empty `-wal` and a 32 KiB `-shm` | | T3 stopped cleanly | no | fails, SQLite 1544 "attempt to write a readonly database" | In every case the main file's bytes stayed the same. The last row is where Filbert and I differ. His review says the stopped-case read works with the directory read-only. In my run it failed with and without the read transaction. The build's test settles it. Either way a failed open is exit 1. So the accurate claim: the reader never writes the main database file. Like any SQLite connection, it may create or update `-wal` and `-shm` beside it and takes read locks in `-shm`. T3 opens normally afterwards. ## 2. Jason or agent Reuse the 6a rule. The first line of `text` decides: a T3 header or the tmux preamble counts as agent, `control-board` as the sender counts as board, and anything else counts as human. Messages with role `user` count; assistant messages don't. The class fix rides in this build (Sage's ruling). HEAD's `packages/ledger/src/ledger.mjs:81` (tmux) and `:83` (T3) both allow only `class=[a-z-]+`. Both become case-insensitive. Seats send uppercase classes: Sage's DECISION, INFO, REVIEW-REQUEST and REVIEW-NOTE, and my own REVIEW-REQUEST. In this project's threads 16 real agent headers failed on that alone at 20:54Z. The ms-communications table lists lowercase names, so the fix follows what seats send, not the table. Cross-check, read at 2026-09-26T20:54Z for the mosaic-stack project (209 user messages outside imported and deleted threads, every one with its `thread.message-sent` event). Filbert's later read agreed, plus messages sent since. | T3 origin | Header matches 6a | Count | |---|---|---| | typed in the app (has `appVersion`) | no | 99 | | sent through the API (no `appVersion`) | yes | 80 | | sent through the API | no, uppercase class | 16 | | sent through the API | no, free-text roles | 14 | No message typed in the app carries a header, and every API message in this project carries one of the three forms. The 14 free-text ones are older Discord Bot thread headers such as `[from: SetSpark coordinator (…) -> to: Discord Bot (…)]`, written before the guide fixed the format. Sage ruled they stay as recorded: they count as human, dated 2026-09-17 to 2026-09-22. The header rule decides. The JSON also carries one diagnostic that feeds no table or total: user messages the rule calls human that T3 recorded as sent through the API. That number exposed the class bug and would catch the next format drift. `origin` is T3's internal metadata, not a documented contract, so it decides nothing. If `orchestration_events` or a column it needs is missing, the diagnostic reads `unknown` and the report goes on (Sage's ruling on F5). Missing tables the counts depend on still exit 1. ## 3. Thread to seat **Project.** A thread counts for this checkout only if its project's `workspace_root` equals the ledger's repository root, byte for byte. The CLI already takes that root from the realpath of its own URL, today `/mnt/storage/src/mosaic-stack`, project `34050c07`. So a T3 project opened through the compatibility symlink `~/src/mosaic-stack-dev-test` doesn't match, and "no project row" is the right refusal. The README says so. **Title rule.** Thread IDs change whenever Jason starts a new thread for a seat, so there's no fixed map. T3-AGENT-COMMS.md already names threads after the seat ("Darkwing", "Sage", "Dewey in Claude"). A thread belongs to seat `` when `` is a real directory under `agents/` and the lower-cased title equals `` or starts with `` followed by a space. So "Sagebrush" stays unmapped. Several threads can map to one seat, and their counts add up, as several Pi session files already do. Today that maps Sage, Darkwing, Filbert, Dewey and Rocko (one thread each, created 2026-09-26, titles set by hand), plus "Darkwing in Claude" (archived) and "Dewey in Claude". Researcher has a directory and no thread. Three threads map to no seat. Two are imported and excluded anyway ("FINDINGS.md review" and "[dragon-lin:darkwing -> …"). The third is "Discord Bot" with 68 user messages: 54 without a header, and the 14 free-text headers. Titles are current state, and T3 can write them itself. They go wrong three ways. T3 auto-titles an unnamed thread from Jason's first prompt, so "Rocko review of the plan" maps to rocko. A rename moves the whole history to another row. A seat thread titled for a topic drops into `t3:unmapped`. None of this changes the Human total or the human-per-closed ratio. It only moves counts between rows, but Gate F reads one seat's row. **Header cross-check.** The headers already say which seat a thread belongs to. For every user message whose header matches the fixed 6a rule and whose `to:` id equals the message's own `thread_id`: - in a mapped thread, the `to:` role, lower-cased, must equal that thread's seat; - in an unmapped thread, the `to:` role must not be a seat name. A conflict exits 1 and names the thread id, its title and both roles. A header whose `to:` id is some other thread is not checked. The check reads message text only, not T3 metadata. In a live read at 21:02Z every header agreed: all 104 addressed to their own thread carried the full thread id and named that thread's seat (Sage 40, Darkwing 15, Filbert 18, Dewey 15, Rocko 16). It catches a seat thread renamed to another seat or to a topic, once any agent writes to it. It also catches an auto-titled thread that agents address by a different seat. It misses a thread no agent ever writes to. Such a thread can only add human counts to a seat's row, never hide them, so for Gate F it errs toward a visible failure. The README says so. **Unmapped row.** Unmapped threads go in one Table 2 row, `t3:unmapped` (Sage's ruling), so their human messages still reach the Human column and the human-per-closed ratio. **Mapping in the JSON.** For each seat, the T3 thread ids and titles that made its row, and the unmapped thread ids and titles. Anyone checking a Gate F result can then see which threads the row came from. A seat's row sums its Pi and T3 counts, and the JSON splits them by source. Nothing is counted twice. Every T3 session today runs on `claudeAgent` or `codex`, which don't write `.pi/state`, and Filbert found no T3 header in any Pi log (6a record). **Excluded,** with the reason stated in the README: - Imported threads (`thread_id` starting `import:`, events marked `historyImport`). They are partial copies of Claude Code sessions, not T3 traffic: 55 user messages in two threads here. - Deleted threads (`deleted_at` set). Across all projects there are 3, with 3 messages. Archived threads count. - Threads in other T3 projects. Live, there is a project at `/home/jwoltje` and a deleted one at `/mnt/storage/src`. A thread in either could work on this repository and would not be counted. The workspace-root rule is still the right one, but the README names this blind spot. ## 4. What fails closed The source is on by default (Sage's ruling). `--no-t3` turns it off, and the report then says T3 was not read. `--t3-db ` reads another database file instead of `~/.t3/userdata/state.sqlite`. It exists for fixtures and gets the same checks. Each of these refuses the report with exit 1, the code the ledger already uses for unreadable session evidence. The report never falls back to Pi logs alone. Where the database is missing or won't open, the message names `--no-t3`. - The database is missing or unreadable, or won't open read-only. That includes a directory that isn't writable when SQLite needs to create `-shm`, and a busy error after the timeout. The Pi reader treats a missing `.pi` as no messages, and this departs from it on purpose. A missing Pi directory means no Pi seats ran here. A missing T3 database on this host means the path or T3 changed, and a silent zero is the failure Gate F exists to prevent. - `~/.t3`, `~/.t3/userdata` or `state.sqlite` is a symlink. With `--t3-db`, the file and its directory are checked. The Pi reader checks every ancestor too, but it skips symlinked entries. Skipping one named file would be another silent zero, so this reader refuses. - A table or column the counts need is missing. The reader checks `PRAGMA table_info` and names what's missing. This catches a T3 upgrade that changes the schema. - No project row, or more than one non-deleted row, for this repository root. - A counted row has a bad `role`, non-string `text`, or a `created_at` that doesn't parse. The Pi reader already refuses malformed JSONL and bad timestamps the same way. - A header conflicts with the title mapping (section 3). The reader never reads other files in `~/.t3`. It passes no message text beyond `messageKind`, `issueNumbers` and the header's `to:` role and id, the same rule as for Pi logs. ## 5. Rulings Sage ruled on the three questions R1 put to Jason, as lead calls: 1. The source is on by default. A missing or unreadable database exits 1, and the message names `--no-t3`. 2. Unmapped threads get the `t3:unmapped` row. 3. The 14 free-text headers stay as recorded. They show only in the JSON diagnostic. Sage also ruled that the class fix rides in this build, and that a missing diagnostic table reads `unknown` (F5). ## 6. Acceptance for the build **No test opens the real `~/.t3`.** Both places in `packages/ledger/tests/ledger.test.mjs` that spawn `cli.mjs` (the shared `run()` helper and the direct `spawnSync` at line 66) set `HOME` to the fixture's temp directory. A test that forgets `--t3-db` or `--no-t3` then finds no database and fails closed. The existing tests aren't about T3. Each gets an empty fixture database at the fixture `HOME`'s default path, with one project row for the fixture root. So they run with the source on, and their expected rows don't change. One test asserts that a `HOME` with no database exits 1 and names `--no-t3`. Fixture databases are built with `node:sqlite` in a temp directory, in WAL mode: - seat threads and an unmapped thread; imported, deleted and archived threads; a message outside the date range; - all three header forms, with uppercase classes in both the tmux preamble and the T3 header; - a thread with the same seat title in another project; - a seat thread renamed to another seat, with an agent header to its own id, which exits 1; - a "Sagebrush" title, which stays unmapped; - a thread titled "Researcher", which maps to the seat that has no thread live. WAL states, each with its own test: - The newest message is only in `-wal`, with the writer still attached (the live-T3 case). It is counted. - T3 stopped: the database closed cleanly with no writer. Counts are correct, and the main file's bytes are unchanged afterwards. - `-wal` without `-shm` in a writable directory: made by a child writer with `wal_autocheckpoint=0` that is SIGKILLed, then `-shm` deleted. The WAL rows are counted. - `-wal` without `-shm` in a directory that isn't writable: exit 1, naming `--no-t3`. Skipped when the tests run as root, where the mode bits don't bind. - The stopped case in a directory that isn't writable: exit 1, naming `--no-t3`, as I measured it. If the build reads there instead, the builder changes this test to assert correct counts and records the correction in the BUILD-LOG entry. Skipped as root too. Also: - Each other fail-closed case in section 4 has its own test, including a removed schema column and each symlink. - A missing `orchestration_events` gives `unknown` for the diagnostic and the same counts. - The class fix is proven against HEAD's `messageKind`. An uppercase class in either preamble counts as agent after the fix and as human before it. - The JSON lists each seat's threads and the unmapped threads. - A read against the live database gives the counts in this brief, allowing for messages sent since. It exits 0 with no header conflict. - The ledger README's counting rules name the new source, both flags, the mapping rule and the header check, and the exclusions. That includes the symlinked-checkout case and the other-project blind spot. - No suite runs the ledger tests, so the BUILD-LOG entry names the test file. ## Not in scope - Claude Code transcripts (`~/.claude/projects`) and Codex sessions (`~/.codex/sessions`). T3's database already holds every message T3 delivered, so those files would only duplicate it. - Any T3 API call, anything that needs T3 running, and any write beyond SQLite's own `-wal` and `-shm` handling. - Fixing the two tmux misclassifications Filbert found in 6a.