Skip to content

System mode (v1): init hints name the system Python without the clone, which fails under PEP 668 #796

Closed

Description

@LoopGlitch26

Debian 12 and Ubuntu 23.04+ refuse sudo pip install into the system Python (PEP 668), so sudo /usr/bin/python3 -m tracekit init works only from inside a clone of the release. Doctor's v2 re-init hint says so: it starts with "from a root-owned clone of the release (docs/deploy.md#laptop-system-mode)" (REINIT, tracekit/doctor.py:49-51).

Four v1 system-mode hints still give the bare command, sudo /usr/bin/python3 -m tracekit init --user <agent-user>:

  • tracekit/install.py:1207: migrate --system when there is no system-mode signer;
  • tracekit/install.py:1397 and :1400: the fixes of the D-SYSTEM-CONFIG results in v1_results;
  • tracekit/install.py:1402: reinstall, the fix for the signer python, venv config, runtime and unit file checks.

tracekit/install.py:1214, in the same migrate_system as line 1207, already adds "from a root-owned clone". The docs give the bare command too: docs/signing.md:10 (the System row), docs/doctor.md:111 (the fix for these checks), and the terminal recordings docs/walkthrough/terminal/06-demo-v1.txt:5 and docs/walkthrough/terminal/11-claude-code.txt:31 (the v2 form there, with --v2).

This is the PEP 668 item of #464, split out. The code hints for v2 that item listed now use REINIT; the rest are listed here.

Task

  1. In tracekit/install.py, write the v1 hint once, worded like REINIT: "from a root-owned clone of the release (), sudo /usr/bin/python3 -m tracekit init --user ", with the link from wiki_url('docs/deploy.md', 'laptop-system-mode') (install.py imports wiki_url at line 32). Use it at lines 1207, 1397, 1400 and 1402.
  2. In docs/signing.md:10 and docs/doctor.md:111, say the command runs from a root-owned clone of the release, linking deploy.md#laptop-system-mode. In the two terminal recordings, show the hint as the code prints it now.
  3. Add a test to tests/test_system_install.py, class Doctor, next to test_fails_without_a_system_install (line 480): with client.system_config returning None, the D-SYSTEM-CONFIG fix line names the root-owned clone. It must fail on main.

Done when: the four hints, the two docs lines and the two recordings name the clone route, and pytest tests/test_system_install.py tests/test_docs.py passes.

Comment here to claim it. Commits need a DCO sign-off (git commit -s).

Activity

  1. FTFaruque commented on Nov 13, 2026

    @FTFaruque
    Contributor

    Hi, I'd like to take this one.

    My Plan:

    • One v1 hint in tracekit/install.py, worded like doctor's REINIT and linking wiki_url('docs/deploy.md', 'laptop-system-mode'), used at lines 1207, 1397, 1400 and 1402
    • Docs: docs/signing.md:10 and docs/doctor.md:111 say the command runs from a root-owned clone of the release, linking deploy.md#laptop-system-mode
    • Recordings: 06-demo-v1.txt:5 and 11-claude-code.txt:31 show the hint as the code prints it now
    • Test: in tests/test_system_install.py (Doctor), with client.system_config returning None, the D-SYSTEM-CONFIG fix line names the root-owned clone; it fails on main
  2. LoopGlitch26 commented on Nov 13, 2026

    @LoopGlitch26
    MemberAuthor

    It's yours; the plan covers it. For the two recordings, re-record them with the script that made them (or edit only the hint line, and say which in the PR), so they still match what the code prints. 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