Skip to content

The open-source app everyone uses to manage agents at work

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

Devin Foleyfaad235aa212
diff --git a/cli/src/__tests__/onboard-service.test.ts b/cli/src/__tests__/onboard-service.test.ts
index c4a711f3f3..5b3f406433 100644
--- a/cli/src/__tests__/onboard-service.test.ts
+++ b/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);
+ });
});
diff --git a/cli/src/__tests__/service-health-check.test.ts b/cli/src/__tests__/service-health-check.test.ts
index d913b2771d..cb4eb298e3 100644
--- a/cli/src/__tests__/service-health-check.test.ts
+++ b/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);
+ });
+});
diff --git a/cli/src/checks/service-health-check.ts b/cli/src/checks/service-health-check.ts
index 27f3a3a3ad..5a4aadd6db 100644
--- a/cli/src/checks/service-health-check.ts
+++ b/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) {
diff --git a/cli/src/onboard-service.ts b/cli/src/onboard-service.ts
index 50cc8e052f..268f121e51 100644
--- a/cli/src/onboard-service.ts
+++ b/cli/src/onboard-service.ts
@@ -1,18 +1,38 @@
+import path from "node:path";
import * as p from "@clack/prompts";
import pc from "picocolors";
+import { installCommand } from "./commands/install.js";
import { resolvePaperclipInstanceId } from "./config/home.js";
+import {
+ readInstallManifest,
+ resolveInstallStorePaths,
+ type InstallManifest,
+} from "./install-store.js";
import {
detectServiceManager,
+ isExecutableFile,
+ resolveServiceShimPath,
type ServiceManagerDetection,
} from "./services/service-manager.js";
+import { packageVersion } from "./version.js";
export type OnboardServiceOptions = {
yes?: boolean;
installService?: boolean;
};
+type EnsureShimResult = { ok: boolean; installedNow: boolean; reason?: string };
+
+// Source checkouts carry the repository placeholder version; installing
+// that as an npm spec would fetch an ancient release (or nothing) instead
+// of the running code. Only real calendar versions are installable.
+export function isInstallableReleaseVersion(version: string): boolean {
+ return /^\d{4}\.\d{1,4}\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version);
+}
+
type OnboardServiceDependencies = {
detect: (instanceId: string) => Promise<ServiceManagerDetection>;
+ ensureServiceShim: () => Promise<EnsureShimResult>;
confirm: () => Promise<boolean>;
confirmLinger: () => Promise<boolean>;
isInteractive: () => boolean;
@@ -23,6 +43,60 @@ type OnboardServiceDependencies = {
const defaultDependencies: OnboardServiceDependencies = {
detect: (instanceId) => detectServiceManager({ instanceId }),
+ // The service definition targets the managed shim. An ephemeral run (npx)
+ // never lays it down, so installing the service without this step creates
+ // a definition that crash-loops on a missing binary.
+ ensureServiceShim: async () => {
+ const shimPath = resolveServiceShimPath();
+ if (await isExecutableFile(shimPath)) {
+ return { ok: true, installedNow: false };
+ }
+ const storeShimPath = resolveInstallStorePaths().shimPath;
+ if (path.resolve(shimPath) !== path.resolve(storeShimPath)) {
+ return {
+ ok: false,
+ installedNow: false,
+ reason: `no executable exists at ${shimPath} (PAPERCLIP_SHIM_PATH), and it is outside the managed install store`,
+ };
+ }
+ let manifest: InstallManifest | null = null;
+ try {
+ manifest = readInstallManifest();
+ } catch {}
+ try {
+ if (manifest?.source === "git" && manifest.repo) {
+ // A managed git payload must be preserved as-is: reinstall the
+ // exact revision the manifest records, not an npm release.
+ await installCommand({ repo: manifest.repo, ref: manifest.sha ?? manifest.ref, yes: true });
+ } else if (isInstallableReleaseVersion(packageVersion)) {
+ // packageVersion, not cliVersion: a managed executable's cliVersion
+ // carries provenance text that is not an installable npm spec.
+ await installCommand({ version: packageVersion, yes: true });
+ } else {
+ return {
+ ok: false,
+ installedNow: false,
+ reason:
+ `this build reports version ${packageVersion}, which is not an installable release; ` +
+ "run `paperclipai install` (or `paperclipai install --repo <repo> --ref <ref>` for source builds) first",
+ };
+ }
+ } catch (error) {
+ return {
+ ok: false,
+ installedNow: false,
+ reason: error instanceof Error ? error.message : String(error),
+ };
+ }
+ if (await isExecutableFile(shimPath)) {
+ return { ok: true, installedNow: true };
+ }
+ return {
+ ok: false,
+ installedNow: false,
+ reason: `the managed install completed but no executable shim appeared at ${shimPath}`,
+ };
+ },
confirm: async () => {
const answer = await p.confirm({
message: "Install Paperclip as a background service?",
@@ -68,6 +142,22 @@ export async function handleOnboardService(
if (!explicitlyRequested && !(await deps.confirm())) return false;
+ // A definition pointing at a missing binary crash-loops in the platform
+ // supervisor's penalty box while doctor blames a port conflict.
+ // Materialize the managed install first, or decline with the repair path
+ // instead of installing a corpse.
+ const shim = await deps.ensureServiceShim();
+ if (!shim.ok) {
+ deps.warn(
+ `Background service not installed: ${shim.reason ?? "the managed install could not be completed"}. ` +
+ "Run `paperclipai install`, then `paperclipai service install`.",
+ );
+ return false;
+ }
+ if (shim.installedNow) {
+ deps.success("Installed the managed paperclipai payload and command shim for the service.");
+ }
+
await detection.manager.install({ startNow: true, startOnLogin: true });
if (!explicitlyRequested && detection.manager.enableLinger && await deps.confirmLinger()) {
await detection.manager.enableLinger();
diff --git a/cli/src/services/service-manager.ts b/cli/src/services/service-manager.ts
index f284afa59b..5267d5e145 100644
--- a/cli/src/services/service-manager.ts
+++ b/cli/src/services/service-manager.ts
@@ -1,4 +1,5 @@
import fs from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
import os from "node:os";
import path from "node:path";
import { execFile } from "node:child_process";
@@ -33,6 +34,7 @@ export interface ServiceManager {
restart(): Promise<void>;
status(): Promise<ServiceStatus>;
logs(follow: boolean, lines: number): Promise<void>;
+ installedExecutablePath(): Promise<string | null>;
enableLinger?(): Promise<void>;
}
@@ -75,6 +77,45 @@ export function resolveServiceShimPath(homeDir = os.homedir()): string {
return process.env.PAPERCLIP_SHIM_PATH?.trim() || path.join(homeDir, ".local", "bin", "paperclipai");
}
+// The installed definition, not the current environment, is the truth
+// about what the service executes: PAPERCLIP_SHIM_PATH may have changed
+// or been unset since the definition was written.
+function unescapeSystemd(value: string): string {
+ return value.replace(/\\\\|\\"|\$\$|%%/g, (m) =>
+ m === "\\\\" ? "\\" : m === '\\"' ? '"' : m === "$$" ? "$" : "%",
+ );
+}
+
+function unescapeXml(value: string): string {
+ return value.replace(/&(amp|lt|gt|quot|apos);/g, (_, name: string) =>
+ name === "amp" ? "&" : name === "lt" ? "<" : name === "gt" ? ">" : name === "quot" ? '"' : "'",
+ );
+}
+
+export function extractExecutableFromSystemdUnit(content: string): string | null {
+ const match = content.match(/^ExecStart="((?:\\.|[^"\\])*)"/m);
+ return match ? unescapeSystemd(match[1]) : null;
+}
+
+export function extractExecutableFromLaunchdPlist(content: string): string | null {
+ const match = content.match(/<key>ProgramArguments<\/key>\s*<array>\s*<string>([^<]+)<\/string>/);
+ return match ? unescapeXml(match[1]) : null;
+}
+
+// The service definition executes this path directly: existence is not
+// enough — a directory or a non-executable file would satisfy fs.access's
+// default mode and still crash the supervisor at spawn.
+export async function isExecutableFile(filePath: string): Promise<boolean> {
+ try {
+ const stats = await fs.stat(filePath);
+ if (!stats.isFile()) return false;
+ await fs.access(filePath, fsConstants.X_OK);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
export function systemdServiceName(instanceId: string): string {
return instanceId === "default" ? "paperclipai.service" : `paperclipai-${instanceId}.service`;
}
@@ -174,6 +215,14 @@ export class SystemdServiceManager implements ServiceManager {
return renderSystemdUnit({ instanceId: this.instanceId, shimPath: this.shimPath, homeDir: this.homeDir });
}
+ async installedExecutablePath(): Promise<string | null> {
+ try {
+ return extractExecutableFromSystemdUnit(await fs.readFile(this.definitionPath, "utf8"));
+ } catch {
+ return null;
+ }
+ }
+
private async ensureCurrent(): Promise<boolean> {
const changed = await writeIfChanged(this.definitionPath, this.renderDefinition());
if (changed) await this.runner("systemctl", ["--user", "daemon-reload"]);
@@ -242,6 +291,14 @@ export class LaunchdServiceManager implements ServiceManager {
renderDefinition(): string { return renderLaunchdPlist({ instanceId: this.instanceId, shimPath: this.shimPath, homeDir: this.homeDir, stdoutPath: this.stdoutPath, stderrPath: this.stderrPath }); }
+ async installedExecutablePath(): Promise<string | null> {
+ try {
+ return extractExecutableFromLaunchdPlist(await fs.readFile(this.definitionPath, "utf8"));
+ } catch {
+ return null;
+ }
+ }
+
async install(options: ServiceInstallOptions): Promise<{ changed: boolean }> {
await fs.mkdir(path.dirname(this.stdoutPath), { recursive: true });
const changed = await writeIfChanged(this.definitionPath, this.renderDefinition());