Skip to content

docs: add macOS system-mode upgrade steps - #703

Merged
LoopGlitch26 merged 2 commits into
Cygnux-Labs:mainfrom
Siri-Durugapu:fix/macos-system-mode-upgrade-docs
Nov 10, 2026
Merged

LoopGlitch26 merged 2 commits into
Cygnux-Labs:mainfrom
Siri-Durugapu:fix/macos-system-mode-upgrade-docs

Conversation

@Siri-Durugapu

Copy link
Copy Markdown
Contributor

What and why

This updates the system-mode upgrade instructions to include the macOS launchd commands alongside the existing Linux systemd commands.

Previously, the upgrade instructions documented only Linux service-management commands, leaving macOS users without the corresponding steps to stop and restart the signer and stop the harness helper when --harness is enabled.

This change:

  • Documents the macOS command to stop the signer using launchctl bootout.
  • Includes the macOS harness-helper shutdown command when --harness is enabled.
  • Clarifies that rerunning init bootstraps the signer and harness helper again on macOS, so no separate launchd start command is needed at that stage.
  • Documents the macOS command to restart the signer using launchctl kickstart.
  • Adds a regression test that checks the documented signer commands against install.V2_LABEL, ensuring the documentation stays aligned with the configured signer label.

How I ran it as a user

This is a documentation-only change. I verified the documented macOS commands against the install configuration and ran the documentation test suite.

Regression test:

python -m pytest .\tests\test_docs.py -k system_mode_upgrade_docs_include_macos_signer_label -q

Output:

1 passed, 8 deselected

The regression test was also run against the original documentation before the documentation change. It failed because the macOS signer stop command was missing.

Full documentation test suite:

python -m pytest .\tests\test_docs.py -q

Output:

9 passed, 12 subtests passed

The macOS launchctl commands were verified against the configured install labels; the commands were not executed on a macOS host.

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/threat-model-laptop.md, docs/threat-model-server.md) — not applicable; no runtime behaviour or security claims changed
  • 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: v1 (core.sig_message, ledger.make_record, the v1 schema, how the verifier treats existing bundles) or the published v2 format
  • or, if it does: the issue explicitly asks for it, existing bundles (including docs/sample/ and tests/fixtures/) still verify, and the change is called out above

Signed-off-by: Siri-Durugapu <siridurugapu29@gmail.com>

@LoopGlitch26 LoopGlitch26 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks. The commands match what init does: the labels are install.V2_LABEL and install.HELPER_LABEL, and init's own bootout and bootstrap (tracekit/install.py:1636-1641 and :201-211) make step 3 right as written. Three small things:

  1. Please assert the helper's label too, since step 1 names it: self.assertIn(f"sudo launchctl bootout system/{install.HELPER_LABEL}", upgrade). Then the docs also follow that label if it changes.
  2. The rest of that list wraps at about 118 columns; please wrap steps 1, 3 and 4 the same way.
  3. Drop the blank line you added after class DocCommands(unittest.TestCase):; the other classes in the file start their first method straight after the class line.

I approved the CI runs.

Signed-off-by: Siri-Durugapu <siridurugapu29@gmail.com>
@Siri-Durugapu

Copy link
Copy Markdown
Contributor Author

Thanks for the review! I've addressed all three suggestions:

  1. Added an assertion for install.HELPER_LABEL.
  2. Wrapped steps 1, 3 and 4 for consistent formatting.
  3. Removed the extra blank line after the DocCommands class declaration.

The focused regression test, full documentation test suite, and pyflakes lint all pass. I've pushed the updates to PR #703.

Thanks for the feedback!

@LoopGlitch26
LoopGlitch26 merged commit 0abe551 into Cygnux-Labs:main Nov 10, 2026
34 checks passed
@LoopGlitch26

Copy link
Copy Markdown
Member

Merged, thanks. The system-mode upgrade steps now give the macOS launchd commands next to the systemd ones, and a test keeps them on init's labels. It ships in the next release.

If you'd like another one nearby: #464 lists more system-mode hints and help text that don't match what init does, and each item can be fixed on its own.

A request: if you use a coding agent (Claude Code, Codex, Cursor, Gemini CLI or OpenCode), would you run Tracekit on it for a week, on your own projects?

pip install -U tracekit-ai
tracekit audit --since 7d   # read-only: what it would have held last week
tracekit init --dev --v2    # then record and guard from now on

After a week, tracekit report --share prints counts only (no commands, paths or content). Post it in #385; that's all we need.

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.

2 participants