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/__tests__/onboard-service.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { handleOnboardService } from "../onboard-service.js";
+import { handleOnboardService, isInstallableReleaseVersion } from "../onboard-service.js";
 
 function supportedDetection() {
   return {
@@ -24,6 +24,7 @@ function supportedDetection() {
         pid: 123,
       })),
       logs: vi.fn(async () => undefined),
+      installedExecutablePath: vi.fn(async () => null),
     },
   };
 }
@@ -48,7 +49,11 @@ describe("onboard service policy", () => {
 
     const installed = await handleOnboardService(
       { yes: true, installService: true },
-      { detect: vi.fn(async () => detection), isInteractive: () => false },
+      {
+        detect: vi.fn(async () => detection),
+        isInteractive: () => false,
+        ensureServiceShim: vi.fn(async () => ({ ok: true, installedNow: false })),
+      },
     );
 
     expect(installed).toBe(true);
@@ -61,7 +66,12 @@ describe("onboard service policy", () => {
 
     const installed = await handleOnboardService(
       {},
-      { detect: vi.fn(async () => detection), isInteractive: () => true, confirm },
+      {
+        detect: vi.fn(async () => detection),
+        isInteractive: () => true,
+        confirm,
+        ensureServiceShim: vi.fn(async () => ({ ok: true, installedNow: false })),
+      },
     );
 
     expect(confirm).toHaveBeenCalledOnce();
@@ -81,4 +91,50 @@ describe("onboard service policy", () => {
     expect(detect).not.toHaveBeenCalled();
     expect(info).not.toHaveBeenCalled();
   });
+
+  it("materializes the managed shim before installing the service", async () => {
+    const detection = supportedDetection();
+    const success = vi.fn();
+    const ensureServiceShim = vi.fn(async () => ({ ok: true, installedNow: true }));
+
+    const installed = await handleOnboardService(
+      { yes: true, installService: true },
+      { detect: vi.fn(async () => detection), isInteractive: () => false, ensureServiceShim, success },
+    );
+
+    expect(installed).toBe(true);
+    expect(ensureServiceShim).toHaveBeenCalledOnce();
+    expect(success).toHaveBeenCalledWith(expect.stringContaining("managed paperclipai payload"));
+    expect(detection.manager.install).toHaveBeenCalledWith({ startNow: true, startOnLogin: true });
+  });
+
+  it("declines instead of installing a service without a binary", async () => {
+    const detection = supportedDetection();
+    const warn = vi.fn();
+
+    const installed = await handleOnboardService(
+      { yes: true, installService: true },
+      {
+        detect: vi.fn(async () => detection),
+        isInteractive: () => false,
+        ensureServiceShim: vi.fn(async () => ({ ok: false, installedNow: false, reason: "npm exploded" })),
+        warn,
+      },
+    );
+
+    expect(installed).toBe(false);
+    expect(detection.manager.install).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("npm exploded"));
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("paperclipai install"));
+  });
+
+});
+
+describe("isInstallableReleaseVersion", () => {
+  it("accepts calendar releases and rejects placeholders", () => {
+    expect(isInstallableReleaseVersion("2026.824.1")).toBe(true);
+    expect(isInstallableReleaseVersion("2026.818.0-beta.1")).toBe(true);
+    expect(isInstallableReleaseVersion("0.3.1")).toBe(false);
+    expect(isInstallableReleaseVersion("not-a-version")).toBe(false);
+  });
 });

cli/src/__tests__/service-health-check.test.ts

@@ -3,6 +3,13 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { serviceHealthChecks } from "../checks/service-health-check.js";
+import {
+  extractExecutableFromLaunchdPlist,
+  extractExecutableFromSystemdUnit,
+  isExecutableFile,
+  renderLaunchdPlist,
+  renderSystemdUnit,
+} from "../services/service-manager.js";
 import { resolveRestartExpectedVersion, withHotRestartLock } from "../commands/service.js";
 import type { PaperclipConfig } from "../config/schema.js";
 import { buildLocalHealthUrl } from "../utils/health-url.js";
@@ -52,6 +59,7 @@ function managerFixture(active = true) {
       linger: true,
     })),
     logs: vi.fn(async () => undefined),
+    installedExecutablePath: vi.fn(async () => null),
   };
 }
 
@@ -129,6 +137,7 @@ describe("service health doctor checks", () => {
     const results = await serviceHealthChecks(config, {
       detect: vi.fn(async () => ({ supported: true as const, manager })),
       probe: vi.fn(async () => ({ ok: true, version: "1.2.3" })),
+      shimPresent: vi.fn(async () => true),
     });
 
     expect(results).toContainEqual(
@@ -140,3 +149,107 @@ describe("service health doctor checks", () => {
     );
   });
 });
+
+describe("isExecutableFile", () => {
+  it("accepts only executable regular files", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "shim-check-"));
+    const executable = path.join(dir, "exec");
+    const plain = path.join(dir, "plain");
+    fs.writeFileSync(executable, "#!/bin/sh\n", { mode: 0o755 });
+    fs.writeFileSync(plain, "data", { mode: 0o644 });
+
+    await expect(isExecutableFile(executable)).resolves.toBe(true);
+    await expect(isExecutableFile(plain)).resolves.toBe(false);
+    await expect(isExecutableFile(dir)).resolves.toBe(false);
+    await expect(isExecutableFile(path.join(dir, "missing"))).resolves.toBe(false);
+  });
+});
+
+describe("service runtime shim awareness", () => {
+  function inactiveManager() {
+    return {
+      platform: "launchd" as const,
+      instanceId: "default",
+      serviceName: "ing.paperclip.paperclipai",
+      definitionPath: "/tmp/nonexistent-definition.plist",
+      renderDefinition: () => "plist",
+      install: vi.fn(async () => ({ changed: false })),
+      uninstall: vi.fn(async () => undefined),
+      start: vi.fn(async () => undefined),
+      stop: vi.fn(async () => undefined),
+      restart: vi.fn(async () => undefined),
+      status: vi.fn(async () => ({
+        platform: "launchd" as const,
+        serviceName: "ing.paperclip.paperclipai",
+        installed: true,
+        active: false,
+        enabled: true,
+        pid: null,
+        detail: "loaded",
+      })),
+      logs: vi.fn(async () => undefined),
+      installedExecutablePath: vi.fn(async (): Promise<string | null> => null),
+    };
+  }
+
+  it("blames the missing binary, not a port conflict, when the shim is gone", async () => {
+    const results = await serviceHealthChecks({} as never, {
+      detect: vi.fn(async () => ({ supported: true as const, manager: inactiveManager() as never })),
+      probe: vi.fn(async () => ({ ok: false, version: null, error: "fetch failed" })),
+      shimPresent: vi.fn(async () => false),
+    });
+    const runtime = results.find((r) => r.name === "Service runtime");
+    expect(runtime?.status).toBe("fail");
+    expect(runtime?.message).toContain("no executable exists at");
+    expect(runtime?.repairHint).toContain("paperclipai install");
+  });
+
+  it("diagnoses against the executable recorded in the definition, not the current env", async () => {
+    const manager = inactiveManager();
+    manager.installedExecutablePath = vi.fn(async () => "/custom/bin/paperclipai");
+    const shimPresent = vi.fn(async () => false);
+    const results = await serviceHealthChecks({} as never, {
+      detect: vi.fn(async () => ({ supported: true as const, manager: manager as never })),
+      probe: vi.fn(async () => ({ ok: false, version: null, error: "fetch failed" })),
+      shimPresent,
+    });
+    const runtime = results.find((r) => r.name === "Service runtime");
+    expect(shimPresent).toHaveBeenCalledWith("/custom/bin/paperclipai");
+    expect(runtime?.message).toContain("/custom/bin/paperclipai");
+    expect(runtime?.repairHint).toContain("/custom/bin/paperclipai");
+    expect(runtime?.repairHint).toContain("unset PAPERCLIP_SHIM_PATH");
+    expect(runtime?.repairHint).toContain("`paperclipai install` followed by `paperclipai service install`");
+  });
+
+  it("attributes a healthy foreign responder instead of reporting Healthy", async () => {
+    const results = await serviceHealthChecks({} as never, {
+      detect: vi.fn(async () => ({ supported: true as const, manager: inactiveManager() as never })),
+      probe: vi.fn(async () => ({ ok: true, version: "9.9.9" })),
+      shimPresent: vi.fn(async () => true),
+    });
+    const healthResult = results.find((r) => r.name === "Service health");
+    expect(healthResult?.status).toBe("warn");
+    expect(healthResult?.message).toContain("but not from ing.paperclip.paperclipai");
+    const runtime = results.find((r) => r.name === "Service runtime");
+    expect(runtime?.message).toContain("serving another Paperclip process");
+  });
+});
+
+describe("definition executable extraction", () => {
+  it("round-trips through both renderers", () => {
+    const unit = renderSystemdUnit({ instanceId: "default", shimPath: "/custom/bin/paperclipai", homeDir: "/home/x/.paperclip" });
+    expect(extractExecutableFromSystemdUnit(unit)).toBe("/custom/bin/paperclipai");
+    const plist = renderLaunchdPlist({ instanceId: "default", shimPath: "/custom/bin/paperclipai", homeDir: "/home/x/.paperclip", stdoutPath: "/tmp/o.log", stderrPath: "/tmp/e.log" });
+    expect(extractExecutableFromLaunchdPlist(plist)).toBe("/custom/bin/paperclipai");
+    expect(extractExecutableFromSystemdUnit("garbage")).toBe(null);
+    expect(extractExecutableFromLaunchdPlist("garbage")).toBe(null);
+  });
+
+  it("round-trips paths the renderers escape", () => {
+    const hostile = '/tmp/we"ird $pa%th & <x>/paperclipai';
+    const unit = renderSystemdUnit({ instanceId: "default", shimPath: hostile, homeDir: "/home/x/.paperclip" });
+    expect(extractExecutableFromSystemdUnit(unit)).toBe(hostile);
+    const plist = renderLaunchdPlist({ instanceId: "default", shimPath: hostile, homeDir: "/home/x/.paperclip", stdoutPath: "/tmp/o.log", stderrPath: "/tmp/e.log" });
+    expect(extractExecutableFromLaunchdPlist(plist)).toBe(hostile);
+  });
+});