Skip to content

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

Merged
LoopGlitch26 merged 2 commits into
Cygnux-Labs:mainfrom
hayatexe:agent/issue-797
Nov 13, 2026
Merged

LoopGlitch26 merged 2 commits into
Cygnux-Labs:mainfrom
hayatexe:agent/issue-797

Conversation

@hayatexe

Copy link
Copy Markdown
Contributor

What and why

Fixes #797. When a Claude Code run's transcript tailer stops, the signer signs a tailer_lost gap whose reason says to run sudo /opt/tracekit/bin/python -I -m tracekit doctor to check the tailer, but doctor had no tailer check. v2_checks now runs four checks in system mode when client.json's hooks.agent is claude:

  • D-TAILER-CONFIG: client.json has a tailer key {user, uid, python}. If it doesn't, doctor warns that each session records a tailer_lost gap instead of its transcript; the fix is re-running init.
  • D-TAILER-USER: the key's user exists and has the key's uid.
  • D-TAILER-SUDO: /etc/sudoers.d/tracekit-tailer is a root-owned 0440 file (fail otherwise), and its rule names <python> -I -m tracekit.tailer (warn if missing or wrong).
  • D-TAILER-ACL: on Linux, getfacl shows the tailer's user can search the agent's home and ~/.claude and read ~/.claude/projects (named entry as the mask leaves it, else other). Without getfacl or on another platform it warns "not checked" and never passes.

The ids are listed in docs/doctor.md. Tests in tests/test_doctor_v2.py (Tailer) fake client.json, the sudoers file and getfacl output in a temp folder and need no root; each new check's test fails on main.

Open questions for review:

  • Severity: everything warns except a sudoers file that isn't root-owned 0440, which fails. Happy to change levels.
  • The ACL check ignores group ACL entries for now (marked lean:), and its getfacl parsing is tested against faked output only.

How I ran it as a user

I don't have a Linux machine with sudo tracekit init --v2, so there are no real tailer lines from a host yet. I ran doctor's tailer checks on a faked system client.json and printed them through doctor's report:

WARN  /…/client.json names no tailer: each Claude Code session records a tailer_lost gap instead of its transcript  (D-TAILER-CONFIG)
      fix: from a root-owned clone of the release (…), sudo /usr/bin/python3 -m tracekit init --v2 --user <agent-user>

pytest tests/test_doctor_v2.py tests/test_docs.py: 101 passed, 31 skipped (POSIX/root-only), 1 failed. The failure is test_docs.py::DocLinks::test_relative_links_resolve (links into examples/v2/demos/), which fails the same way on main on my Windows machine. pyflakes is clean on the changed files. I didn't run the full make check locally (Windows); relying on CI for the Linux run.

