Skip to content

Doctor: check the transcript tailer that the signed tailer_lost reason points at #797

Closed

Description

@LoopGlitch26

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_tailer on 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: setfacl on Linux, chmod +a on 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.tailer as the tailer's user and nothing else;
  • a tailer key 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 a tailer_lost gap 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:

  1. The client config has no tailer key: a warning that each session records a tailer_lost gap instead of its transcript, with re-running init as the fix (REINIT, tracekit/doctor.py:49).
  2. The key's user exists and has the key's uid.
  3. /etc/sudoers.d/tracekit-tailer exists, is owned by root with mode 0440, and its rule names the key's python and tracekit.tailer.
  4. The tailer's user can search the agent's home and ~/.claude and read ~/.claude/projects. On Linux, read the ACLs with getfacl. 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

  1. hayatexe commented on Nov 13, 2026

    @hayatexe
    Contributor

    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.

  2. LoopGlitch26 commented on Nov 13, 2026

    @LoopGlitch26
    MemberAuthor

    It's yours. A few things the review will look for:

    • each check id gets a row in docs/doctor.md;
    • each check has a test that fails without it;
    • the PR shows tracekit doctor output for one case that passes and one that warns, run on a real machine.

    Commits need a DCO sign-off (git commit -s).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions