@indigoai-us/hq-cli 5.286.0 → 5.288.0

package/dist/lib/lanes/dropbox.d.ts

@@ -8,7 +8,6 @@
  * overlap.
  */
 import * as fs from "node:fs";
-import { probeProviderCompactionsSince } from "./compaction.js";
 import { tryReadLane } from "./store.js";
 import { type LaneRecord, type LaneState, type QuestionRecord } from "./types.js";
 export declare const DROPBOX_DIR = "dropbox";
@@ -59,7 +58,7 @@ export interface LaneDrainHookInput {
 }
 export interface RunDrainHookDeps {
     readLane?: typeof tryReadLane;
-    probeCompactionsSince?: typeof probeProviderCompactionsSince;
+    probeCompactionsSince?: typeof import("./compaction.js").probeProviderCompactionsSince;
 }
 export declare function mintClaimId(): string;
 export declare function assertSafeLaneId(laneId: string): void;

package/dist/lib/lanes/dropbox.js

@@ -10,9 +10,8 @@
 import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { probeProviderCompactionsSince, providerTranscriptSize, } from "./compaction.js";
 import { LanesError } from "./errors.js";
-import { MESSAGE_COMPACTION_REPLAY_NOTE, MESSAGE_REPLAY_STATE_NAME, } from "./message-replay.js";
+import { MESSAGE_COMPACTION_REPLAY_NOTE, MESSAGE_REPLAY_STATE_NAME, readMessageReplayState, updateMessageReplayTranscript, writeMessageReplayState, } from "./message-replay.js";
 import { LANES_RUNS_REL, readProcStarttime } from "./spawn.js";
 import { tryReadLane } from "./store.js";
 export const DROPBOX_DIR = "dropbox";
