feat(setup): kontext setup / --uninstall for self-serve managed observe

[michiosw]

What & why

kontext setup / kontext setup --uninstall (ENG-442) — the self-serve install path that replaces pkg+MDM. Same managed-observe daemon, same Authorization: Bearer ingest as enterprise; only the provisioning differs (the user pastes a dashboard key instead of MDM injecting it). Builds on #276.

setup does, in order: darwin-only gate -> refuse if any KONTEXT_MANAGED_CONFIG is set or a system /Library config exists ("managed by your IT admin") -> validate the token via GET /ping (learns the org id; fails fast on a bad/revoked key) -> write the keychain item via /usr/bin/security -i stdin (never argv) and read it back through the daemon's own path so a write/read mismatch fails here, not silently under launchd -> write user managed.json (org id from ping) -> ensure installation identity -> merge ~/.claude/settings.json hooks -> install + bootstrap + kickstart the LaunchAgent -> probe the socket. --uninstall reverses it (bootout by plist path, remove hooks keeping foreign + Guard hooks, delete keychain item, remove managed.json) and keeps installation.json so re-running setup reuses the same device identity.

The token is validated raw (no trimming): leading/trailing whitespace or control chars fail loudly rather than being silently rewritten, so the stored credential is byte-identical to the dashboard's and can never smuggle a second line into the security -i stream.

How to review / test — without brew (no CLI release needed)

The logic is fully unit-tested behind seams (execCommand/readPassword/isTerminal/keychain/launchctl/systemConfigPath/goos are function vars), so you can verify the whole flow with no real keychain, launchctl, or network:

go test ./internal/setup/...    # ping httptest, refusal cases (env + MDM), full artifact
                                 # assertions, idempotent re-run, uninstall inverse + identity kept,
                                 # plist golden + XML escaping, token-shape rejection

To exercise the real daemon path against the local stack — build from the branch and run the binary directly (this is the brew-less equivalent of the published flow):

go build -o /tmp/kontext-review ./cmd/kontext     # do NOT use /tmp/kontext (collides with runtimehost)
KONTEXT_MANAGED_ALLOW_HTTP_LOCALHOST=1 /tmp/kontext-review setup \
  --cloud-url http://localhost:4000 --token <key minted in the dashboard>
# assert: keychain read-back ok, ~/.claude/settings.json hooks merged, LaunchAgent running,
# a batch lands in the dashboard with device label = ComputerName and version cli-<v>.
# Run it twice (idempotent), then: /tmp/kontext-review setup --uninstall  (clean; installation.json kept)

Note: a machine with an existing /Library managed.json will (correctly) refuse — move it aside to test the happy path.

Security notes for the reviewer

• Token never reaches argv/logs/plist; the security -i quoting is injection-safe for everything that passes the shape check.
• managed.json is 0600; settings.json writes preserve mode; the keychain delete loop purges only same-service items before writing exactly one.
• Refuses every env override and every MDM-managed Mac, so self-serve state can never shadow an org-managed install.

Part of the ENG-442 kontext-cli stack: #276 -> #277 -> #278.

[michiosw]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(selfserve): harden managed observe cli readiness #286
• feat(observe): surface revoked install tokens; doctor managed-observe section #278
• feat(setup): kontext setup / --uninstall for self-serve managed observe #277 👈 (View in Graphite)
• feat(selfserve): scope-aware config/identity paths, user settings merge, version fallback #276
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR adds a self-serve macOS setup and uninstall flow for managed observe. The main changes are:

• Adds the top-level kontext setup command and setup flags.
• Validates install tokens, stores them in the login keychain, and writes user managed config.
• Installs Claude Code hooks and a user LaunchAgent for the managed observe daemon.
• Adds uninstall cleanup for LaunchAgent, hooks, keychain token, and user managed config while keeping device identity.
• Adds daemon scope checking so a self-serve agent parks when a higher-priority managed config appears.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

_{Reviews (3): Last reviewed commit: "feat(setup): kontext setup / --uninstall..." | Re-trigger Greptile}

[michiosw]

@greptileai

[michiosw]

@greptileai