fix(cli): materialize the managed install before the onboarding service install (#12148)

## 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

cli/src/checks/service-health-check.ts

@@ -1,9 +1,12 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import type { PaperclipConfig } from "../config/schema.js";
 import { resolvePaperclipInstanceId } from "../config/home.js";
-import { readInstallManifest } from "../install-store.js";
+import { readInstallManifest, resolveInstallStorePaths } from "../install-store.js";
 import {
   detectServiceManager,
+  isExecutableFile,
+  resolveServiceShimPath,
   type ServiceManagerDetection,
 } from "../services/service-manager.js";
 import { buildLocalHealthUrl } from "../utils/health-url.js";
@@ -13,6 +16,7 @@ type HealthResult = { ok: boolean; version: string | null; error?: string };
 type ServiceCheckDependencies = {
   detect: (instanceId: string) => Promise<ServiceManagerDetection>;
   probe: (config: PaperclipConfig) => Promise<HealthResult>;
+  shimPresent: (executablePath: string) => Promise<boolean>;
 };
 
 async function probeHealth(config: PaperclipConfig): Promise<HealthResult> {
@@ -45,6 +49,7 @@ export async function serviceHealthChecks(
   const deps: ServiceCheckDependencies = {
     detect: (instanceId) => detectServiceManager({ instanceId }),
     probe: probeHealth,
+    shimPresent: (executablePath) => isExecutableFile(executablePath),
     ...dependencies,
   };
   const instanceId = resolvePaperclipInstanceId();
@@ -84,17 +89,36 @@ export async function serviceHealthChecks(
   );
 
   const health = await deps.probe(config);
+  // The installed definition is the truth about what the service executes;
+  // fall back to the environment-derived path only when it is unreadable.
+  const serviceExecutable = (await manager.installedExecutablePath()) ?? resolveServiceShimPath();
+  const shimPresent = status.active ? true : await deps.shimPresent(serviceExecutable);
   results.push(
     status.active
       ? { name: "Service runtime", status: "pass", message: `${status.serviceName} is active` }
-      : {
-          name: "Service runtime",
-          status: "fail",
-          message: health.ok
-            ? `${status.serviceName} is inactive but the configured port is serving another Paperclip process`
-            : `${status.serviceName} is ${status.detail ?? "inactive"}`,
-          repairHint: "Run `paperclipai service start`, or stop the conflicting foreground process first",
-        },
+      : !shimPresent
+        ? {
+            name: "Service runtime",
+            status: "fail",
+            message: `${status.serviceName} cannot start: no executable exists at ${serviceExecutable}`,
+            repairHint:
+              path.resolve(serviceExecutable) === path.resolve(resolveInstallStorePaths().shimPath)
+                ? "Run `paperclipai install` to restore the managed payload and shim, then `paperclipai service start`"
+                : `Restore the executable at ${serviceExecutable}, or unset PAPERCLIP_SHIM_PATH and run \`paperclipai install\` followed by \`paperclipai service install\` to re-point the service at the managed shim`,
+          }
+        : health.ok
+          ? {
+              name: "Service runtime",
+              status: "fail",
+              message: `${status.serviceName} is inactive but the configured port is serving another Paperclip process`,
+              repairHint: "Run `paperclipai service start`, or stop the conflicting foreground process first",
+            }
+          : {
+              name: "Service runtime",
+              status: "fail",
+              message: `${status.serviceName} is ${status.detail ?? "inactive"}`,
+              repairHint: "Run `paperclipai service start`; inspect `paperclipai service logs` if it does not stay up",
+            },
   );
 
   let expectedVersion: string | null = null;
@@ -116,11 +140,17 @@ export async function serviceHealthChecks(
             message: `Running ${health.version ?? "unknown"}; managed install is ${expectedVersion}`,
             repairHint: "Run `paperclipai service restart --expected-version " + expectedVersion + "`",
           }
-        : {
-            name: "Service health",
-            status: "pass",
-            message: `Healthy${health.version ? ` at version ${health.version}` : ""}`,
-          },
+        : status.active
+          ? {
+              name: "Service health",
+              status: "pass",
+              message: `Healthy${health.version ? ` at version ${health.version}` : ""}`,
+            }
+          : {
+              name: "Service health",
+              status: "warn",
+              message: `The configured port answers healthy${health.version ? ` (version ${health.version})` : ""}, but not from ${status.serviceName} — the service is inactive`,
+            },
   );
 
   if (status.enabled && status.linger === false) {