@@ -430,83 +429,6 @@ export function hookAdditionalContextJson(messages, hookEventName = "PreToolUse"
 function replayStatePath(hqRoot, laneId) {
     return path.join(dropboxDir(hqRoot, laneId), MESSAGE_REPLAY_STATE_NAME);
 }
-function safeProviderTranscriptPath(transcriptPath, provider, env) {
-    if (provider === "grok")
-        return transcriptPath;
-    const home = provider === "claude" ? env.CLAUDE_CONFIG_DIR : env.CODEX_HOME;
-    if (!home) {
-        throw new LanesError("message_replay_provider_home_missing", `Cannot validate ${provider} transcript without its provider home`);
-    }
-    if (!path.isAbsolute(transcriptPath) || path.extname(transcriptPath) !== ".jsonl") {
-        throw new LanesError("message_replay_transcript_path_invalid", `The ${provider} hook transcript path must be an absolute JSONL path`);
-    }
-    const configuredHomePath = path.resolve(home);
-    const homePath = fs.realpathSync(home);
-    const candidate = path.resolve(transcriptPath);
-    const expectedRoot = provider === "claude" ? "projects" : "sessions";
-    const assertWithinProviderHome = (root, resolvedTranscript, message) => {
-        const relative = path.relative(root, resolvedTranscript);
-        if (relative === "" ||
-            relative === ".." ||
-            relative.startsWith(`..${path.sep}`) ||
-            path.isAbsolute(relative) ||
-            relative.split(path.sep)[0] !== expectedRoot) {
-            throw new LanesError("message_replay_transcript_outside_provider_home", message);
-        }
-    };
-    try {
-        const realTranscript = fs.realpathSync(candidate);
-        assertWithinProviderHome(homePath, realTranscript, `The ${provider} hook transcript resolves outside its ${expectedRoot} directory`);
-        return realTranscript;
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            assertWithinProviderHome(configuredHomePath, candidate, `The ${provider} hook transcript is outside its configured ${expectedRoot} directory`);
-            return candidate;
-        }
-        throw err;
-    }
-}
-function readReplayState(filePath, turnId) {
-    const text = fs.readFileSync(filePath, "utf8");
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch (err) {
-        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is not an object`);
-    }
-    const state = parsed;
-    if (state.schema_version !== 1 ||
-        state.turn_id !== turnId ||
-        (state.last_compaction_marker !== null &&
-            (!Number.isSafeInteger(state.last_compaction_marker) || Number(state.last_compaction_marker) < 0)) ||
-        (state.transcript_offset !== undefined &&
-            (!Number.isSafeInteger(state.transcript_offset) || Number(state.transcript_offset) < 0)) ||
-        (state.transcript_path !== undefined && typeof state.transcript_path !== "string") ||
-        (state.flag_enabled !== undefined && typeof state.flag_enabled !== "boolean")) {
-        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} does not match the current provider turn`);
-    }
-    // Older state files persisted the removed per-turn flag. Accept it, but
-    // remove it before the next write so the stale cache does not live on.
-    delete state.flag_enabled;
-    return state;
-}
-function writeReplayState(filePath, state) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const tempPath = `${filePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
-    fs.writeFileSync(tempPath, `${JSON.stringify(state)}\n`, { mode: 0o600 });
-    try {
-        fs.renameSync(tempPath, filePath);
-    }
-    catch (err) {
-        fs.rmSync(tempPath, { force: true });
-        throw err;
-    }
-}
 function deliveredMessagesForTurn(hqRoot, laneId, turnId) {
     const delivered = path.join(dropboxDir(hqRoot, laneId), DELIVERED_DIR);
     let names;
@@ -522,7 +444,8 @@ function deliveredMessagesForTurn(hqRoot, laneId, turnId) {
     return names.flatMap((name) => readClaimedFile(path.join(delivered, name), defaultDrainDeps()));
 }
 function reportReplayFailure(err) {
-    return `hq-lanes-drain: message compaction replay failed: ${err instanceof Error ? err.message : String(err)}\n`;
+    const code = err instanceof LanesError ? `${err.error}: ` : "";
+    return `hq-lanes-drain: message compaction replay failed: ${code}${err instanceof Error ? err.message : String(err)}\n`;
 }
 /**
  * Hook protocol. HQ_LANE_ID absent or empty → exit 0, empty stdout, empty stderr.
@@ -564,7 +487,7 @@ export async function runDrainHook(env, input = {}, deps = {}) {
                 const statePath = replayStatePath(hqRoot, laneId);
                 let state;
                 try {
-                    state = readReplayState(statePath, turnId);
+                    state = readMessageReplayState(statePath, turnId);
                 }
                 catch (err) {
                     if (err.code !== "ENOENT")
@@ -576,38 +499,14 @@ export async function runDrainHook(env, input = {}, deps = {}) {
                     if (!lane) {
                         throw new LanesError("message_replay_lane_missing", `Lane ${laneId} could not be read for compaction replay`);
                     }
-                    if (lane.provider === "grok") {
-                        state.last_compaction_marker = 0;
-                    }
-                    else {
-                        const transcriptPath = safeProviderTranscriptPath(input.transcript_path, lane.provider, env);
-                        if (state.last_compaction_marker === null ||
-                            state.transcript_path !== transcriptPath ||
-                            state.transcript_offset === undefined) {
-                            // Existing transcript history belongs to the turn's resume
-                            // prompt. Start watching only records appended from this point.
-                            state.last_compaction_marker = 0;
-                            state.transcript_path = transcriptPath;
-                            state.transcript_offset = providerTranscriptSize(transcriptPath);
-                        }
-                        else {
-                            const delta = (deps.probeCompactionsSince ?? probeProviderCompactionsSince)(transcriptPath, lane.provider, state.transcript_offset);
-                            state.transcript_offset = delta.next_offset;
-                            if (delta.replaced) {
-                                // A replaced or truncated transcript establishes a new
-                                // baseline; it is not evidence of a fresh compaction.
-                                state.last_compaction_marker = 0;
-                            }
-                            else if (delta.count > 0) {
-                                state.last_compaction_marker += delta.count;
-                                replayed = deliveredMessagesForTurn(hqRoot, laneId, turnId);
-                                if (replayed.length > 0)
-                                    replayNote = MESSAGE_COMPACTION_REPLAY_NOTE;
-                            }
-                        }
+                    const update = updateMessageReplayTranscript(state, input.transcript_path, lane.provider, env, deps.probeCompactionsSince);
+                    if (update === "compacted") {
+                        replayed = deliveredMessagesForTurn(hqRoot, laneId, turnId);
+                        if (replayed.length > 0)
+                            replayNote = MESSAGE_COMPACTION_REPLAY_NOTE;
                     }
                 }
-                writeReplayState(statePath, state);
+                writeMessageReplayState(statePath, state);
             }
             catch (err) {
                 // Replay is advisory hook context. Report failures but let the provider

package/dist/lib/lanes/message-replay.d.ts

@@ -1,3 +1,5 @@
+import { probeProviderCompactionsSince } from "./compaction.js";
+import type { LaneProvider } from "./types.js";
 export declare const MESSAGE_REPLAY_STATE_NAME = "message-compaction-replay.json";
 export declare const MESSAGE_COMPACTION_REPLAY_NOTE = "These messages were delivered before a context compaction and still apply.";
 export interface MessageReplayState {
@@ -9,5 +11,11 @@ export interface MessageReplayState {
     transcript_offset?: number;
     /** Canonical transcript path for this provider turn. */
     transcript_path?: string;
+    /** Provider needed to inspect appended transcript records without loading the lane store. */
+    provider?: LaneProvider;
 }
+export type ReplayTranscriptUpdate = "baseline" | "unchanged" | "replaced" | "compacted";
+export declare function readMessageReplayState(filePath: string, turnId: string, onLegacyFlag?: () => void): MessageReplayState;
+export declare function writeMessageReplayState(filePath: string, state: MessageReplayState): void;
+export declare function updateMessageReplayTranscript(state: MessageReplayState, transcriptPath: string, provider: LaneProvider, env: NodeJS.ProcessEnv, probe?: typeof probeProviderCompactionsSince): ReplayTranscriptUpdate;
 //# sourceMappingURL=message-replay.d.ts.map

package/dist/lib/lanes/message-replay.js

@@ -1,3 +1,122 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { probeProviderCompactionsSince, providerTranscriptSize, } from "./compaction.js";
+import { LanesError } from "./errors.js";
 export const MESSAGE_REPLAY_STATE_NAME = "message-compaction-replay.json";
 export const MESSAGE_COMPACTION_REPLAY_NOTE = "These messages were delivered before a context compaction and still apply.";
+export function readMessageReplayState(filePath, turnId, onLegacyFlag) {
+    const text = fs.readFileSync(filePath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is not an object`);
+    }
+    const state = parsed;
+    if (state.schema_version !== 1 ||
+        state.turn_id !== turnId ||
+        (state.last_compaction_marker !== null &&
+            (!Number.isSafeInteger(state.last_compaction_marker) || Number(state.last_compaction_marker) < 0)) ||
+        (state.transcript_offset !== undefined &&
+            (!Number.isSafeInteger(state.transcript_offset) || Number(state.transcript_offset) < 0)) ||
+        (state.transcript_path !== undefined && typeof state.transcript_path !== "string") ||
+        (state.provider !== undefined && !isLaneProvider(state.provider)) ||
+        (state.flag_enabled !== undefined && typeof state.flag_enabled !== "boolean")) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} does not match the current provider turn`);
+    }
+    // Older state files persisted the removed per-turn flag. Accept it, but
+    // remove it before the next write so the stale cache does not live on.
+    if (state.flag_enabled !== undefined) {
+        delete state.flag_enabled;
+        onLegacyFlag?.();
+    }
+    return state;
+}
+function isLaneProvider(value) {
+    return value === "claude" || value === "codex" || value === "grok";
+}
+export function writeMessageReplayState(filePath, state) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    fs.writeFileSync(tempPath, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    try {
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        fs.rmSync(tempPath, { force: true });
+        throw err;
+    }
+}
+function safeProviderTranscriptPath(transcriptPath, provider, env) {
+    if (provider === "grok")
+        return transcriptPath;
+    const home = provider === "claude" ? env.CLAUDE_CONFIG_DIR : env.CODEX_HOME;
+    if (!home) {
+        throw new LanesError("message_replay_provider_home_missing", `Cannot validate ${provider} transcript without its provider home`);
+    }
+    if (!path.isAbsolute(transcriptPath) || path.extname(transcriptPath) !== ".jsonl") {
+        throw new LanesError("message_replay_transcript_path_invalid", `The ${provider} hook transcript path must be an absolute JSONL path`);
+    }
+    const configuredHomePath = path.resolve(home);
+    const homePath = fs.realpathSync(home);
+    const candidate = path.resolve(transcriptPath);
+    const expectedRoot = provider === "claude" ? "projects" : "sessions";
+    const assertWithinProviderHome = (root, resolvedTranscript, message) => {
+        const relative = path.relative(root, resolvedTranscript);
+        if (relative === "" ||
+            relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative) ||
+            relative.split(path.sep)[0] !== expectedRoot) {
+            throw new LanesError("message_replay_transcript_outside_provider_home", message);
+        }
+    };
+    try {
+        const realTranscript = fs.realpathSync(candidate);
+        assertWithinProviderHome(homePath, realTranscript, `The ${provider} hook transcript resolves outside its ${expectedRoot} directory`);
+        return realTranscript;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            assertWithinProviderHome(configuredHomePath, candidate, `The ${provider} hook transcript is outside its configured ${expectedRoot} directory`);
+            return candidate;
+        }
+        throw err;
+    }
+}
+export function updateMessageReplayTranscript(state, transcriptPath, provider, env, probe = probeProviderCompactionsSince) {
+    if (provider === "grok") {
+        state.provider = provider;
+        state.last_compaction_marker = 0;
+        return "unchanged";
+    }
+    const canonicalPath = safeProviderTranscriptPath(transcriptPath, provider, env);
+    const providerChanged = state.provider !== undefined && state.provider !== provider;
+    state.provider = provider;
+    if (providerChanged ||
+        state.last_compaction_marker === null ||
+        state.transcript_path !== canonicalPath ||
+        state.transcript_offset === undefined) {
+        state.last_compaction_marker = 0;
+        state.transcript_path = canonicalPath;
+        state.transcript_offset = providerTranscriptSize(canonicalPath);
+        return "baseline";
+    }
+    const delta = probe(canonicalPath, provider, state.transcript_offset);
+    state.transcript_offset = delta.next_offset;
+    if (delta.replaced) {
+        state.last_compaction_marker = 0;
+        return "replaced";
+    }
+    if (delta.count > 0) {
+        state.last_compaction_marker += delta.count;
+        return "compacted";
+    }
+    return "unchanged";
+}
 //# sourceMappingURL=message-replay.js.map

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