mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-19 10:36:26 +02:00
f987f95d6a
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The `paperclipai` CLI can run Paperclip as a background service
(launchd on macOS, a systemd user unit on Linux), and that service
definition always launches the managed-install shim
> - #12148 made onboarding create the managed install first
(`ensureServiceShim()`), or refuse with a repair path, when the shim
does not exist
> - The standalone `paperclipai service install` command never got that
guard: it calls `manager.install()` directly, reports `installed: true`,
and leaves the supervisor crash-looping on a missing binary (for example
after a global npm install)
> - This pull request runs the same onboarding guard in `service
install` before any service definition is written
> - The benefit is that `service install` either produces a service that
can start, or fails with the same repair instructions onboarding gives,
and never reports success for a service that cannot run
## Linked Issues or Issue Description
- Fixes: #13841
- Refs #12148 (the onboarding-path fix this extends), #11755 and #11620
(related global-npm / service issues, not addressed here)
## What Changed
- `cli/src/onboard-service.ts`: moved the existing onboarding shim
guard, unchanged, into an exported `ensureServiceShim()` so both entry
points share it. It takes an optional `installIfMissing` flag that
defaults to `true`, so onboarding behaves exactly as before. When only
the shim is missing (a managed install is recorded and its current
payload is still present), the guard now runs the installer's existing
`smokePayload()` check (the payload must run and report its recorded
version), then rewrites the shim in place with the existing
`writeManagedShim()` instead of reinstalling. A payload that fails the
check gets no new shim; the command stops with the repair hint. The
recorded version and update channel stay unchanged, with no download and
no payload pruning. Otherwise the existing onboarding fallback
(reinstall the recorded git revision, or install this CLI's release
version) is unchanged.
- `cli/src/commands/service.ts`: `service install` now calls
`ensureServiceShim()` after the service manager is resolved and before
`manager.install()`. If the shim cannot be made available, the command
throws `Background service not installed: <reason>. Run \`paperclipai
install\`, then \`paperclipai service install\`.` (exit code 1) and
writes no service definition.
- With `--json`, the command only checks for the shim and does not start
a managed install. `installCommand()` prints progress to stdout, which
would corrupt the machine-readable result. JSON callers get a clean
non-zero exit with the repair hint; interactive callers get the same
behavior as onboarding (create the managed install, then the service).
The JSON output shape and all existing flags are unchanged.
- Docs: no change needed. `doc/INSTALLING.md` already says the service
uses the managed-install shim; this makes the command enforce that.
- Tests: a new command-level test (`service-install-command.test.ts`)
and one `ensureServiceShim` case in `onboard-service.test.ts`.
## Verification
- `pnpm exec vitest run
cli/src/__tests__/service-install-command.test.ts` on unmodified
`master` (efce9356): 3/3 tests fail (the guard is never called, and the
missing-shim command resolves instead of rejecting). With this change:
pass.
- `pnpm exec vitest run
cli/src/__tests__/service-install-command.test.ts
cli/src/__tests__/onboard-service.test.ts
cli/src/__tests__/service-health-check.test.ts`: 36/36 pass.
- The tests cover: the guard runs before `manager.install` (call order);
`--no-start-now` / `--no-start-on-login` are still forwarded;
`installed: true` JSON is printed only on success; a failed guard
rejects with the repair message, never calls `manager.install`, and
prints nothing; `--json` uses check-only mode; check-only mode never
calls `installCommand`; with a managed payload present, the repair
smoke-tests the payload, then restores the shim in place without calling
the installer, and rechecks the executable; a payload that fails the
smoke test gets no shim and no reinstall.
- `pnpm --filter paperclipai typecheck` and `pnpm --filter paperclipai
build`: pass.
- Repo-wide `pnpm -r typecheck` and `pnpm build` stop at the unchanged
`paperclip-runner` package because `cargo` is not installed locally.
They fail the same way on unmodified `master`, so CI is the authority
there.
- `pnpm test:run` locally: 32 server failures. 30 reproduce on
unmodified `master` (AI-connection/auth and worktree-provisioning
cases). The other 2 pass when run alone on both `master` and this
branch. None are in `cli/`.
- Manual check for reviewers: with no `~/.local/bin/paperclipai`,
`paperclipai service install --json` now exits 1 with the repair hint
and writes no LaunchAgent/unit. Without `--json`, it creates the managed
install first, then the service.
## Risks
- Low risk. Behavior changes only when the managed shim is missing,
which is exactly the case that used to produce a crash-looping service.
- Behavior shift: in that case, `service install --json` now fails
instead of reporting a service that cannot start. Scripts that relied on
the old false success will see exit code 1 and the repair instructions.
- Onboarding is unchanged. The guard body moved into a named function,
and onboarding calls it with the same defaults.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Implementation and tests: OpenAI Codex, model `gpt-6-astra` (agentic
coding with tool use and code execution; context window not reported by
the runtime).
- Plan critique before implementation: OpenAI `gpt-5.6-sol` at high
reasoning effort (read-only).
- Coordination, scoping and PR description: Anthropic Claude Opus 5.5
(`claude-opus-5-5`, 1M context, tool use).
- Independent code review of the exact head: Anthropic `claude-sonnet-5`
at medium effort (read-only), no findings.
- A human contributor directed the work and owns the change.
## 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
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com>