Repository navigation
Description
When a watched Claude Code run's transcript tailer stops, the signer signs a tailer_lost gap. Its reason ends "run sudo /opt/tracekit/bin/python -I -m tracekit doctor to check the tailer" (tracekit/signer/service.py:1745-1747). Doctor has no tailer check: tracekit/doctor.py doesn't mention the tailer. The reason is signed into the record, so the check it points at should exist.
What v2 system init sets up for the tailer (tracekit/install.py); the user for every agent, the rest for Claude Code only (lines 1622-1624, 1713):
- a system user for it:
tracekit-tailer, or_tracekit_taileron macOS (V2_TAILER,V2_TAILER_DARWIN, line 109); - read access for that user to the agent's
~/.claude/projects, and search on the folders above it (_tailer_acl, line 1482:setfaclon Linux,chmod +aon macOS); - a sudoers rule,
/etc/sudoers.d/tracekit-tailer(TAILER_SUDOERS, line 110;_tailer_sudo, line 1515), written 0440 and owned by root (line 1521), that lets the agent's user start<OPT_PYTHON> -I -m tracekit.taileras the tailer's user and nothing else; - a
tailerkey in the root-owned client config,{"user", "uid", "python"}, written only when the ACL and the sudo rule were both set up (lines 1712-1713). Without it, the hook has the signer record atailer_lostgap for each run instead (the comment at line 1707).
This is the tailer_lost item of #464, split out.
Task
Add tailer checks to doctor's v2 system-mode checks (v2_checks, tracekit/doctor.py:806). Its client_json argument is the system client config's path (client.SYSTEM_CONFIG, doctor.py:114), so read it with read_json as doctor.py:1164 does. Its agent argument is a pwd entry, not the agent's name: take the name from the config's hooks.agent, and run the checks when it is claude:
- The client config has no
tailerkey: a warning that each session records atailer_lostgap instead of its transcript, with re-running init as the fix (REINIT,tracekit/doctor.py:49). - The key's user exists and has the key's uid.
/etc/sudoers.d/tracekit-tailerexists, is owned by root with mode 0440, and its rule names the key'spythonandtracekit.tailer.- The tailer's user can search the agent's home and
~/.claudeand read~/.claude/projects. On Linux, read the ACLs withgetfacl. Where the tool is missing or the platform is another, report that the check was skipped; don't pass it.
Give each result a D-TAILER-… id, and list the ids in docs/doctor.md's table (rows like D-HOOKS-VENV's at line 57).
Tests go in tests/test_doctor_v2.py, with the client config and the files faked in a temp folder; no root needed. Each new check needs a test that fails on main.
Done when: doctor names each missing or wrong piece with a fix, and passes on a correct setup; docs/doctor.md lists the checks; pytest tests/test_doctor_v2.py tests/test_docs.py passes. If you have a Linux machine, run sudo tracekit init --v2 there and paste doctor's tailer lines in the PR.
Comment here to claim it. Commits need a DCO sign-off (git commit -s).
Activity
hayatexe commentedon Nov 13, 2026
I'd like to claim this one. I have the four doctor checks (D-TAILER-CONFIG / USER / SUDO / ACL) with tests ready and will open a PR shortly.
LoopGlitch26 commentedon Nov 13, 2026
It's yours. A few things the review will look for:
docs/doctor.md;tracekit doctoroutput for one case that passes and one that warns, run on a real machine.Commits need a DCO sign-off (
git commit -s).doctor: tailer review fixes (Cygnux-Labs#797)
Doctor: check the transcript tailer that the signed tailer_lost reaso…