@indigoai-us/hq-cli 5.274.1 → 5.275.0

package/dist/commands/core-checkpoint-gate-setting.js

@@ -0,0 +1,163 @@
+/**
+ * `hq core checkpoint-gate-setting` — keeps the local cache that lets a
+ * company owner turn the checkpoint Stop gate off for their company (CO-58).
+ *
+ * The owner sets `companySettings.checkpointGateEnabled` on hq-pro
+ * (`hq company settings set --checkpoint-gate-enabled false`, or the console
+ * Settings page). The Stop gate script never calls the network: it reads
+ * `~/.hq/cache/checkpoint-gate/<slug>.json` and, when that is missing or older
+ * than ten minutes, starts this command detached with `--refresh`.
+ *
+ * `--refresh` reads the setting through the member-readable
+ * `GET /company-settings/checkpoint-gate` route and writes the cache only while
+ * the hq-flag `checkpoint.gate.company-setting` is on for the company. With the
+ * flag off it removes the cache, so the gate keeps today's behaviour. Any
+ * failure (no login, API unreachable, timeout) leaves the cache as it was: the
+ * gate then uses the last known value, or today's behaviour when there is none.
+ * Only the named company's setting is ever read.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getEntityUid, vaultApiFetch } from "../utils/vault-api.js";
+import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
+export const CHECKPOINT_GATE_SETTING_FLAG = "checkpoint.gate.company-setting";
+/** The refresh gives up after this long; the gate keeps the cached value. */
+export const CHECKPOINT_GATE_REFRESH_TIMEOUT_MS = 3_000;
+/** Same character set the gate script accepts; anything else is refused. */
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+export function assertCompanySlug(slug) {
+    if (!SLUG_RE.test(slug) || slug === "personal") {
+        throw new Error(`checkpoint-gate-setting: '${slug}' is not a company slug`);
+    }
+}
+export function checkpointGateCacheDir(home = os.homedir()) {
+    return path.join(home, ".hq", "cache", "checkpoint-gate");
+}
+export function checkpointGateCachePath(slug, home = os.homedir()) {
+    return path.join(checkpointGateCacheDir(home), `${slug}.json`);
+}
+/**
+ * `readLanesRegistryFlag` resolves a failed registry read to `false`. The
+ * refresh must not treat that as "flag off" and delete a valid cache, so a
+ * reported failure becomes null (unknown).
+ */
+export async function readCheckpointGateSettingFlag(slug, companyUid) {
+    let failed = false;
+    const enabled = await readLanesRegistryFlag(CHECKPOINT_GATE_SETTING_FLAG, {
+        company: { slug, uid: companyUid },
+        reportFailure: () => {
+            failed = true;
+        },
+    });
+    return failed ? null : enabled;
+}
+async function defaultFetchSetting(token, companyUid, signal) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/company-settings/checkpoint-gate",
+        query: { companyUid },
+        signal,
+    });
+    if (!res.ok)
+        throw new Error(`GET /company-settings/checkpoint-gate returned ${res.status}`);
+    const body = (await res.json());
+    if (typeof body.checkpointGateEnabled !== "boolean") {
+        throw new Error("GET /company-settings/checkpoint-gate returned no boolean checkpointGateEnabled");
+    }
+    return body.checkpointGateEnabled;
+}
+function writeCacheAtomic(file, entry) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function withTimeout(work, ms) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`timed out after ${ms} ms`));
+        }, ms);
+    });
+    return Promise.race([work(controller.signal), timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Refresh one company's cache entry. Never throws for a network or auth
+ * failure: those return `kept` and leave the cache untouched.
+ */
+export async function refreshCheckpointGateSetting(slug, deps = {}) {
+    assertCompanySlug(slug);
+    const file = checkpointGateCachePath(slug, deps.home);
+    // Never interactive: a detached refresh must not open a browser login.
+    const getToken = deps.getToken ?? (() => ensureCognitoToken({ interactive: false }));
+    const resolveCompanyUid = deps.resolveCompanyUid ?? ((token, companySlug) => getEntityUid(token, { companySlug }));
+    const fetchSetting = deps.fetchSetting ?? defaultFetchSetting;
+    const readFlag = deps.readFlag ?? readCheckpointGateSettingFlag;
+    // One timeout covers every network step, the flag read included.
+    let fetched;
+    try {
+        fetched = await withTimeout(async (signal) => {
+            const token = await getToken();
+            const uid = await resolveCompanyUid(token, slug);
+            const enabled = await fetchSetting(token, uid, signal);
+            return { enabled, flag: await readFlag(slug, uid) };
+        }, deps.timeoutMs ?? CHECKPOINT_GATE_REFRESH_TIMEOUT_MS);
+    }
+    catch (error) {
+        return { status: "kept", company: slug, reason: error instanceof Error ? error.message : String(error) };
+    }
+    if (fetched.flag === null) {
+        return { status: "kept", company: slug, reason: `could not read ${CHECKPOINT_GATE_SETTING_FLAG}` };
+    }
+    if (!fetched.flag) {
+        fs.rmSync(file, { force: true });
+        return { status: "removed", company: slug, reason: "flag_off" };
+    }
+    const now = (deps.now?.() ?? new Date()).getTime();
+    writeCacheAtomic(file, { company: slug, checkpointGateEnabled: fetched.enabled, fetched_at: Math.floor(now / 1000) });
+    return { status: "written", company: slug, checkpointGateEnabled: fetched.enabled };
+}
+export function describeRefreshOutcome(outcome) {
+    switch (outcome.status) {
+        case "written":
+            return `checkpoint gate for ${outcome.company}: ${outcome.checkpointGateEnabled ? "on" : "off"} (cached)`;
+        case "removed":
+            return `checkpoint gate for ${outcome.company}: company setting not in use (${CHECKPOINT_GATE_SETTING_FLAG} is off); cache cleared`;
+        case "kept":
+            return `checkpoint gate for ${outcome.company}: could not refresh (${outcome.reason}); cache unchanged`;
+    }
+}
+export function registerCoreCheckpointGateSettingCommand(core) {
+    const command = core
+        .command("checkpoint-gate-setting")
+        .description("Refresh the local cache of a company's checkpoint gate setting (used by the Stop gate)")
+        .requiredOption("--company <slug>", "company whose setting to read")
+        .option("--refresh", "read the setting from HQ and update the local cache")
+        .option("--json", "print the result as JSON")
+        .action(async (options) => {
+        try {
+            assertCompanySlug(options.company);
+            if (!options.refresh) {
+                const file = checkpointGateCachePath(options.company);
+                const cached = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null;
+                process.stdout.write(`${options.json ? JSON.stringify({ company: options.company, cached }) : cached ? `checkpoint gate for ${options.company}: ${cached.checkpointGateEnabled ? "on" : "off"} (cached at ${new Date(cached.fetched_at * 1000).toISOString()})` : `checkpoint gate for ${options.company}: no cached setting`}\n`);
+                return;
+            }
+            const outcome = await refreshCheckpointGateSetting(options.company);
+            process.stdout.write(`${options.json ? JSON.stringify(outcome) : describeRefreshOutcome(outcome)}\n`);
+            // A timed-out request can keep sockets open; the answer is already out.
+            process.exit(0);
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+        }
+    });
+    describeCoreCommand(command, { execution: "native", root: "cwd" });
+}
+//# sourceMappingURL=core-checkpoint-gate-setting.js.map

package/dist/commands/core.js

@@ -31,6 +31,7 @@
 import { Option } from "commander";
 import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
 import { registerCoreOntologyCommand } from "./core-ontology.js";
+import { registerCoreCheckpointGateSettingCommand } from "./core-checkpoint-gate-setting.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { interpreterFor, runBundledScript } from "../utils/run-bundled-script.js";
 import { renderIndexTarget } from "../lib/index-render/index.js";
@@ -286,6 +287,7 @@ export function registerCoreCommands(program) {
     // hosts native TypeScript plumbing when a scaffold contract needs it.
     registerCoreCheckpointCommand(core);
     registerCoreOntologyCommand(core);
+    registerCoreCheckpointGateSettingCommand(core);
     // These command names intentionally own native implementations. Their
     // similarly named scaffold assets are forwarders, so sending them through
     // runEntry would recurse back into this command forever.

package/dist/commands/daemon.js

@@ -489,8 +489,13 @@ function binaryFingerprint(bin) {
     }
 }
 async function runTmuxService(d, opts) {
-    const { runRemoteControlHost } = await import("../lib/daemon/remote-control.js");
+    const { installFingerprint, runRemoteControlHost } = await import("../lib/daemon/remote-control.js");
     const { findOnPath } = await import("../lib/daemon/run.js");
+    const { resolveRunningInstall } = await import("../utils/version-gate.js");
+    // The daemon keeps this host running across a CLI update, so a new hq-cli
+    // install also counts as an update and restarts the session once it is quiet.
+    const cliRoot = resolveRunningInstall().packageRoot;
+    const watched = cliRoot ? [opts.watch, path.join(cliRoot, "package.json")] : [opts.watch];
     const hqRoot = d.env.HQ_ROOT?.trim();
     if (!hqRoot)
         throw new DaemonCommandError(`${opts.label} needs HQ_ROOT (the daemon sets it from the saved HQ folder)`);
@@ -508,7 +513,7 @@ async function runTmuxService(d, opts) {
             cwd: hqRoot,
             argv: opts.argv,
             label: opts.label,
-            binaryFingerprint: () => binaryFingerprint(opts.watch),
+            binaryFingerprint: () => installFingerprint(watched, binaryFingerprint),
             now: () => Date.now(),
             run: d.run,
             pollMs: 5_000,

package/dist/commands/lanes.js

@@ -1158,7 +1158,7 @@ async function loadClaudeBalanceHostSnapshots(ctx, hqRoot, config) {
         const actualLocalLanes = hostname
             ? localLanes.filter((lane) => lane.host.kind === "local" && lane.host.id === hostname)
             : [];
-        if (actualLocalLanes.length > 0) {
+        if (hostname) {
             snapshots.push({
                 capacity: buildHostCapacitySnapshot({
                     host: actualLocalHost,
@@ -2402,6 +2402,11 @@ async function runCreate(ctx, opts) {
     let placementHostOverride;
     let autoPlacementChoice;
     let autoPlacementSkippedHosts = [];
+    let placementMachineIdentity;
+    const resolvePlacementMachineIdentity = () => {
+        placementMachineIdentity ??= ctx.resolveMachineIdentity();
+        return placementMachineIdentity;
+    };
     let balanceHostLoad;
     let balanceTargetHost;
     let inheritedPlacement;
@@ -2485,23 +2490,39 @@ async function runCreate(ctx, opts) {
                 }
                 throw err;
             }
-            placementHostOverride = autoPlacementChoice.host;
-            if (autoPlacementChoice.host.kind === currentHost.kind &&
-                autoPlacementChoice.host.id === currentHost.id) {
-                outpostId = undefined;
+            const chosenHost = autoPlacementChoice.host;
+            const localHostname = ctx.hostname().trim();
+            if (!localHostname) {
+                throw new LanesError("host_identity_unknown", "Cannot resolve this host for automatic lane placement", {});
+            }
+            const localHost = { kind: "local", id: localHostname };
+            let chosenHostIsCaller = chosenHost.id === currentHost.id ||
+                sanitizeHostComponent(chosenHost.id) === sanitizeHostComponent(localHostname);
+            if (!chosenHostIsCaller && chosenHost.kind === "outpost") {
+                const identity = resolvePlacementMachineIdentity();
+                if (identity.status === "ok") {
+                    const machineIds = [identity.id, identity.imds, identity.hostname]
+                        .filter((id) => typeof id === "string" && id.trim() !== "");
+                    chosenHostIsCaller = machineIds.some((id) => sanitizeHostComponent(chosenHost.id) === sanitizeHostComponent(id.trim()));
+                }
             }
-            else if (autoPlacementChoice.host.kind === "outpost") {
-                outpostId = autoPlacementChoice.host.id;
+            if (chosenHostIsCaller) {
+                // A capacity snapshot can identify this process as an Outpost (or an
+                // alias of its machine). Auto placement must spawn locally so the
+                // Outpost self-target guard is never reached.
+                placementHostOverride = localHost;
+                outpostId = undefined;
             }
             else {
-                outpostId = undefined;
+                placementHostOverride = chosenHost;
+                outpostId = chosenHost.kind === "outpost" ? chosenHost.id : undefined;
             }
         }
     }
     let originHost;
     let originHostSource;
     if (outpostId) {
-        const identity = ctx.resolveMachineIdentity();
+        const identity = resolvePlacementMachineIdentity();
         if (identity.status !== "ok") {
             throw new LanesError("origin_host_unresolvable", "Cannot record origin_host; this machine's identity is unresolvable", { identity });
         }

package/dist/lib/daemon/catalog.d.ts

@@ -54,6 +54,13 @@ export interface UnitPlan {
     command: UnitCommand | null;
     env: Record<string, string>;
     blocked?: UnitBlock;
+    /**
+     * Signal that asks the unit to finish its current work and exit, used when a
+     * new daemon replaces it after a CLI update. Without one it gets SIGTERM.
+     */
+    drainSignal?: "SIGUSR2";
+    /** A new CLI version alone does not restart this unit; it restarts itself when idle. */
+    keepAcrossCliUpdates?: true;
 }
 export interface PlanContext {
     machineType: MachineType;

package/dist/lib/daemon/catalog.js

@@ -183,6 +183,8 @@ function planService(service, ctx) {
                 description: `runs the local bot ${name}`,
                 restart: "on-failure",
                 command: { type: "hq", args: ["bot", "run", name] },
+                // A bot drains on SIGUSR2: running turns finish, then it exits.
+                drainSignal: "SIGUSR2",
             }));
         }
         case "session-host":
@@ -267,6 +269,8 @@ function planService(service, ctx) {
                         type: "hq",
                         args: ["daemon", "service", "codex-remote-control", "--script", script ?? "", "--codex", ctx.codexPath ?? ""],
                     },
+                    // Restarting the host ends the tmux session people are using.
+                    keepAcrossCliUpdates: true,
                     env: ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {},
                     blocked: firstBlock([
                         [!script, `this machine has no Codex remote-control runner (${CODEX_RUNNER_SCRIPT})`],
@@ -290,6 +294,8 @@ function planService(service, ctx) {
                 base(service, {
                     command: { type: "hq", args },
                     env: ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {},
+                    // Restarting the host ends the tmux session people are using.
+                    keepAcrossCliUpdates: true,
                     blocked: firstBlock([
                         [!ctx.claudePath, "the claude CLI is not installed"],
                         [!ctx.tmuxPath, "tmux is not installed (remote control runs Claude inside tmux)"],

package/dist/lib/daemon/flag.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Feature flags read by the daemon. The daemon runs for weeks, so each read
+ * asks the registry again instead of holding a per-process answer, and it
+ * reads as off unless the registry itself says on (or a local override does).
+ */
+import { type FlagClientOptions, type FlagResolution } from "@indigoai-us/hq-flags-client";
+/** Outposts hand running services to the next daemon on a CLI update instead of restarting them all. */
+export declare const SUPERVISOR_HANDOFF_FLAG = "daemon.supervisor-handoff";
+export interface DaemonFlagClient {
+    ready(): Promise<void>;
+    explain(flagKey: string, options?: {
+        fallback?: boolean;
+    }): FlagResolution;
+    close(): void;
+}
+export interface ReadDaemonFlagOptions {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => DaemonFlagClient;
+    getToken?: () => Promise<string>;
+    onError?: (error: unknown) => void;
+}
+export declare function readDaemonFlag(flagKey: string, options?: ReadDaemonFlagOptions): Promise<boolean>;
+//# sourceMappingURL=flag.d.ts.map

package/dist/lib/daemon/flag.js

@@ -0,0 +1,57 @@
+/**
+ * Feature flags read by the daemon. The daemon runs for weeks, so each read
+ * asks the registry again instead of holding a per-process answer, and it
+ * reads as off unless the registry itself says on (or a local override does).
+ */
+import { createFlagClient, readLocalOverride, } from "@indigoai-us/hq-flags-client";
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+import { resolveProcessFlagCompanyContext } from "../flag-registry.js";
+/** Outposts hand running services to the next daemon on a CLI update instead of restarting them all. */
+export const SUPERVISOR_HANDOFF_FLAG = "daemon.supervisor-handoff";
+const READ_TIMEOUT_MS = 5_000;
+export async function readDaemonFlag(flagKey, options = {}) {
+    const env = options.env ?? process.env;
+    const override = readLocalOverride(flagKey, env);
+    if (override !== null)
+        return override;
+    let failed = false;
+    const onError = (error) => {
+        failed = true;
+        options.onError?.(error);
+    };
+    let client;
+    try {
+        const company = resolveProcessFlagCompanyContext(env);
+        // Signed out reads as off without reaching the registry.
+        const token = await (options.getToken ?? (() => ensureCognitoIdToken({ interactive: false })))();
+        if (typeof token !== "string" || token.trim() === "")
+            return false;
+        client = (options.createClient ?? createFlagClient)({
+            endpoint: resolveFlagRegistryEndpoint(undefined, env),
+            getToken: () => token,
+            env: {},
+            refreshIntervalMs: 0,
+            requestTimeoutMs: READ_TIMEOUT_MS,
+            ...(company.companyUid ? { companyUid: company.companyUid } : {}),
+            ...(company.companySlug ? { companyIdentifiers: [company.companySlug] } : {}),
+            onError,
+        });
+        await client.ready();
+        const resolution = client.explain(flagKey, { fallback: false });
+        return !failed && resolution.source === "snapshot" && resolution.value === true;
+    }
+    catch (error) {
+        onError(error);
+        return false;
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch {
+            // closing a one-shot client cannot change the answer
+        }
+    }
+}
+//# sourceMappingURL=flag.js.map

package/dist/lib/daemon/install.js

@@ -61,6 +61,11 @@ function serviceHost(host) {
  * Output goes to the journal: an `append:` log file would be created by
  * systemd as root inside the user's home, and the daemon (running as the user)
  * writes its own logs under ~/.hq/daemon/logs.
+ *
+ * `KillMode=process`: systemd signals only the daemon. The daemon stops its
+ * services itself on SIGTERM, and after a CLI update it can leave them running
+ * for the next daemon to adopt (see succession.ts). A daemon that starts and
+ * finds services it did not adopt stops them first.
  */
 function renderSystemdSystemUnit(host, user, userHome) {
     const exec = [host.nodeBinary, host.hqBinary, "daemon", "run", "--managed"].map(shellQuote).join(" ");
@@ -87,7 +92,7 @@ ExecStart=${exec}
 WorkingDirectory=${userHome}
 Restart=always
 RestartSec=10
-KillMode=control-group
+KillMode=process
 TimeoutStopSec=20
 ${envLines}
 

package/dist/lib/daemon/remote-control.d.ts

@@ -31,6 +31,12 @@ export declare function remoteControlArgs(opts: {
  * (`--name outpost-1-2`), so taking the runner over keeps the name people see.
  */
 export declare function runnerSessionName(script: string): string | null;
+/**
+ * Fingerprint of what a host runs: the tool first, then other installs it
+ * depends on (the hq-cli package). Null while the tool cannot be read; an
+ * unreadable extra install is left out rather than hiding a tool update.
+ */
+export declare function installFingerprint(paths: readonly string[], fingerprint: (file: string) => string | null): string | null;
 /** A tool updated on disk restarts its session once quiet this long... */
 export declare const IDLE_BEFORE_RESTART_MS: number;
 /** ...or after this long, however busy the session is. */

package/dist/lib/daemon/remote-control.js

@@ -35,6 +35,18 @@ export function runnerSessionName(script) {
     const m = /remote-control\b[^\n]*?--name[= ]+"?([^\s"]+)"?/.exec(script);
     return m ? m[1] : null;
 }
+/**
+ * Fingerprint of what a host runs: the tool first, then other installs it
+ * depends on (the hq-cli package). Null while the tool cannot be read; an
+ * unreadable extra install is left out rather than hiding a tool update.
+ */
+export function installFingerprint(paths, fingerprint) {
+    const [tool, ...rest] = paths;
+    const toolFp = tool === undefined ? null : fingerprint(tool);
+    if (toolFp === null)
+        return null;
+    return [toolFp, ...rest.map(fingerprint).filter((fp) => fp !== null)].join("|");
+}
 /** A tool updated on disk restarts its session once quiet this long... */
 export const IDLE_BEFORE_RESTART_MS = 10 * 60_000;
 /** ...or after this long, however busy the session is. */

package/dist/lib/daemon/run.js

@@ -11,12 +11,14 @@ import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as path from "node:path";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { CLI_VERSION } from "../../cli-version.js";
 import { isLocalDependencyInstall, resolveRunningInstall } from "../../utils/version-gate.js";
 import { agentKitPaths } from "../agent-kit/paths.js";
 import { readBotConfig } from "../bot/config.js";
 import { botsRoot } from "../bot/paths.js";
 import { CLAUDE_RUNNER_SCRIPT, CODEX_RUNNER_SCRIPT, enabledServices, planUnits } from "./catalog.js";
 import { readDaemonConfig } from "./config.js";
+import { SUPERVISOR_HANDOFF_FLAG, readDaemonFlag } from "./flag.js";
 import { findLegacyUnits, legacyOwnerLookup } from "./legacy.js";
 import { readLegacySyncEnv } from "./legacy-sync-env.js";
 import { acquireDaemonLock, releaseDaemonLock } from "./lock.js";
@@ -26,12 +28,15 @@ import { appendPrivate, daemonPaths, ensurePrivateDir, openPrivateAppend } from
 import { takeControlRequests } from "./requests.js";
 import { currentHqCloud, hqCloudRunners } from "./hq-cloud.js";
 import { runnerSessionName } from "./remote-control.js";
-import { STOP_ESCALATION_MS, createSupervisor } from "./supervisor.js";
+import { adoptChild, createChildTracker, finishSuccession, handoffEligible, readProcStart, stopOrphans, successionPaths, systemdKillMode, takeSuccession, writeHandoff, } from "./succession.js";
+import { STOP_ESCALATION_MS, createSupervisor, } from "./supervisor.js";
 import { userToolDirs } from "./tools.js";
 export const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
 /** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
 export const RESTART_EXIT_CODE = 75;
 const LEGACY_PROBE_TTL_MS = 60_000;
+/** A flag read that has not answered by then counts as off. */
+const HANDOFF_FLAG_TIMEOUT_MS = 10_000;
 export function resolveSyncRunnerPath() {
     try {
         const require = createRequire(import.meta.url);
@@ -246,6 +251,32 @@ export async function runDaemon(opts) {
     }
     const hostNote = opts.host ? `, hosted by the ${opts.host} app` : "";
     log("info", `starting hq daemon (pid ${process.pid}) as ${machineType} (${detected.detail})${hostNote}`);
+    // On Linux, services can outlive a daemon (KillMode=process). Adopt the ones
+    // the previous daemon handed over and stop any others it left behind before
+    // starting anything, so a service never runs twice.
+    const succession = platform === "linux" && opts.host === undefined ? successionPaths(paths.root) : null;
+    const signalPid = (pid, sig) => {
+        process.kill(pid, sig);
+    };
+    let adopt = [];
+    if (succession) {
+        const taken = takeSuccession(succession, { now: Date.now, readStart: readProcStart, log });
+        await stopOrphans(taken.orphans, {
+            readStart: readProcStart,
+            signal: signalPid,
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+            log,
+        });
+        adopt = taken.adopt.map((u) => ({ id: u.id, key: u.key, child: adoptChild(u, { readStart: readProcStart, signal: signalPid }) }));
+    }
+    const tracker = succession ? createChildTracker(succession.childrenPath, { readStart: readProcStart, log }) : null;
+    for (const unit of adopt)
+        tracker?.track(unit.id, unit.child);
+    // Until now a crash leaves the previous records for the next daemon; from here the tracker owns them.
+    if (succession && tracker)
+        finishSuccession(succession, tracker.records(), log);
+    /** Service processes this daemon spawned, so a handoff can let go of them. */
+    const spawned = new Set();
     if (!resolveSyncRunnerPath())
         log("warn", "the hq-cloud sync runner was not found in this CLI install; sync is unavailable");
     const updatable = cliSelfUpdatable();
@@ -320,6 +351,11 @@ export async function runDaemon(opts) {
                 stdio: ["ignore", fd, fd],
                 windowsHide: true,
             });
+            spawned.add(child);
+            child.once("exit", () => spawned.delete(child));
+            // Only long-running services are handed over; a scheduled run left behind finishes on its own.
+            if (unit.kind === "long-running")
+                tracker?.track(unit.id, child);
             return child;
         }
         finally {
@@ -346,9 +382,36 @@ export async function runDaemon(opts) {
         restartDaemon: () => restartDaemon(),
         writeState: (state) => writeJsonAtomic(paths.statePath, state),
         log,
+        cliVersion: CLI_VERSION,
+        adopt,
     });
+    /** Hand services over on this restart: the unit leaves them running and the flag is on. */
+    const handoffWanted = async () => {
+        const killMode = platform === "linux"
+            ? systemdKillMode((file, args) => {
+                const r = spawnSync(file, args, { encoding: "utf8" });
+                return { status: r.status, stdout: r.stdout ?? "" };
+            })
+            : null;
+        if (!handoffEligible({ platform, managed: opts.managed === true, host: opts.host, killMode }))
+            return false;
+        let timer;
+        const timeout = new Promise((r) => {
+            timer = setTimeout(() => r(false), HANDOFF_FLAG_TIMEOUT_MS);
+        });
+        const on = await Promise.race([
+            readDaemonFlag(SUPERVISOR_HANDOFF_FLAG, {
+                env,
+                onError: (err) => log("warn", `could not read ${SUPERVISOR_HANDOFF_FLAG}: ${err.message ?? err}`),
+            }),
+            timeout,
+        ]);
+        clearTimeout(timer);
+        return on;
+    };
     return await new Promise((resolve) => {
         let stopping = false;
+        let restartPending = false;
         const shutdown = (why, exitCode = 0) => {
             if (stopping)
                 return;
@@ -370,12 +433,62 @@ export async function runDaemon(opts) {
                 resolve(exitCode);
             });
         };
+        /** Exit for a restart but leave the services running for the next daemon to adopt. */
+        const handOver = () => {
+            if (stopping)
+                return;
+            stopping = true;
+            const released = supervisor.release();
+            const starts = new Map((tracker?.records() ?? []).map((r) => [r.pid, r.start]));
+            const units = released.flatMap((u) => {
+                const start = starts.get(u.pid);
+                if (start !== undefined)
+                    return [{ ...u, start }];
+                // Unverifiable later, so it cannot be adopted; stop it rather than leave a second copy.
+                log("warn", `stopping ${u.id}: its process could not be recorded for the next daemon`);
+                try {
+                    process.kill(u.pid, "SIGTERM");
+                }
+                catch {
+                    // already gone
+                }
+                return [];
+            });
+            try {
+                writeHandoff(succession.handoffPath, { releasedAt: Date.now(), units });
+                log("info", `restarting onto the updated CLI; handing ${units.length} running service(s) to the next daemon`);
+            }
+            catch (err) {
+                // The children record still lists them, so the next daemon stops and restarts them.
+                log("error", `could not write the handoff; the next daemon will restart the services: ${err.message}`);
+            }
+            // The released processes must not keep this one alive.
+            for (const child of spawned)
+                child.unref();
+            releaseDaemonLock(paths.lockPath);
+            resolve(RESTART_EXIT_CODE);
+            // Anything else still holding the event loop open must not delay the restart.
+            setTimeout(() => process.exit(RESTART_EXIT_CODE), 5_000).unref();
+        };
         restartDaemon = () => {
             if (!restartsForParent(opts)) {
                 log("warn", "a restart was requested, but no service manager would start this daemon again; restart it yourself");
                 return;
             }
-            shutdown("restarting onto the updated CLI", RESTART_EXIT_CODE);
+            if (stopping || restartPending)
+                return;
+            restartPending = true;
+            void handoffWanted()
+                .catch((err) => {
+                log("warn", `could not decide on a handoff; restarting every service: ${err.message}`);
+                return false;
+            })
+                .then((handoff) => {
+                if (handoff && succession)
+                    handOver();
+                else
+                    shutdown("restarting onto the updated CLI", RESTART_EXIT_CODE);
+            });
         };
         process.on("SIGTERM", () => shutdown("received SIGTERM"));
         process.on("SIGINT", () => shutdown("received SIGINT"));