@indigoai-us/hq-cli 5.285.0 → 5.287.0

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

@@ -12,6 +12,8 @@ export interface DaemonPaths {
     requestsDir: string;
     supervisorLogPath: string;
     unitLogPath: (unitId: string) => string;
+    /** The FIFO a unit that speaks the sync protocol writes its stdout to (see protocol-tail.ts); kept out of logs/ so nothing reading logs drains it. */
+    unitProtocolPath: (unitId: string) => string;
 }
 export declare function daemonPaths(home?: string, env?: NodeJS.ProcessEnv): DaemonPaths;
 /** Create `dir` (and any missing parents) readable only by its owner, and tighten it if it already exists. */

package/dist/lib/daemon/paths.js

@@ -18,6 +18,7 @@ export function daemonPaths(home = os.homedir(), env = process.env) {
         requestsDir: path.join(root, "requests"),
         supervisorLogPath: path.join(logsDir, "daemon.log"),
         unitLogPath: (unitId) => path.join(logsDir, `${unitId.replace(/[^A-Za-z0-9_.-]/g, "-")}.log`),
+        unitProtocolPath: (unitId) => path.join(root, "protocol", `${unitId.replace(/[^A-Za-z0-9_.-]/g, "-")}.fifo`),
     };
 }
 /** Create `dir` (and any missing parents) readable only by its owner, and tighten it if it already exists. */

package/dist/lib/daemon/protocol-tail.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A service's protocol output read from a named pipe instead of an anonymous
+ * one.
+ *
+ * An anonymous pipe loses its reader when the daemon exits, so a service
+ * writing to one cannot be handed to the next daemon. Here the service's
+ * stdout is a FIFO it holds open for reading and writing, so it always has a
+ * reader and never gets EPIPE. Each daemon polls the FIFO without blocking and
+ * feeds what it reads to the supervisor as the child's stdout. On a handoff
+ * the daemon stops reading without draining, so output it has not read stays
+ * in the kernel buffer for the next daemon, and nothing accumulates on disk.
+ */
+export interface ProtocolTail {
+    /** "data" carries each chunk read; "end" fires once, after close(). */
+    on(event: "data" | "end", handler: (chunk?: Buffer | string) => void): ProtocolTail;
+    /** The service exited: read what is left, emit "end" and stop polling. */
+    close(): void;
+    /** Handing over: stop polling without reading, leaving the rest for the next daemon. */
+    detach(): void;
+}
+/** Make `file` a FIFO, replacing anything else found there. */
+export declare function ensureProtocolFifo(file: string): void;
+/**
+ * The service's stdout. Opened for reading and writing, so the FIFO keeps a
+ * reader while no daemon has it open and the service's writes never fail.
+ */
+export declare function openProtocolWriter(file: string): number;
+export declare function createProtocolTail(file: string, opts?: {
+    pollMs?: number;
+    setInterval?: (fn: () => void, ms: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+}): ProtocolTail;
+//# sourceMappingURL=protocol-tail.d.ts.map

package/dist/lib/daemon/protocol-tail.js

@@ -0,0 +1,131 @@
+/**
+ * A service's protocol output read from a named pipe instead of an anonymous
+ * one.
+ *
+ * An anonymous pipe loses its reader when the daemon exits, so a service
+ * writing to one cannot be handed to the next daemon. Here the service's
+ * stdout is a FIFO it holds open for reading and writing, so it always has a
+ * reader and never gets EPIPE. Each daemon polls the FIFO without blocking and
+ * feeds what it reads to the supervisor as the child's stdout. On a handoff
+ * the daemon stops reading without draining, so output it has not read stays
+ * in the kernel buffer for the next daemon, and nothing accumulates on disk.
+ */
+import { spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ensurePrivateDir } from "./paths.js";
+const POLL_MS = 1_000;
+const READ_CHUNK_BYTES = 64 * 1024;
+/** Make `file` a FIFO, replacing anything else found there. */
+export function ensureProtocolFifo(file) {
+    ensurePrivateDir(path.dirname(file));
+    try {
+        if (fs.lstatSync(file).isFIFO())
+            return;
+        fs.rmSync(file, { force: true });
+    }
+    catch {
+        // Missing: created below.
+    }
+    const r = spawnSync("mkfifo", ["-m", "600", file], { encoding: "utf8" });
+    if (r.error)
+        throw r.error;
+    if (r.status !== 0)
+        throw new Error(`mkfifo ${file} failed: ${(r.stderr ?? "").trim() || `exit ${r.status}`}`);
+}
+/**
+ * The service's stdout. Opened for reading and writing, so the FIFO keeps a
+ * reader while no daemon has it open and the service's writes never fail.
+ */
+export function openProtocolWriter(file) {
+    return fs.openSync(file, fs.constants.O_RDWR);
+}
+export function createProtocolTail(file, opts = {}) {
+    const events = new EventEmitter();
+    const setI = opts.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+    const clearI = opts.clearInterval ?? ((h) => clearInterval(h));
+    let fd = null;
+    let done = false;
+    const open = () => {
+        if (fd !== null)
+            return fd;
+        try {
+            fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        }
+        catch {
+            fd = null;
+        }
+        return fd;
+    };
+    const read = () => {
+        const handle = open();
+        if (handle === null)
+            return;
+        const buf = Buffer.alloc(READ_CHUNK_BYTES);
+        for (;;) {
+            let n;
+            try {
+                n = fs.readSync(handle, buf, 0, buf.length, null);
+            }
+            catch (err) {
+                // EAGAIN: nothing written since the last read.
+                if (err.code === "EAGAIN")
+                    return;
+                throw err;
+            }
+            if (n <= 0)
+                return;
+            events.emit("data", Buffer.from(buf.subarray(0, n)));
+        }
+    };
+    const stop = () => {
+        done = true;
+        clearI(timer);
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // already closed
+            }
+            fd = null;
+        }
+    };
+    const timer = setI(() => {
+        try {
+            read();
+        }
+        catch {
+            // An unreadable FIFO reads as silence; the heartbeat watchdog restarts the service.
+        }
+    }, opts.pollMs ?? POLL_MS);
+    timer.unref?.();
+    // Open now, so the FIFO has a reader before the service starts writing.
+    open();
+    const tail = {
+        on(event, handler) {
+            events.on(event, handler);
+            return tail;
+        },
+        close() {
+            if (done)
+                return;
+            try {
+                read();
+            }
+            catch {
+                // nothing more to read
+            }
+            stop();
+            events.emit("end");
+        },
+        detach() {
+            if (done)
+                return;
+            stop();
+        },
+    };
+    return tail;
+}
+//# sourceMappingURL=protocol-tail.js.map