Checklist

  • make check passes (lint, tests, build); make test-ts too if sdk/typescript/ changed
  • a regression test covers the change
  • user-visible changes are described above (release notes are written at release time; don't edit CHANGELOG.md)
  • docs updated if behaviour or a security claim changed (docs/doctor.md; no threat-model change)
  • every commit is signed off (git commit -s, see CONTRIBUTING.md)

Security invariants

  • the agent still never holds a signing key or assigns sequence numbers
  • nothing an agent-controlled process supplies (isolation level, fail mode, gap/tamper records, approval identity) is newly trusted by the signer or verifier
  • gaps are still signed, never silent; a check that cannot run warns instead of passing
  • no verification code is shipped inside a bundle

Evidence format

  • this change does not touch the frozen formats

…s at (Cygnux-Labs#797)

A tailer_lost gap's signed reason says to run doctor to check the tailer, and
doctor had no tailer check. In v2 system mode with Claude Code, doctor now
checks client.json's tailer key (D-TAILER-CONFIG), the tailer's user and uid
(D-TAILER-USER), /etc/sudoers.d/tracekit-tailer (D-TAILER-SUDO) and, on Linux
with getfacl, the ACLs on the agent's home, ~/.claude and ~/.claude/projects
(D-TAILER-ACL; skipped with a warning elsewhere, never passed).

Signed-off-by: hayatexe <145812188+hayatexe@users.noreply.github.com>
Copilot AI lite review requested due to automatic review settings November 13, 2026 07:19

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@LoopGlitch26

Copy link
Copy Markdown
Member

I read this against install._tailer_acl, _tailer_sudo and the tailer key init writes, ran tests/test_doctor_v2.py and tests/test_docs.py, and ran doctor on a dev setup (no D-TAILER-* rows, as intended). The four checks match what init sets up, and each new test fails when its check is reverted. A few small things before merge:

  1. D-TAILER-SUDO (doctor.py:856) passes on a rule sudo wouldn't use. cmd in read_text(sudoers) is a substring match, so a commented-out line (# agent ALL=(tracekit-tailer) NOPASSWD: /opt/tracekit/bin/python -I -m tracekit.tailer) or a rule for another user or run-as user (bob ALL=(root) NOPASSWD: ...) reads as ok. Please compare whole lines with the one _tailer_sudo writes: f"{agent.pw_name} ALL=({user}) NOPASSWD: {python} -I -m tracekit.tailer", and fall back to the current check only when agent is None.
  2. The same line crashes doctor on a sudoers file that isn't UTF-8: read_text raises UnicodeDecodeError, a ValueError, and only OSError is caught. Catching ValueError there as well, as a warning, is enough.
  3. doctor.py:869: agent.pw_dir if agent else '~' is inside ... if agent else REINIT, so the '~' branch never runs. agent.pw_dir alone does the same.
  4. Two branches have no test: a getfacl that exits non-zero (doctor.py:882; the "projects missing" case still warns through the empty-output path), and the other:: fallback in _acl_perms (doctor.py:817), for example a home with mode 0755 and no named entry, which should pass. A subtest for each would cover them.
  5. Small one: the lean: note sits in _acl_perms's docstring (doctor.py:808). Elsewhere in doctor.py it's a # comment, which agent-flow debt lists.

If you'd rather not pick these up, say so and we'll finish them with your commits kept. Your CI runs need a maintainer approval first (it's your first PR here).

D-TAILER-SUDO matches the whole line install._tailer_sudo writes, so a
commented-out rule or one for another user or run-as user doesn't pass,
and a sudoers file that isn't UTF-8 warns instead of crashing doctor.
Tests for getfacl exiting non-zero and for the other:: fallback; the
lean: note moves to a comment; drop a dead '~' branch.

Signed-off-by: hayatexe <145812188+hayatexe@users.noreply.github.com>
@hayatexe

Copy link
Copy Markdown
Contributor Author

Thanks for the careful review! Picked all five up in 5ade16a:

  1. D-TAILER-SUDO now compares whole lines against the exact rule _tailer_sudo writes ({agent} ALL=({user}) NOPASSWD: {python} -I -m tracekit.tailer), falling back to the command substring only when there's no agent. New subtests: commented-out line, another user's rule, another run-as user.
  2. A non-UTF-8 sudoers file is caught as ValueError and warns; test added.
  3. Dropped the dead '~' branch.
  4. Added tests for getfacl exiting non-zero (detail shows getfacl exited 2) and for the other:: fallback (0755-style home with no named entry passes; other::--- warns).
  5. Moved the lean: note out of the docstring into a # comment.

pytest tests/test_doctor_v2.py -k Tailer: 10 passed, 13 subtests; the new sudo/UTF-8 cases fail with the doctor.py change reverted. pyflakes clean.

@LoopGlitch26

Copy link
Copy Markdown
Member

Checked 5ade16a. All five are in:

  • the exact _tailer_sudo line, with the substring check kept only when there's no agent;
  • a non-UTF-8 file warns instead of crashing;
  • the dead branch is gone;
  • the lean: note is a comment;
  • the two new subtests.

It merges once CI is green; the runs are being approved now.

@LoopGlitch26
LoopGlitch26 enabled auto-merge (squash) November 13, 2026 09:06
@LoopGlitch26
LoopGlitch26 merged commit d871cce into Cygnux-Labs:main Nov 13, 2026
34 checks passed
@LoopGlitch26

Copy link
Copy Markdown
Member

Merged, thank you. tracekit doctor now checks the transcript tailer that a signed tailer_lost points at, so the person reading that gap has somewhere to start. Our first outside field report this week (#815) had 121 of them, so this lands at the right time.

If you want a next one: #816 (a shorter "approve or skip?" for held calls, from that same report) and #811 (audit's help text still says Claude Code only) are both small and well scoped.

And if you use a coding agent day to day, running Tracekit on your own projects for a week and filing a field report would help us more than anything: https://github.com/Cygnux-Labs/Tracekit/issues/new?template=field-report.yml

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.

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

3 participants