Repository navigation
Description
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_lostgap 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
System mode: --no-hooks says what it does, and the tailer message nam…
init: v2 system init says when harness binding is off (#464) (#665)
LoopGlitch26 commentedon Nov 10, 2026
The last item, the macOS (launchd) form of the upgrade steps, is now its own issue: #701.
LoopGlitch26 commentedon Nov 10, 2026
One more item of the same kind: doctor's system-mode re-init hint (
REINIT,tracekit/doctor.py:48) has no--no-hooks, whileplugin/README.md:36tells 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-hookswhen the plugin's hooks are what's in place.System init: the clone route in init's refusals names v2 init (#464) (#…
LoopGlitch26 commentedon Nov 13, 2026
Status on main:
Done:
--no-hookshas 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); nosudo tracekithint is left intracekit/. 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_lostreason points at is #797.Still open here:
REINIThas no--no-hooksfor Claude Code plugin users (the comment above).docs/deploy-compose.md:9and:80usesudo tracekit deploy compose.Doctor's re-init fix keeps init --managed's hooks and init's agent (#464
Doctor's re-init fix keeps --no-hooks; deploy compose runs without tr…