package/dist/lib/daemon/run.js

@@ -25,6 +25,7 @@ import { acquireDaemonLock, releaseDaemonLock } from "./lock.js";
 import { daemonRootRefusal } from "./install.js";
 import { detectMachineType } from "./machine-type.js";
 import { appendPrivate, daemonPaths, ensurePrivateDir, openPrivateAppend } from "./paths.js";
+import { createProtocolTail, ensureProtocolFifo, openProtocolWriter } from "./protocol-tail.js";
 import { takeControlRequests } from "./requests.js";
 import { currentHqCloud, hqCloudRunners } from "./hq-cloud.js";
 import { runnerSessionName } from "./remote-control.js";
@@ -224,6 +225,14 @@ export function unitProcessEnv(base, unit) {
         env.NODE_OPTIONS = syncRunnerNodeOptions(env);
     return env;
 }
+function isFifo(file) {
+    try {
+        return fs.lstatSync(file).isFIFO();
+    }
+    catch {
+        return false;
+    }
+}
 export async function runDaemon(opts) {
     const env = opts.env ?? process.env;
     const home = opts.home ?? os.homedir();
@@ -263,6 +272,8 @@ export async function runDaemon(opts) {
         process.kill(pid, sig);
     };
     let adopt = [];
+    /** Readers of units' protocol FIFOs; a handoff detaches them so the next daemon reads what is left. */
+    const protocolTails = new Set();
     if (succession) {
         const taken = takeSuccession(succession, { now: Date.now, readStart: readProcStart, log });
         await stopOrphans(taken.orphans, {
@@ -271,7 +282,20 @@ export async function runDaemon(opts) {
             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 }) }));
