Skip to content

Claude Code: start a stopped transcript tailer again, park an idle one - #818

Merged
LoopGlitch26 merged 3 commits into
mainfrom
agent/fabricated-gaps
Nov 13, 2026
Merged

LoopGlitch26 merged 3 commits into
mainfrom
agent/fabricated-gaps

Conversation

@LoopGlitch26

@LoopGlitch26 LoopGlitch26 commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Most of the false reconcile.fabricated gaps from Claude Code come from the transcript tailer stopping while the run goes on. Calls made after that have a decide but no tool use in the record. The field report in #815 (7 days, 25,746 calls, 3,703 fabricated, 121 tailer_lost, Tracekit 1.5.3, desktop app, parallel sessions, Task sub-agents) matches what we measured on our own store on 11-08.

What was wrong (origin/main)

  1. A stopped tailer was never started again (about half of the 11-08 count). tracekit/integrations/claude_code.py:443 returns as soon as the session state says the run has a tailer. In dev mode nothing watches it either: the agent's token isn't granted tailer_heartbeat (tracekit/signer/service.py:445), so tracekit/tailer.py:285 stops sending heartbeats. A tailer that was killed, or failed before it could report, left no gap (docs/limits.md:93), and every later call of the run read as fabricated.
  2. The tailer gave up while the run was open (about 20k on 11-08). After IDLE_TAILER_S (2 h, tracekit/tailer.py:65) with no new line, or with no transcript yet, it sent tailer_lost and exited (tracekit/tailer.py:321, :323). A run stays open while an approval waits, and a session can sit quiet before its first prompt. Every call after that was fabricated.
  3. Workflow and sub-agent transcripts. _subagents (tracekit/tailer.py:211-218) and _seen (claude_code.py:426-434) match the real layout. I checked this on a machine with Claude Code 2.1.x transcripts, file names and structure only: 1,458 <session>/subagents/agent-*.jsonl, 223 <session>/subagents/workflows/wf_*/agent-*.jsonl, and 42 journal.jsonl files there that aren't transcripts. Nothing is nested deeper, and workflow agents' lines carry the parent session's id. The glob has been right since 1.5.1 (1.5.1: gap noise from Claude Code runs, DESK's NEEDS YOU and SPAN #471). On 1.5.x, workflow calls go unread when the tailer stops (cause 1 or 2), and workflows run long and in parallel, so they lose many calls. The restart test covers a sub-agent and a workflow transcript.

What this changes

  • The hook starts a stopped tailer again, after a signed gap. In dev mode the hook creates a per-run lock file, locks it and passes the open descriptor to the tailer, which holds it until it exits. Every hook event of the run tries the lock. If the lock is free and the tailer didn't end for good, the hook records tailer_lost ("stopped without a word … a new one reads on from where it stopped (restart n of at most 10)") and starts a new tailer. The kernel releases the lock when the process dies, so a SIGKILL is caught too. After 10 restarts in a run the gap says the tailer won't be started again (lean: RESTARTS).
  • A new tailer reads on from where the old one stopped. The hook starts each run's progress log with the run's start offsets. After each line it reports, the tailer appends [transcript, offset, sha256 of the bytes before]. A new tailer starts from those offsets, so nothing is read twice or skipped. A transcript the old tailer never reported from is read from its start. Before reading on, the new tailer checks the bytes already read against the digest, so a line edited while no tailer ran is still a signed tailer_lost. A tailer that ends for good (the run ended, SessionEnd, or a loss it reported) removes its lock and log, so no hook restarts it.
  • A tailer started at SessionEnd reads every transcript. When SessionEnd is the first event after a park or a kill, the new tailer's first wake is also its last. So it opens the main transcript before listing the sub-agents' transcripts. The hook starts no tailer for a run it already found ended, and in system mode it starts none for a lock file at all, since that file is in the agent's runtime dir.
  • An idle dev-mode tailer parks. After IDLE_TAILER_S with no new line, or with no transcript yet, a dev-mode tailer writes "parked" and exits with no gap. The run's next hook event starts it again from its offsets. A transcript that never appears by SessionEnd is still a tailer_lost.
  • System mode is unchanged. The signer watches its tailer through heartbeats, and the idle limit stays. It is the only thing that catches a decoy tailer that heartbeats but reads nothing.
  • Docs: docs/limits.md (the dev-mode row) and docs/coding-agents.md (the gap list).

Before and after

A scripted Claude Code-shaped run against a real dev signer process in a temp HOME. Hooks go through claude_code.handle with Claude Code's payloads, and each tailer runs in a thread of the script on the handle the hook wrote. There are three parallel sessions:

  • A has a main transcript, a Task sub-agent and a workflow agent, and its tailer is killed mid-run.

  • B goes quiet past the idle limit (scaled to 3 s), then continues.

  • C gets its first prompt only after the idle limit.

  • D's tailer is killed and SessionEnd is the next event. Meanwhile its sub-agent and workflow agent make 5 calls no hook decided. This runs against the signer's real 5 s grace window.

The run also has true gaps planted on purpose: in A, a tool use no hook decided and a decide that no transcript asks for, plus D's 5 calls. 91 hook-decided calls in total. Counts are from tracekit report --json.

origin/main this branch
reconcile.fabricated 45 (44 false + the planted one) 1 (the planted one)
reconcile.hook_missing 0 (all 6 planted ones went unseen: their tailers had stopped) 6 (the planted ones)
tailer_lost 3 (B's idle stop, C's and D's "never appeared") 2 (A's and D's kills)
tool uses recorded / recorded twice 35 / 0 97 / 0
decided calls with no tool use 57 1

How it was tested

  • New tests in tests/test_tailer.py. Each one failed on origin/main.
    • A killed tailer is started again after one signed gap. Calls made afterwards, in the main transcript, a sub-agent and a workflow agent, reconcile, and no model event is recorded twice.
    • A transcript the stopped tailer never reported from is read from its start.
    • A line edited while no tailer ran is a tailer_lost.
    • An idle tailer parks, and the next event starts it with no gap.
    • A transcript that appears after the idle limit is read.
    • The restart cap works.
    • With SessionEnd as the first event after a park or a kill, sub-agent and workflow lines are read, and an unhooked call is a hook_missing.
    • Restarts are counted through hook events up to the cap.
    • A lock that is removed between the hook's open and its lock is left alone.
    • SessionEnd copes with a file its tailer removed meanwhile.
    • System mode ignores a planted lock file.
    • An ended run gets no new tailer.
    • Each of these fails with its fix reverted.
    • A real child process holds the lock it was handed until SIGKILL.
    • Tailer files are kept with their session (_prune).
  • tests/test_tailer.py, test_reconcile.py, test_hook_v2.py, test_hook_invocation.py, test_contract_claude_code.py, test_harness_hooks_v2.py, test_agent_hooks.py, test_signer_completeness.py and test_docs.py: 547 passed. E11 (L1 tampering) gives the same result as before.
  • Full gate on macOS (make test-ts lint build test):
    • TypeScript: 152 passed, 0 failed.
    • Lint is clean and the build passed.
    • Python: 5,157 passed and 1 failed. The failure is test_audit.py::test_the_guard_line_names_the_calls_files_agent (gptme), which fails the same way on origin/main 5dd9eba without this change.
  • Not checked locally: the tailer as a separate process running this branch's code. python -I imports the main checkout through the editable install, so the restart test runs the tailer in process and the lock test uses a real child process. CI, on one checkout, runs the hook tests with real tailer processes.

Not in this PR

  • hook_missing for tools Claude Code runs without a PreToolUse (our 11-08 list: Agent, Artifact, ToolSearch, WebFetch, Skill, TaskStop, SendUserFile). That list needs checking against Claude Code 2.1.x before reconcile labels any call "unhooked". Field report: Claude Code, 7 days on macOS #815 has 42 of these.
  • hook_missing and fabricated pairs when a call is decided in one run of a session and read in another. Fixing that means reconciling across a session's runs in the signer.
  • A session opened and closed with no prompt still gets "the transcript never appeared".

Refs #815

In dev mode nothing watched the transcript tailer: once it was killed, or
failed before it could report, no hook started another, and every later
call of the run read as reconcile.fabricated. It also gave up after two
hours with no new line, or with no transcript yet, while the run was open.

- The hook hands each run's tailer a lock it holds for its life. Each hook
  event of the run checks it; when it is free, the hook records a signed
  tailer_lost and starts a new tailer where the stopped one got (at most
  10 times a run).
- The tailer appends [transcript, offset, digest] to a progress log after
  each line it reports, after the hook's first line of start offsets. A new
  tailer reads on from there, so no line is read twice or skipped, and it
  checks the bytes already read against the digests: an edit made while no
  tailer ran is still a tailer_lost.
- A dev-mode tailer quiet for IDLE_TAILER_S parks with no gap, and the run's
  next event starts it again. System mode keeps its idle limit.

Refs #815

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
Review fixes for the stopped-tailer restart:

- A tailer started at SessionEnd (the first event after it parked or was
  killed) had its first wake as its last, and listed the sub-agents'
  transcripts only once the main one was open: it read the main one alone.
  It now opens the main one before listing them.
- The hook starts no tailer for a lock file in system mode, where the
  runtime dir is the agent's, and none for a run it found ended.
- SessionEnd's cleanup takes a file the tailer removed meanwhile.
- Tests: restarts counted through hook events up to the cap, and a lock
  removed between the hook's open and its lock.
- docs/limits.md: the agent's user can also write the progress log, and a
  missing log reads on from where the hook last saw the transcripts.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
@LoopGlitch26
LoopGlitch26 enabled auto-merge (squash) November 13, 2026 13:31
@LoopGlitch26
LoopGlitch26 merged commit cd9a2a0 into main Nov 13, 2026
32 of 34 checks passed
@LoopGlitch26
LoopGlitch26 deleted the agent/fabricated-gaps branch November 13, 2026 15:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant