quotacap 0.0.22 → 0.0.23

package/dist/cli/runtime.js

@@ -1,11 +1,156 @@
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { VERSION } from "../version.js";
-import { getDbPath, readConfig } from "../config.js";
+import { ensureConfig, getDbPath } from "../config.js";
 import { readClaim } from "../runtime/owner.js";
 import { startService } from "../runtime/service.js";
 import { createServiceClient, ServiceError, ServiceUnavailable, } from "../runtime/client.js";
-import { runServiceCommand } from "../service/index.js";
+import { isServiceInstalled, isServiceManaged, runServiceCommand, serviceSupported, } from "../service/index.js";
+import { detectChannel, refreshUpdateCache } from "../runtime/updates.js";
+import { checkSkew, execSkewWarning, formatWedged, olderCliWarning, takeoverManaged, takeoverUnmanaged, upgradedMessage, waitForHealthy, WedgedError, } from "./takeover.js";
+// Shared `web` launcher handler: the `web` command and the bare `quotacap`
+// invocation both run this. Decision order: healthy daemons open (with the
+// skew matrix), registered-but-down services start, and only the last resort
+// foreground-starts. Explicit `--foreground` and non-config `--port`
+// overrides skip service management entirely.
+export async function launchWeb(o, deps = {}) {
+    const start = deps.startService ?? startService;
+    const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
+    const exit = deps.exit ?? process.exit;
+    const execService = deps.execService ?? ((args, opts) => runServiceCommand(args, opts ?? {}, {}));
+    const createClient = deps.createClient ?? ((c) => createServiceClient(c));
+    const isManaged = deps.isManaged ?? isServiceManaged;
+    const isInstalled = deps.isInstalled ?? isServiceInstalled;
+    const supported = deps.serviceSupported ?? serviceSupported;
+    const takeoverOpts = deps.takeoverOpts ?? {};
+    const checkUpdates = deps.checkUpdates ??
+        (() => refreshUpdateCache({ channel: detectChannel(), current: VERSION }));
+    const sleep = takeoverOpts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const readyTimeoutMs = takeoverOpts.timeoutMs ?? 15000;
+    const { config: cfg } = await ensureConfig();
+    const port = o.port ? parseInt(o.port, 10) : cfg.port;
+    const dataDir = path.dirname(getDbPath());
+    // Passive daily update signal (writer only; the dashboard badge reads it).
+    await checkUpdates().catch(() => null);
+    // Services only ever bind the config port, so an explicit override names
+    // an ad-hoc listener: skip service management like --foreground does.
+    const foregroundOnly = !!o.foreground || (!!o.port && port !== cfg.port);
+    // 1. A healthy service answers: compare skew, take over when newer.
+    let health = null;
+    try {
+        health = await createClient({ port, timeoutMs: 2000 }).get("/health");
+    }
+    catch (e) {
+        if (!(e instanceof ServiceUnavailable) && !(e instanceof ServiceError)) {
+            throw e;
+        }
+        health = null;
+    }
+    if (health?.ok) {
+        const skew = checkSkew(health, VERSION, process.execPath);
+        if (skew === "match") {
+            await openDashboard(`http://127.0.0.1:${port}`, openBrowser);
+            return;
+        }
+        if (skew === "exec-only") {
+            console.error(execSkewWarning(String(health.exec)));
+            await openDashboard(`http://127.0.0.1:${port}`, openBrowser);
+            return;
+        }
+        if (skew === "cli-older") {
+            console.error(olderCliWarning(String(health.version ?? "unknown")));
+            await openDashboard(`http://127.0.0.1:${port}`, openBrowser);
+            return;
+        }
+        // CLI newer than daemon: take over, then open.
+        const managed = await isManaged().catch(() => false);
+        if (managed) {
+            try {
+                const r = await takeoverManaged({
+                    port,
+                    health,
+                    createClient,
+                    execService,
+                    ...takeoverOpts,
+                });
+                console.error(r.message);
+            }
+            catch (e) {
+                console.error(e instanceof Error ? e.message : String(e));
+                exit(1);
+                return;
+            }
+            await openDashboard(`http://127.0.0.1:${port}`, openBrowser);
+            return;
+        }
+        try {
+            const r = await takeoverUnmanaged({
+                port,
+                health,
+                dataDir,
+                createClient,
+                ...takeoverOpts,
+            });
+            console.error(upgradedMessage(r.oldVersion, VERSION, "daemon"));
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            exit(e instanceof WedgedError ? 2 : 1);
+            return;
+        }
+        // Unmanaged successor: foreground-start the new daemon and open it.
+        const started = await start(o.port ? { port } : undefined);
+        await openDashboard(`http://127.0.0.1:${started.port}`, openBrowser);
+        return;
+    }
+    // 2. Nothing healthy on the target port, but another owner holds the
+    // installation: wedged — print recovery, never create a second poller.
+    const claim = readClaim(dataDir);
+    const fresh = !!claim && Date.now() - new Date(claim.lastBeat).getTime() < 30000;
+    if (fresh && claim) {
+        const managed = await isManaged().catch(() => false);
+        console.error(formatWedged({ claim, port, managed }));
+        exit(2);
+        return;
+    }
+    // 3. Unhealthy but registered: start the login service and open it.
+    let attemptedServiceStart = false;
+    if (!foregroundOnly) {
+        const installed = await isInstalled().catch(() => false);
+        if (installed) {
+            attemptedServiceStart = true;
+            let detail = null;
+            try {
+                const code = await execService(["start"]);
+                if (code !== 0)
+                    detail = `exit ${code}`;
+            }
+            catch (e) {
+                detail = e?.message ?? String(e);
+            }
+            if (!detail) {
+                const healthy = await waitForHealthy(port, VERSION, {
+                    createClient,
+                    sleep,
+                    timeoutMs: readyTimeoutMs,
+                });
+                if (!healthy)
+                    detail = `not ready within ${Math.round(readyTimeoutMs / 1000)}s`;
+            }
+            if (!detail) {
+                await openDashboard(`http://127.0.0.1:${port}`, openBrowser);
+                return;
+            }
+            console.error(`service start failed (${detail}); starting in the foreground instead`);
+        }
+    }
+    // 4. Foreground fallback: start, open, and suggest the login service.
+    const started = await start(o.port ? { port } : undefined);
+    if (!foregroundOnly && !attemptedServiceStart && supported()) {
+        console.error("for a background service that survives terminal closes, run 'quotacap service install'");
+    }
+    await openDashboard(`http://127.0.0.1:${started.port}`, openBrowser);
+}
 async function defaultOpenBrowser(url) {
     const cmd = process.platform === "darwin"
         ? "open"
@@ -37,58 +182,40 @@ export function registerRuntimeCommands(program, deps) {
     const exit = deps?.exit ?? process.exit;
     const execService = deps?.execService ??
         ((args, opts) => runServiceCommand(args, opts ?? {}, {}));
+    const createClient = deps?.createClient ?? ((o) => createServiceClient(o));
+    const isManaged = deps?.isManaged ?? isServiceManaged;
+    const isInstalled = deps?.isInstalled ?? isServiceInstalled;
+    const supported = deps?.serviceSupported ?? serviceSupported;
+    const takeoverOpts = deps?.takeoverOpts ?? {};
+    const checkUpdates = deps?.checkUpdates ??
+        (() => refreshUpdateCache({ channel: detectChannel(), current: VERSION }));
     program
         .command("daemon")
         .option("--foreground", "keep foreground (default: true)")
         .option("--port <n>")
         .description("run the complete service in the foreground")
         .action(async (o) => {
+        await ensureConfig();
         const started = await start(o.port ? { port: parseInt(o.port, 10) } : undefined);
         console.log(`quotacap service listening on http://127.0.0.1:${started.port}`);
     });
     program
         .command("web")
         .option("--port <n>")
-        .description("open the dashboard, starting the foreground service if needed")
-        .action(async (o) => {
-        const cfg = await readConfig();
-        const port = o.port ? parseInt(o.port, 10) : cfg.port;
-        const dataDir = path.dirname(getDbPath());
-        // 1. A healthy service answers: open it, never replace it.
-        let health = null;
-        try {
-            health = await createServiceClient({ port }).get("/health");
-        }
-        catch (e) {
-            if (!(e instanceof ServiceUnavailable) && !(e instanceof ServiceError)) {
-                throw e;
-            }
-            health = null;
-        }
-        if (health?.ok) {
-            if (health.version !== VERSION ||
-                (typeof health.exec === "string" &&
-                    health.exec !== process.execPath)) {
-                console.error(`existing service mismatch: ${health.exec ?? "unknown executable"} version ${health.version ?? "unknown"} on port ${port} (this CLI: ${process.execPath} version ${VERSION})`);
-                exit(2);
-                return;
-            }
-            await openDashboard(`http://127.0.0.1:${port}`, openBrowser);
-            return;
-        }
-        // 2. Nothing healthy on the target port, but another owner holds the
-        // installation: report, never create a second poller.
-        const claim = readClaim(dataDir);
-        const fresh = !!claim && Date.now() - new Date(claim.lastBeat).getTime() < 30000;
-        if (fresh && claim) {
-            console.error(`existing service mismatch: installation owned by ${claim.exec} version ${claim.version} (pid ${claim.pid}, started ${claim.startedAt}); no healthy service on port ${port}`);
-            exit(2);
-            return;
-        }
-        // 3. Start the foreground service (never login startup) and open it.
-        const started = await start(o.port ? { port } : undefined);
-        await openDashboard(`http://127.0.0.1:${started.port}`, openBrowser);
-    });
+        .option("--foreground", "hold the terminal with a foreground service instead of using the login service")
+        .description("open the dashboard, starting the service if needed")
+        .action(async (o) => launchWeb(o, {
+        startService: start,
+        openBrowser,
+        exit,
+        execService,
+        createClient,
+        isManaged,
+        isInstalled,
+        serviceSupported: supported,
+        takeoverOpts,
+        checkUpdates,
+    }));
     const service = program
         .command("service")
         .description("manage the per-user login service");

package/dist/cli/snapshot-source.d.ts

@@ -6,6 +6,7 @@ export declare class ClientError extends Error {
     constructor(kind: ClientErrorKind, message: string);
 }
 export declare const OFFLINE_LABEL = "offline: showing stored readings (service unreachable)";
+export declare function offlineOnlyClient(): ServiceClient;
 export declare function toClientError(e: unknown, action: string): ClientError;
 export declare function openOfflineDb(dbPath: string): any;
 export type SnapshotSource = "service" | "offline";

package/dist/cli/snapshot-source.js

@@ -18,6 +18,15 @@ export class ClientError extends Error {
 }
 // stderr label for labeled offline fallback (stdout stays a pure data contract).
 export const OFFLINE_LABEL = "offline: showing stored readings (service unreachable)";
+// A client that always fails transport: forces resolveSnapshot down the
+// labeled offline path without touching the network. Used when the daemon
+// is reachable but too old for an unmanaged takeover.
+export function offlineOnlyClient() {
+    const fail = async () => {
+        throw new ServiceUnavailable("service unavailable: skew fallback to stored readings");
+    };
+    return { get: fail, post: fail };
+}
 const NO_DATA_HINT = "no quotas yet - start the service (quotacap web)";
 function unreadableMessage(dbPath) {
     return `incompatible-schema: ${dbPath} is not a current QuotaCap database - start the service (quotacap web) to upgrade it`;

package/dist/cli/status.js

@@ -1,9 +1,13 @@
 import { projectQuotasResponse } from "../advisory/snapshot.js";
-import { getDbPath, readConfig } from "../config.js";
+import { ensureConfig, getDbPath } from "../config.js";
 import { renderCompact, renderNarrow, renderWide } from "../format/terminal.js";
 import { assertValidSortKey } from "../format/rows.js";
 import { createServiceClient } from "../runtime/client.js";
-import { ClientError, OFFLINE_LABEL, resolveSnapshot } from "./snapshot-source.js";
+import { VERSION } from "../version.js";
+import { isServiceManaged, runServiceCommand } from "../service/index.js";
+import { detectChannel, printUpdateFooter, readUpdateCache, refreshUpdateCache, updateFooter, } from "../runtime/updates.js";
+import { ClientError, OFFLINE_LABEL, offlineOnlyClient, resolveSnapshot } from "./snapshot-source.js";
+import { checkSkew, execSkewWarning, olderCliWarning, takeoverManaged, unmanagedSkewWarning, } from "./takeover.js";
 const WIDE_COLUMNS = 100;
 export function registerStatusCommand(program, deps) {
     const createClient = deps.createClient ?? ((o) => createServiceClient(o));
@@ -11,6 +15,11 @@ export function registerStatusCommand(program, deps) {
     const resolveWidth = deps.resolveWidth ?? (() => ({ columns: process.stdout.columns, tty: !!process.stdout.isTTY }));
     const now = deps.now ?? (() => new Date());
     const exit = deps.exit ?? process.exit;
+    const execService = deps.execService ?? ((args, o) => runServiceCommand(args, o ?? {}, {}));
+    const isManaged = deps.isManaged ?? isServiceManaged;
+    const takeoverOpts = deps.takeoverOpts ?? {};
+    const checkUpdates = deps.checkUpdates ??
+        (() => refreshUpdateCache({ channel: detectChannel(), current: VERSION }));
     program
         .command("status")
         .description("show quota status (service when reachable, stored readings otherwise)")
@@ -33,8 +42,61 @@ export function registerStatusCommand(program, deps) {
         const t = now();
         const compact = !!o.compact;
         const timeoutMs = compact ? 1000 : 2000;
-        const cfg = await readConfig();
-        const client = createClient({ port: cfg.port, timeoutMs });
+        const { config: cfg } = await ensureConfig();
+        let client = createClient({ port: cfg.port, timeoutMs });
+        // Skew pre-check: warn on exec-only and older-CLI skew, take the
+        // managed path when newer, and never spawn a foreground daemon here —
+        // unmanaged skew serves the stored snapshot instead of failing.
+        let health = null;
+        try {
+            health = await client.get("/health");
+        }
+        catch {
+            health = null;
+        }
+        if (health?.ok) {
+            const skew = checkSkew(health, VERSION, process.execPath);
+            if (skew === "exec-only") {
+                console.error(execSkewWarning(String(health.exec)));
+            }
+            else if (skew === "cli-older") {
+                console.error(olderCliWarning(String(health.version ?? "unknown")));
+            }
+            else if (skew === "cli-newer") {
+                const managed = await isManaged().catch(() => false);
+                if (managed) {
+                    try {
+                        const r = await takeoverManaged({
+                            port: cfg.port,
+                            health,
+                            createClient,
+                            execService,
+                            ...takeoverOpts,
+                        });
+                        console.error(r.message);
+                    }
+                    catch (e) {
+                        console.error(e instanceof Error ? e.message : String(e));
+                        exit(1);
+                        return;
+                    }
+                }
+                else {
+                    console.error(unmanagedSkewWarning(String(health.version ?? "unknown")));
+                    client = offlineOnlyClient();
+                }
+            }
+        }
+        // Passive daily update signal: opportunistically refresh the shared
+        // cache, then surface staleness as a stderr footer (never in --json).
+        let updateCache = null;
+        try {
+            updateCache = await checkUpdates();
+        }
+        catch {
+            updateCache = readUpdateCache();
+        }
+        const footer = updateFooter(VERSION, updateCache?.latest ?? null);
         let resolved;
         try {
             resolved = await resolveSnapshot({
@@ -53,9 +115,11 @@ export function registerStatusCommand(program, deps) {
                 }
                 if (compact) {
                     console.log("(use: none)");
+                    printUpdateFooter(o, footer);
                     return;
                 }
                 console.log(e.message);
+                printUpdateFooter(o, footer);
                 return;
             }
             console.error(e instanceof Error ? e.message : String(e));
@@ -71,6 +135,7 @@ export function registerStatusCommand(program, deps) {
         }
         if (compact) {
             console.log(renderCompact(snapshot, t));
+            printUpdateFooter(o, footer);
             return;
         }
         const { columns, tty } = resolveWidth();
@@ -80,5 +145,6 @@ export function registerStatusCommand(program, deps) {
         console.log(wide
             ? renderWide(snapshot, { now: t, ascii, color, sort })
             : renderNarrow(snapshot, { now: t, ascii, color, sort }));
+        printUpdateFooter(o, footer);
     });
 }

package/dist/cli/takeover.d.ts

@@ -0,0 +1,64 @@
+import { type ServiceClient } from "../runtime/client.js";
+import { type ClaimInfo } from "../runtime/owner.js";
+import { isServiceManaged } from "../service/index.js";
+export type SkewKind = "match" | "exec-only" | "cli-newer" | "cli-older";
+export interface HealthView {
+    ok?: unknown;
+    version?: unknown;
+    exec?: unknown;
+}
+export { parseVersion, compareVersions } from "../runtime/versions.js";
+export declare function checkSkew(health: HealthView, cliVersion?: string, cliExec?: string): SkewKind;
+/** Upgrade attempted but failed (restart error, readiness timeout, port never released). Callers exit 1. */
+export declare class TakeoverError extends Error {
+    constructor(message: string);
+}
+/** Daemon cannot be asked to stop (old binary, missing token). Callers print the message and exit 2. */
+export declare class WedgedError extends Error {
+    constructor(message: string);
+}
+export declare function olderCliWarning(daemonVersion: string): string;
+export declare function execSkewWarning(daemonExec: string, cliVersion?: string, cliExec?: string): string;
+export declare function unmanagedSkewWarning(daemonVersion: string): string;
+export declare function upgradedMessage(oldVersion: string, cliVersion: string, via: "service" | "daemon"): string;
+export declare function formatWedged(opts: {
+    claim: ClaimInfo | null;
+    port: number;
+    managed: boolean;
+}): string;
+export type SleepFn = (ms: number) => Promise<void>;
+export type CreateTakeoverClient = (opts: {
+    port: number;
+    token?: string;
+    timeoutMs: number;
+}) => ServiceClient;
+export type ExecServiceFn = (args: string[], opts?: Record<string, any>) => Promise<number>;
+export interface WaitOpts {
+    createClient?: CreateTakeoverClient;
+    sleep?: SleepFn;
+    timeoutMs?: number;
+}
+export declare function waitForHealthy(port: number, expectedVersion: string, opts?: WaitOpts): Promise<any | null>;
+export declare function waitForRelease(port: number, dataDir?: string, opts?: WaitOpts): Promise<boolean>;
+export interface TakeoverSharedOpts extends WaitOpts {
+    port: number;
+    cliVersion?: string;
+    cliExec?: string;
+    dataDir?: string;
+}
+export interface ManagedTakeoverOpts extends TakeoverSharedOpts {
+    health: HealthView;
+    execService?: ExecServiceFn;
+}
+export declare function takeoverManaged(opts: ManagedTakeoverOpts): Promise<{
+    oldVersion: string;
+    message: string;
+}>;
+export interface UnmanagedTakeoverOpts extends TakeoverSharedOpts {
+    health: HealthView;
+    readToken?: () => string | undefined;
+}
+export declare function takeoverUnmanaged(opts: UnmanagedTakeoverOpts): Promise<{
+    oldVersion: string;
+}>;
+export { isServiceManaged };

package/dist/cli/takeover.js

@@ -0,0 +1,175 @@
+// Daemon skew detection and takeover protocol (design section 6). Shared by
+// `web`, `status`, `advise`, and (Task 3) `update`: every command that
+// contacts /health compares version and exec, and a CLI newer than the
+// daemon restarts it instead of failing with exit code 2.
+import path from "node:path";
+import { VERSION } from "../version.js";
+import { getDbPath } from "../config.js";
+import { createServiceClient, ServiceError, ServiceUnavailable, } from "../runtime/client.js";
+import { readToken } from "../runtime/token.js";
+import { readClaim } from "../runtime/owner.js";
+import { runServiceCommand, isServiceManaged } from "../service/index.js";
+export { parseVersion, compareVersions } from "../runtime/versions.js";
+import { compareVersions, parseVersion } from "../runtime/versions.js";
+export function checkSkew(health, cliVersion = VERSION, cliExec = process.execPath) {
+    const hv = typeof health.version === "string" ? health.version : "";
+    const hex = typeof health.exec === "string" ? health.exec : "";
+    if (compareVersions(cliVersion, hv) === 0) {
+        return !hex || hex === cliExec ? "match" : "exec-only";
+    }
+    // Unequal versions: the CLI-newer path runs only when the CLI version
+    // parses and the daemon version does not sort above it. Anything else
+    // warns and proceeds; a newer daemon is never restarted into an older CLI.
+    if (parseVersion(cliVersion) && compareVersions(hv, cliVersion) <= 0) {
+        return "cli-newer";
+    }
+    return "cli-older";
+}
+/** Upgrade attempted but failed (restart error, readiness timeout, port never released). Callers exit 1. */
+export class TakeoverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TakeoverError";
+    }
+}
+/** Daemon cannot be asked to stop (old binary, missing token). Callers print the message and exit 2. */
+export class WedgedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WedgedError";
+    }
+}
+export function olderCliWarning(daemonVersion) {
+    return `daemon is newer (${daemonVersion}); run 'quotacap update' to match it`;
+}
+export function execSkewWarning(daemonExec, cliVersion = VERSION, cliExec = process.execPath) {
+    return `warning: service executable (${daemonExec}) differs from this CLI (${cliExec}) but versions match (${cliVersion}); continuing`;
+}
+export function unmanagedSkewWarning(daemonVersion) {
+    return `warning: daemon is older (${daemonVersion}) and no background service is registered; showing stored readings — run 'quotacap web' to upgrade`;
+}
+export function upgradedMessage(oldVersion, cliVersion, via) {
+    return `Upgraded daemon from ${oldVersion} to ${cliVersion} (${via === "service" ? "service restarted" : "daemon restarted"})`;
+}
+// Recovery instructions for a daemon that cannot be reached. The tool never
+// kills by PID; the human verifies first. This is the only surviving use of
+// the mismatch exit code.
+export function formatWedged(opts) {
+    const { claim, port, managed } = opts;
+    if (managed) {
+        return (`existing service mismatch: daemon on port ${port} is not answering but a background service is registered; ` +
+            `run 'quotacap service restart' (or 'quotacap service stop' and retry) to recover`);
+    }
+    if (claim) {
+        return (`existing service mismatch: installation owned by ${claim.exec} version ${claim.version} ` +
+            `(pid ${claim.pid}, started ${claim.startedAt}) is not answering on port ${port}; ` +
+            `stop that process in its own terminal, or verify it with 'ps -p ${claim.pid}' and then 'kill ${claim.pid}' before retrying`);
+    }
+    return (`existing service mismatch: daemon on port ${port} is not answering and no ownership claim was found; ` +
+        `stop the process listening on port ${port} in its own terminal and retry`);
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Poll /health until it reports the expected version (or the deadline).
+export async function waitForHealthy(port, expectedVersion, opts = {}) {
+    const createClient = opts.createClient ?? createServiceClient;
+    const sleep = opts.sleep ?? defaultSleep;
+    const timeoutMs = opts.timeoutMs ?? 15000;
+    const deadline = Date.now() + timeoutMs;
+    const client = createClient({ port, timeoutMs: 1000 });
+    for (;;) {
+        try {
+            const h = await client.get("/health");
+            if (h?.ok && h?.ready && h?.version === expectedVersion)
+                return h;
+        }
+        catch { }
+        if (Date.now() >= deadline)
+            return null;
+        await sleep(500);
+    }
+}
+// Poll until the port stops answering AND the ownership claim is gone.
+export async function waitForRelease(port, dataDir = path.dirname(getDbPath()), opts = {}) {
+    const createClient = opts.createClient ?? createServiceClient;
+    const sleep = opts.sleep ?? defaultSleep;
+    const timeoutMs = opts.timeoutMs ?? 15000;
+    const deadline = Date.now() + timeoutMs;
+    const client = createClient({ port, timeoutMs: 1000 });
+    for (;;) {
+        let portDown = false;
+        try {
+            await client.get("/health");
+        }
+        catch {
+            portDown = true;
+        }
+        if (portDown && readClaim(dataDir) === null)
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await sleep(250);
+    }
+}
+// Managed path: restart the supervisor-owned job, wait for readiness, and
+// verify /health reports the CLI version before declaring success.
+export async function takeoverManaged(opts) {
+    const cliVersion = opts.cliVersion ?? VERSION;
+    const oldVersion = typeof opts.health.version === "string" && opts.health.version
+        ? opts.health.version
+        : "unknown";
+    const execService = opts.execService ?? ((args, o) => runServiceCommand(args, o ?? {}, {}));
+    const code = await execService(["restart"]);
+    if (code !== 0) {
+        throw new TakeoverError(`daemon upgrade failed: service restart exited ${code}`);
+    }
+    const healthy = await waitForHealthy(opts.port, cliVersion, opts);
+    if (!healthy) {
+        throw new TakeoverError(`daemon upgrade failed: service did not report version ${cliVersion} within 15s; run 'quotacap service status' to inspect`);
+    }
+    return { oldVersion, message: upgradedMessage(oldVersion, cliVersion, "service") };
+}
+// Unmanaged path: ask the reachable daemon to stop gracefully, then wait for
+// the port and claim to release. The caller spawns the successor (or, for
+// `update`, leaves it stopped with guidance).
+export async function takeoverUnmanaged(opts) {
+    const port = opts.port;
+    const cliVersion = opts.cliVersion ?? VERSION;
+    const cliExec = opts.cliExec ?? process.execPath;
+    const dataDir = opts.dataDir ?? path.dirname(getDbPath());
+    const oldVersion = typeof opts.health.version === "string" && opts.health.version
+        ? opts.health.version
+        : "unknown";
+    const token = (opts.readToken ?? readToken)();
+    if (!token) {
+        throw new WedgedError(formatWedged({ claim: readClaim(dataDir), port, managed: false }));
+    }
+    const createClient = opts.createClient ?? createServiceClient;
+    const client = createClient({ port, token, timeoutMs: 5000 });
+    try {
+        // Always send the info body: Fastify rejects content-type json with an
+        // empty body, and the daemon logs the requester.
+        await client.post("/api/restart", { version: cliVersion, exec: cliExec });
+    }
+    catch (e) {
+        if (e instanceof ServiceError && e.status === 404) {
+            // Old daemon predates /api/restart and cannot be asked to stop.
+            throw new WedgedError(formatWedged({ claim: readClaim(dataDir), port, managed: false }));
+        }
+        if (e instanceof ServiceError && e.status === 401) {
+            throw new TakeoverError(`daemon upgrade failed: restart rejected (401) on port ${port}`);
+        }
+        if (e instanceof ServiceError) {
+            throw new TakeoverError(`daemon upgrade failed: restart request failed (HTTP ${e.status}) on port ${port}`);
+        }
+        if (!(e instanceof ServiceUnavailable))
+            throw e;
+        // Connection failed: the daemon may already be stopping; fall through
+        // to the release wait, which succeeds fast when it is gone.
+    }
+    const released = await waitForRelease(port, dataDir, opts);
+    if (!released) {
+        throw new TakeoverError(`daemon upgrade failed: old daemon did not stop within 15s; stop the process on port ${port} in its own terminal and retry`);
+    }
+    return { oldVersion };
+}
+export { isServiceManaged };