Skip to content

System mode: hints, messages and help text that don't match what init does #464

Closed

Description

@LoopGlitch26

Messages, hints and help text in system mode that don't match what init does or what's on the machine.

sudo tracekit ... hints fail after a venv-route or clone-route init

Nothing in tracekit/install.py puts a tracekit command on root's PATH, and /opt/tracekit/bin/tracekit doesn't
run (item 3). So after init from a venv or a clone, every sudo tracekit ... hint fails. (After a sudo pip install
into the system Python, pip's /usr/local/bin/tracekit works.) The hints:

  • tracekit/signer/service.py:1578, inside the signed tailer_lost gap reason
  • tracekit/autowire.py:403
  • tracekit/doctor.py:492, :553
  • tracekit/install.py:1101, 1269, 1278, 1288, 1309
  • 17 docs pages (grep -rlF "sudo tracekit" docs): coding-agents, compliance/README, concepts/custody,
    concepts/deployment, concepts/integrations, deploy-compose, doctor, egress, evaluation, guarantees, limits,
    portability, privacy, signing, support, threat-model-server, witnesses. docs/deploy.md and docs/quickstart-v2.md
    now use /opt/tracekit/bin/python -I -m tracekit.

Expected: one command form that works on every route. Either init installs a root-owned wrapper (for example
/usr/local/sbin/tracekit running /opt/tracekit/bin/python -I -m tracekit "$@"), or the hints and docs name
/opt/tracekit/bin/python -I -m tracekit.

sudo /usr/bin/python3 -m tracekit init hints fail under PEP 668

These hints tell the reader to run init from the system Python. On Debian 12 and Ubuntu 23.04+ that Python has no
Tracekit and refuses sudo pip install (PEP 668), so the command works only from inside a clone:

  • tracekit/doctor.py:35 (REINIT, used in many fixes)
  • tracekit/integrations/claude_code.py:508-510
  • tracekit/install.py:1104, 1111, 1192, 1202, 1281, 1283
  • tracekit/demo.py:220
  • docs/doctor.md:107, docs/limits.md:676
  • docs/walkthrough/terminal/06-demo-v1.txt:5, docs/walkthrough/terminal/11-claude-code.txt:28

install.py:1202 (the clone hint in _install_source, which v2 init also runs) leaves out --v2.

Expected: the hints point at the install steps in docs/deploy.md#laptop-system-mode (or give the /opt/tracekit
form where Tracekit is already installed), and install.py:1202 names --v2 when v2 init calls it.

The signed tailer_lost reason points at a doctor check that doesn't exist

When a watched run's tailer stops its heartbeats, the signer writes a tailer_lost gap whose reason ends "run sudo tracekit doctor to check the tailer" (tracekit/signer/service.py:1572-1579). Doctor has no tailer check
(grep -c tailer tracekit/doctor.py is 0). The reason is signed into the record, so it should be right. The command
form also fails after a venv or clone init (item 4).

Expected: add a doctor check for the tailer (its user, the ACL on the agent's transcripts, the sudo rule at
/etc/sudoers.d/tracekit-tailer, client.json's tailer key), or change the reason to name something that does
check it.

Init's tailer message overstates which runs get a tailer_lost gap

When the ACL or the sudo rule can't be set up, init prints "No tailer is set up, so each run of AGENT's sessions
records a tailer_lost gap instead of their tool uses and prompts" (tracekit/install.py:1479-1480). Only the Claude
Code hook records that gap (tracekit/integrations/claude_code.py:260-261); an SDK agent's runs (for example with
--no-hooks and tracekit.instrument()) record none.

Expected: for example, "each of AGENT's Claude Code sessions records a tailer_lost gap instead of its transcript".

--no-hooks has no help text

p.add_argument("--no-hooks", action="store_true") (tracekit/cli.py:109) shows in tracekit init --help with no
description. It is the documented way to set up system mode for an SDK agent or the Claude Code plugin
(docs/deploy.md, docs/limits.md:676, plugin/README.md).

Expected: a help line, for example "install no agent hooks (an SDK agent, or the Claude Code plugin's own hooks)".

v2 init leaves harness binding off without saying so

--harness defaults to none with --v2 (tracekit/cli.py:127-130), and init_system_v2 writes no
harness_binding and installs no helper then (tracekit/install.py:1459, :1336-1356, :1501). v1 init looks for the
agent's CLI on PATH and prints a note when binding is off (harness_config, install.py:775-791); v2 init prints
nothing, and doctor checks the helper only when signer.yaml has harness_binding (tracekit/doctor.py:574). Without
binding any process of the agent's user can start runs or write into the agent's runs; docs/limits.md:63 already
lists that limit.

Expected (the owner's call): init prints one line when it sets up v2 system mode without binding, saying what that
allows and naming --harness [NAME=]PATH; doctor could warn the same.

Upgrade steps for macOS system mode

docs/deploy.md's upgrade steps (Laptop system mode, "To upgrade") stop and restart the units with systemctl.
macOS system mode (experimental, --experimental-macos) runs under launchd: init boots out and bootstraps
/Library/LaunchDaemons/dev.tracekit.signer.plist (tracekit/install.py:1504-1508) and the helper's
dev.tracekit.harness-helper.plist (install.py:196-197).

Expected: the steps also give the launchd form, for example sudo launchctl bootout system/dev.tracekit.signer
before the upgrade (and the helper's label with --harness); init's own bootstrap starts them again.

Found while re-checking docs/deploy.md against the code (system mode, laptop and server). Each item can be fixed and tested on its own.

Activity

  1. LoopGlitch26 commented on Nov 10, 2026

    @LoopGlitch26
    MemberAuthor

    The last item, the macOS (launchd) form of the upgrade steps, is now its own issue: #701.

  2. LoopGlitch26 commented on Nov 10, 2026

    @LoopGlitch26
    MemberAuthor

    One more item of the same kind: doctor's system-mode re-init hint (REINIT, tracekit/doctor.py:48) has no --no-hooks, while plugin/README.md:36 tells plugin users to run system init with --no-hooks. System init doesn't detect the plugin, so following doctor's hint as a plugin user installs both sets of hooks (doctor then warns, D-HOOKS-PRESENT). The hint could add --no-hooks when the plugin's hooks are what's in place.

  3. LoopGlitch26 commented on Nov 13, 2026

    @LoopGlitch26
    MemberAuthor

    Status on main:

    Done: --no-hooks has a help line (tracekit/cli.py:316); init's tailer message names Claude Code sessions only (tracekit/install.py:1626-1627); v2 init says when harness binding is off (install.py:1715); the v2 code hints use doctor's re-init hint, which names a root-owned clone (REINIT, doctor.py:49-51); no sudo tracekit hint is left in tracekit/. The macOS upgrade steps are #701.

    Split out: the remaining PEP 668 hints (v1, and the docs) are #796; the doctor check that the signed tailer_lost reason points at is #797.

    Still open here:

    1. REINIT has no --no-hooks for Claude Code plugin users (the comment above).
    2. docs/deploy-compose.md:9 and :80 use sudo tracekit deploy compose.
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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions