## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Interactive onboarding offers to install Paperclip as a background
service, defaulting to yes
> - The service definition targets the managed command shim, but an
ephemeral npx run never installs it, and the service step never checks
> - The result is a crash-looping service, a doctor hint about a
nonexistent port conflict, and a first run that ends with nothing
serving
> - This pull request materializes the managed install before
registering the service, or declines with the repair path
> - The benefit is that saying yes to the service prompt yields a
working service — or an honest explanation
## Linked Issues or Issue Description
**What happened?**
On a machine with no managed install, `npx paperclipai@2026.824.0
onboard` (interactive), accepting the background-service prompt,
produced: a LaunchAgent pointing at `~/.local/bin/paperclipai` (which
does not exist), launchd exit code 78 in a KeepAlive crash loop, doctor
reporting "inactive but the configured port is serving another Paperclip
process — stop the conflicting foreground process" (no such process
existed), and "Service health: fetch failed". Reproduced twice on a
clean field. `latest` has carried this path since v2026.817.0 shipped;
CI never sees it because `--yes` onboarding skips the service prompt.
**Expected behavior**
Accepting the service prompt installs a working service (materializing
the managed payload and shim first when needed), and doctor diagnoses a
missing service binary as exactly that.
**Steps to reproduce**
On macOS with no `~/.local/bin/paperclipai`: `npx paperclipai@latest
onboard`, accept the service prompt, then `launchctl print
gui/$UID/ing.paperclip.paperclipai` (exit code 78, spawn scheduled) and
`paperclipai doctor`.
**Paperclip version or commit**
`2026.824.0` (path present since #10045).
## What Changed
- `cli/src/onboard-service.ts`: after the user opts in, an
`ensureServiceShim` step checks the service shim path. Missing +
managed-store location → run `installCommand` pinned to the onboarding
version (payload, shim, PATH block), then proceed. Missing + custom
`PAPERCLIP_SHIM_PATH`, or install failure → decline with `paperclipai
install` / `paperclipai service install` guidance and install nothing.
- `cli/src/checks/service-health-check.ts`: the runtime check diagnoses
a missing service binary with the install repair hint (instead of the
port-conflict hint); an inactive service with a healthy responder gets a
`warn` attributing the foreign process instead of a plain "Healthy"
pass.
- Tests: new cases for shim materialization ordering,
decline-on-failure, missing-binary diagnosis, and foreign-responder
attribution; existing fixtures updated to inject the new dependencies.
## Verification
- `vitest run` on both touched suites: 15 pass.
- `tsc --noEmit` error count identical to the master baseline (16
pre-existing, all in `server/`, none in changed files).
- The live failure was reproduced on macOS before the fix (twice, clean
field) and the mechanism confirmed in source: `install()` writes the
definition and bootstraps launchd only; `install-store` was previously
reachable solely from the `install`/`update` commands.
## Risks
- Low: the new path runs only when the user opts into the service and
the shim is absent. The managed install resolves the pinned onboarding
version from the public registry; on failure the flow declines exactly
as it does on unsupported platforms. `--yes` quickstarts, Docker, and
managed installs are untouched.
## Model Used
Claude Fable 5 (Claude Code)
## Pre-submission checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
faad235aa2