+        adopt = taken.adopt.map((u) => {
+            // A unit that speaks the sync protocol writes it to a FIFO; read what the previous daemon left.
+            const protocolPath = paths.unitProtocolPath(u.id);
+            const stdout = isFifo(protocolPath) ? createProtocolTail(protocolPath) : undefined;
+            const child = adoptChild(u, { readStart: readProcStart, signal: signalPid, ...(stdout ? { stdout } : {}) });
+            if (stdout) {
+                protocolTails.add(stdout);
+                child.on("exit", () => {
+                    protocolTails.delete(stdout);
+                    stdout.close();
+                });
+            }
+            return { id: u.id, key: u.key, child };
+        });
     }
     const tracker = succession ? createChildTracker(succession.childrenPath, { readStart: readProcStart, log }) : null;
     for (const unit of adopt)
@@ -381,11 +405,57 @@ export async function runDaemon(opts) {
                 : [command.file, command.args];
         const logPath = paths.unitLogPath(unit.id);
         const cwd = unit.env.HQ_ROOT && fs.existsSync(unit.env.HQ_ROOT) ? unit.env.HQ_ROOT : home;
+        if (unit.heartbeatTimeoutMs && succession) {
+            // The supervisor reads this unit's protocol heartbeats from stdout. Where
+            // services can outlive the daemon, stdout is a FIFO (see protocol-tail.ts)
+            // rather than a pipe, so the unit can be handed to the next daemon.
+            const protocolPath = paths.unitProtocolPath(unit.id);
+            ensureProtocolFifo(protocolPath);
+            const stdout = createProtocolTail(protocolPath);
+            const outFd = openProtocolWriter(protocolPath);
+            const errFd = openPrivateAppend(logPath);
+            try {
+                const child = spawn(file, args, {
+                    cwd,
+                    env: unitProcessEnv(env, unit),
+                    stdio: ["ignore", outFd, errFd],
+                    windowsHide: true,
+                });
+                spawned.add(child);
+                if (unit.service === "sync" && child.pid !== undefined)
+                    daemonSyncRunnerPids.add(child.pid);
+                protocolTails.add(stdout);
+                const finish = () => {
+                    protocolTails.delete(stdout);
+                    stdout.close();
+                };
+                child.once("exit", () => {
+                    spawned.delete(child);
+                    if (child.pid !== undefined)
+                        daemonSyncRunnerPids.delete(child.pid);
+                    finish();
+                });
+                child.once("error", finish);
+                const supervised = {
+                    pid: child.pid,
+                    stdout,
+                    on(event, handler) {
+                        child.on(event, handler);
+                        return supervised;
+                    },
+                    kill: (signal) => child.kill(signal),
+                };
+                if (unit.kind === "long-running")
+                    tracker?.track(unit.id, supervised);
+                return supervised;
+            }
+            finally {
+                fs.closeSync(outFd);
+                fs.closeSync(errFd);
+            }
+        }
         if (unit.heartbeatTimeoutMs) {
-            // The supervisor reads this unit's protocol heartbeats from stdout, so its
-            // output goes through the daemon. A piped child cannot outlive the daemon,
-            // so it is never handed over: a handoff stops it and the next daemon
-            // starts it again.
+            // Elsewhere the service stops with the daemon, so its output can go through a pipe.
             const logFd = openPrivateAppend(logPath);
             const logStream = fs.createWriteStream(logPath, { fd: logFd, autoClose: true });
             logStream.on("error", (err) => log("error", `could not write ${unit.id} log ${logPath}: ${err.message}`));
@@ -525,6 +595,10 @@ export async function runDaemon(opts) {
                 return;
             stopping = true;
             const released = supervisor.release();
+            // What these readers have not read stays in the FIFO for the next daemon.
+            for (const tail of protocolTails)
+                tail.detach();
+            protocolTails.clear();
             const starts = new Map((tracker?.records() ?? []).map((r) => [r.pid, r.start]));
             const units = released.flatMap((u) => {
                 const start = starts.get(u.pid);

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

@@ -95,6 +95,8 @@ export declare function adoptChild(record: ChildRecord, deps: {
     setInterval?: (fn: () => void, ms: number) => unknown;
     clearInterval?: (handle: unknown) => void;
     pollMs?: number;
+    /** Its protocol output, read from the file it writes to (see protocol-tail.ts). */
+    stdout?: SupervisedChild["stdout"];
 }): SupervisedChild;
 /** The loaded daemon unit's KillMode, or null when systemctl cannot tell. */
 export declare function systemdKillMode(run: (file: string, args: string[]) => {

package/dist/lib/daemon/succession.js

@@ -226,6 +226,7 @@ export function adoptChild(record, deps) {
     poll.unref?.();
     const child = {
         pid: record.pid,
+        ...(deps.stdout ? { stdout: deps.stdout } : {}),
         on(event, handler) {
             events.on(event, handler);
             return child;

package/dist/lib/doctor/report.js

@@ -103,7 +103,7 @@ export function renderText(options) {
     const pad = " ".repeat(STATUS_LABEL_WIDTH);
     const lines = [];
     lines.push(`hq doctor — HQ root: ${hqRoot}`);
-    lines.push(`Platform: ${platform.id}`);
+    lines.push(`Agent platform: ${platform.id}`);
     for (const run of families) {
         lines.push("");
         lines.push(`${run.family.title} (${run.family.id})`);

package/dist/lib/lanes/outpost-snapshot-refresh.d.ts

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+export declare const OUTPOST_SNAPSHOT_REFRESH_LOCK_STALE_AFTER_MS: number;
+export interface SnapshotRefreshChildRuntime {
+    pid: number;
+    once: (event: "exit", listener: () => void) => unknown;
+}
+export interface StartSnapshotRefreshDeps {
+    spawn?: typeof spawn;
+    now?: () => number;
+    pid?: number;
+    isProcessAlive?: (pid: number) => boolean;
+    entryPath?: string;
+    beforeStaleLockClaim?: () => void;
+    writeError?: (message: string) => void;
+}
+export declare function outpostSnapshotRefreshLockPath(root: string, env?: NodeJS.ProcessEnv): string;
+/** Start the detached remote snapshot refresh unless this HQ root is refreshing already. */
+export declare function startOutpostLaneSnapshotRefresh(root: string, env?: NodeJS.ProcessEnv, deps?: StartSnapshotRefreshDeps): void;
+/** Adopt the launcher lock in the detached child and remove it on normal exit. */
+export declare function registerOutpostLaneSnapshotRefreshChild(env?: NodeJS.ProcessEnv, runtime?: SnapshotRefreshChildRuntime): boolean;
+//# sourceMappingURL=outpost-snapshot-refresh.d.ts.map

package/dist/lib/lanes/outpost-snapshot-refresh.js

@@ -0,0 +1,329 @@
+import { randomUUID, createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const STATE_DIR_ENV = "HQ_LANES_SNAPSHOT_REFRESH_STATE_DIR";
+const CHILD_LOCK_PATH_ENV = "HQ_INTERNAL_LANES_SNAPSHOT_REFRESH_LOCK_PATH";
+const CHILD_LOCK_TOKEN_ENV = "HQ_INTERNAL_LANES_SNAPSHOT_REFRESH_LOCK_TOKEN";
+// One Outpost summary pickup has a 20-second timeout. Thirty minutes leaves
+// ample time for lists spanning many Outposts while bounding abandoned locks.
+export const OUTPOST_SNAPSHOT_REFRESH_LOCK_STALE_AFTER_MS = 30 * 60 * 1_000;
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function writeError(message) {
+    process.stderr.write(`${message}\n`);
+}
+export function outpostSnapshotRefreshLockPath(root, env = process.env) {
+    const stateBase = env[STATE_DIR_ENV]?.trim() || path.join(env.XDG_STATE_HOME?.trim() || path.join(os.homedir(), ".local", "state"), "hq-cli");
+    if (!path.isAbsolute(stateBase))
+        throw new Error(`${STATE_DIR_ENV} must resolve to an absolute path`);
+    const canonicalRoot = fs.realpathSync(path.resolve(root));
+    const rootHash = createHash("sha256").update(canonicalRoot).digest("hex");
+    return path.join(stateBase, "lanes-snapshot-refresh", `${rootHash}.lock`);
+}
+function parseLock(filePath, content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`could not read lock ${filePath}: ${errorMessage(err)}`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`invalid lock data in ${filePath}`);
+    }
+    const lock = value;
+    if (!Number.isSafeInteger(lock.pid) || (lock.pid ?? 0) <= 0 ||
+        !Number.isFinite(lock.startedAt) || (lock.startedAt ?? 0) < 0 ||
+        typeof lock.token !== "string" || lock.token.length === 0) {
+        throw new Error(`invalid lock fields in ${filePath}`);
+    }
+    return lock;
+}
+function readLock(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`could not read lock ${filePath}: ${errorMessage(err)}`);
+    }
+    return parseLock(filePath, content);
+}
+function observeLock(filePath) {
+    const descriptor = fs.openSync(filePath, "r");
+    try {
+        const stat = fs.fstatSync(descriptor);
+        const content = fs.readFileSync(descriptor, "utf8");
+        try {
+            return { lock: parseLock(filePath, content), content, stat };
+        }
+        catch (err) {
+            return { lock: null, content, stat, invalidReason: errorMessage(err) };
+        }
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true;
+        throw err;
+    }
+}
+function writeLockExclusive(filePath, lock) {
+    const descriptor = fs.openSync(filePath, "wx", 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify(lock)}\n`, "utf8");
+        fs.fsyncSync(descriptor);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch {
+            // Keep the original write error as the actionable cause.
+        }
+        throw err;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function writeLockReplacement(filePath, lock) {
+    const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    const descriptor = fs.openSync(temporaryPath, "wx", 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify(lock)}\n`, "utf8");
+        fs.fsyncSync(descriptor);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temporaryPath);
+        }
+        catch {
+            // Keep the original write error as the actionable cause.
+        }
+        throw err;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    try {
+        fs.renameSync(temporaryPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temporaryPath);
+        }
+        catch {
+            // Keep the rename error as the actionable cause.
+        }
+        throw err;
+    }
+}
+function releaseLock(filePath, token) {
+    try {
+        if (readLock(filePath).token === token)
+            fs.unlinkSync(filePath);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            writeError(`lanes snapshot refresh could not release its lock: ${errorMessage(err)}`);
+        }
+    }
+}
+function updateLockOwner(filePath, token, pid) {
+    const lock = readLock(filePath);
+    if (lock.token !== token)
+        throw new Error(`lock ownership changed at ${filePath}`);
+    writeLockReplacement(filePath, { ...lock, pid });
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+ * Claim the exact stale inode before unlinking it. Claim paths are stable for
+ * one inode, so two contenders cannot both remove the same expired lock.
+ */
+function claimStaleLock(filePath, observed) {
+    const claimPath = `${filePath}.claim-${observed.stat.dev}-${observed.stat.ino}`;
+    try {
+        fs.linkSync(filePath, claimPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST" || code === "ENOENT")
+            return false;
+        throw err;
+    }
+    let claimedStaleLock = false;
+    let claimError;
+    try {
+        const claimStat = fs.statSync(claimPath);
+        const currentStat = fs.statSync(filePath);
+        if (sameFile(observed.stat, claimStat) && sameFile(observed.stat, currentStat)) {
+            const claimContent = fs.readFileSync(claimPath, "utf8");
+            const currentContent = fs.readFileSync(filePath, "utf8");
+            if (claimContent === observed.content && currentContent === observed.content) {
+                fs.unlinkSync(filePath);
+                claimedStaleLock = true;
+            }
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            claimError = err;
+    }
+    try {
+        fs.unlinkSync(claimPath);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            claimError ??= err;
+    }
+    if (claimError)
+        throw claimError;
+    return claimedStaleLock;
+}
+function acquireLock(root, env, deps) {
+    const filePath = outpostSnapshotRefreshLockPath(root, env);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const lock = {
+            pid: deps.pid ?? process.pid,
+            startedAt: (deps.now ?? Date.now)(),
+            token: randomUUID(),
+        };
+        try {
+            writeLockExclusive(filePath, lock);
+            return lock;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        let existing;
+        try {
+            existing = observeLock(filePath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const staleSince = existing.lock?.startedAt ?? existing.stat.mtimeMs;
+        const ageMs = (deps.now ?? Date.now)() - staleSince;
+        const oldEnough = ageMs >= OUTPOST_SNAPSHOT_REFRESH_LOCK_STALE_AFTER_MS;
+        if (!existing.lock) {
+            if (!oldEnough) {
+                throw new Error(`malformed lock ${filePath} is not old enough to recover: ${existing.invalidReason}`);
+            }
+        }
+        else {
+            const alive = (deps.isProcessAlive ?? processIsAlive)(existing.lock.pid);
+            if (!oldEnough || alive)
+                return null;
+        }
+        deps.beforeStaleLockClaim?.();
+        if (!claimStaleLock(filePath, existing))
+            return null;
+    }
+    // Another caller may have replaced a stale lock during recovery. Fail closed
+    // and let the next list call retry rather than risking a second refresh.
+    return null;
+}
+/** Start the detached remote snapshot refresh unless this HQ root is refreshing already. */
+export function startOutpostLaneSnapshotRefresh(root, env = process.env, deps = {}) {
+    const report = deps.writeError ?? writeError;
+    let entry;
+    try {
+        const currentEntry = deps.entryPath ?? process.argv[1];
+        if (!currentEntry)
+            throw new Error("process.argv[1] is empty");
+        entry = fs.realpathSync(currentEntry);
+    }
+    catch (err) {
+        report(`lanes snapshot refresh could not resolve the running CLI entry: ${errorMessage(err)}`);
+        return;
+    }
+    let lock;
+    let filePath;
+    try {
+        filePath = outpostSnapshotRefreshLockPath(root, env);
+        lock = acquireLock(root, env, deps);
+    }
+    catch (err) {
+        report(`lanes snapshot refresh could not acquire its lock: ${errorMessage(err)}`);
+        return;
+    }
+    if (!lock)
+        return;
+    let child;
+    try {
+        const childEnv = {
+            ...env,
+            HQ_ROOT: root,
+            HQ_NO_UPDATE_CHECK: "1",
+            HQ_INTERNAL_LANES_REFRESH_REMOTE_SNAPSHOT: "1",
+            [CHILD_LOCK_PATH_ENV]: filePath,
+            [CHILD_LOCK_TOKEN_ENV]: lock.token,
+        };
+        const spawnChild = deps.spawn ?? spawn;
+        child = spawnChild(process.execPath, [...process.execArgv, entry, "lanes", "list", "--json"], {
+            cwd: root,
+            detached: true,
+            stdio: ["ignore", "ignore", "inherit"],
+            env: childEnv,
+        });
+        child.once("error", (err) => {
+            releaseLock(filePath, lock.token);
+            report(`lanes snapshot refresh could not start: ${errorMessage(err)}`);
+        });
+        if (child.pid)
+            updateLockOwner(filePath, lock.token, child.pid);
+        child.unref();
+    }
+    catch (err) {
+        try {
+            child?.kill();
+        }
+        catch {
+            // Spawn failure is already reported below; the lock is still released.
+        }
+        releaseLock(filePath, lock.token);
+        report(`lanes snapshot refresh could not start: ${errorMessage(err)}`);
+    }
+}
+/** Adopt the launcher lock in the detached child and remove it on normal exit. */
+export function registerOutpostLaneSnapshotRefreshChild(env = process.env, runtime = process) {
+    const filePath = env[CHILD_LOCK_PATH_ENV];
+    const token = env[CHILD_LOCK_TOKEN_ENV];
+    if (!filePath && !token)
+        return false;
+    if (!filePath || !token) {
+        writeError("lanes snapshot refresh child has incomplete lock metadata");
+        return false;
+    }
+    try {
+        updateLockOwner(filePath, token, runtime.pid);
+    }
+    catch (err) {
+        writeError(`lanes snapshot refresh child could not register its lock: ${errorMessage(err)}`);
+        return false;
+    }
+    runtime.once("exit", () => releaseLock(filePath, token));
+    return true;
+}
+//# sourceMappingURL=outpost-snapshot-refresh.js.map