stack/agents/darkwing/work/ledger-t3-source/r2.md

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/<seat>/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 <s> when <s> is a real directory under agents/ and the lower-cased title equals <s> or starts with <s> 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 <path> 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.