@indigoai-us/hq-cli 5.345.160 → 5.345.161

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

@@ -20,6 +20,8 @@ export interface LinkOptions {
     timeout?: number;
     event?: string;
     input?: string;
+    ackMode?: string;
+    claims?: string;
     now?: () => Date;
     sleep?: (milliseconds: number) => Promise<void>;
 }
@@ -31,7 +33,6 @@ export declare function resolveLinkSessionId(root: string, explicit: string | un
 /** Cheap hook guard used before remote flag lookup or queue access. */
 export declare function linkedSessionIdFromHookInput(input: string): string;
 export declare function isLinkedSession(root: string, sid: string): boolean;
-/** Claims pending files by renaming the whole queue, matching conduct-inbox's no-loss drain. */
 export declare function drainLinkQueue(inbox: string): string;
 export declare function runLaneLink(subcommand: string, options: LinkOptions): Promise<LinkResult>;
 /** Apply the default-on feature gate contract at the command boundary. */

package/dist/lib/lanes/links.js

@@ -2,6 +2,8 @@ import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { appendDropboxMessageAtPath } from "./dropbox.js";
+import { withLaneRecordFileLock } from "./store.js";
+import { LanesError } from "./errors.js";
 export const LANE_SESSION_LINKS_FLAG = "lanes.session-links";
 const ID_PATTERN = /^[A-Za-z0-9._-]+$/;
 export class LaneLinkError extends Error {
@@ -132,6 +134,17 @@ function resolvePointer(root, sid, role, options) {
 function queueDir(root, link, child) {
     return path.join(rootDir(root), link, child ? "children" : "up", ...(child ? [child] : []), "inbox");
 }
+function withLinkQueueLock(inbox, fn) {
+    try {
+        return withLaneRecordFileLock(path.join(inbox, "queue"), fn, { reclaimByAge: false });
+    }
+    catch (error) {
+        if (error instanceof LanesError && error.error === "store_lock_timeout") {
+            throw new LaneLinkError("queue_busy", "Conductor queue busy; instructions retained");
+        }
+        throw error;
+    }
+}
 function sendQueue(root, link, child, text) {
     const inbox = queueDir(root, link, child);
     const pending = path.join(inbox, "pending");
@@ -139,10 +152,12 @@ function sendQueue(root, link, child, text) {
     // Reuse hq monitor's session-inbox append primitive; the pending directory is
     // still claimed as a whole below, keeping conduct-inbox's no-loss handoff.
     const cleanText = text.replaceAll("\0", "").replaceAll("\u000b", "").replaceAll("\u000c", "").replaceAll("\r", "");
-    appendDropboxMessageAtPath(pending, { at: new Date().toISOString(), text: cleanText });
+    withLinkQueueLock(inbox, () => {
+        appendDropboxMessageAtPath(pending, { at: new Date().toISOString(), text: cleanText });
+    });
 }
 /** Claims pending files by renaming the whole queue, matching conduct-inbox's no-loss drain. */
-export function drainLinkQueue(inbox) {
+function drainLinkQueueUnlocked(inbox) {
     const pending = path.join(inbox, "pending");
     const claimedRoot = path.join(inbox, "claimed");
     // Recover claims interrupted before the delivery result was committed. This is
@@ -190,16 +205,197 @@ export function drainLinkQueue(inbox) {
     fs.writeFileSync(path.join(claim, ".consumed"), "delivered\n", { mode: 0o600 });
     return messages;
 }
+export function drainLinkQueue(inbox) {
+    return withLinkQueueLock(inbox, () => drainLinkQueueUnlocked(inbox));
+}
+/** Claims remain replayable until the recipient explicitly accepts instructions.
+ * This is at-least-once transport, not proof of a native turn or execution.
+ */
+function claimLinkQueueUnlocked(inbox) {
+    const pending = path.join(inbox, "pending");
+    const claimed = path.join(inbox, "unaccepted");
+    fs.mkdirSync(claimed, { recursive: true });
+    if (fs.existsSync(path.join(pending, "inbox.jsonl"))) {
+        // Allocate while holding the queue lock. Wall time alone can repeat or
+        // move backward, and pid/random suffixes do not preserve claim order.
+        let serial = 0n;
+        for (const previous of fs.readdirSync(claimed)) {
+            const prefix = /^(\d{1,16})-/.exec(previous)?.[1];
+            if (prefix && BigInt(prefix) > serial)
+                serial = BigInt(prefix);
+        }
+        const wall = Date.now();
+        if (!Number.isSafeInteger(wall) || wall < 0)
+            throw new LaneLinkError("claim_clock_invalid", "Cannot allocate a safe receipt serial");
+        serial = BigInt(wall) > serial ? BigInt(wall) : serial + 1n;
+        if (serial > 9999999999999999n)
+            throw new LaneLinkError("claim_serial_exhausted", "Receipt serial exhausted; instructions retained");
+        const id = `${serial.toString().padStart(16, "0")}-${process.pid}-${randomBytes(8).toString("hex")}`;
+        const dir = path.join(claimed, id);
+        fs.mkdirSync(dir);
+        // The shared queue lock joins the producer's open/write/close before this
+        // immutable snapshot is read. Keep the producer directory stable too.
+        try {
+            fs.renameSync(path.join(pending, "inbox.jsonl"), path.join(dir, "inbox.jsonl"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const claims = [];
+    const messages = [];
+    const ordered = fs.readdirSync(claimed).sort((a, b) => {
+        const left = /^(\d{1,16})-/.exec(a)?.[1];
+        const right = /^(\d{1,16})-/.exec(b)?.[1];
+        if (left && right && BigInt(left) !== BigInt(right))
+            return BigInt(left) < BigInt(right) ? -1 : 1;
+        return a.localeCompare(b);
+    });
+    for (const id of ordered) {
+        if (!safeId(id))
+            continue;
+        const dir = path.join(claimed, id);
+        if (fs.existsSync(path.join(dir, ".consumed")))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, "inbox.jsonl"), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const rows = [];
+        const invalidRows = [];
+        text.split(/\r?\n/).forEach((line, index) => {
+            if (!line)
+                return;
+            try {
+                const row = JSON.parse(line);
+                if (!row || typeof row !== "object" || typeof row.text !== "string")
+                    throw new Error("invalid row");
+                rows.push(row.text);
+            }
+            catch {
+                invalidRows.push(index + 1);
+            }
+        });
+        if (invalidRows.length) {
+            // The immutable original is the quarantine evidence. Record positions,
+            // never malformed contents, and retain both even after valid rows' ACK.
+            const audit = path.join(dir, "invalid-rows.json");
+            const expectedAudit = JSON.stringify({ version: 1, rows: invalidRows }) + "\n";
+            let previousAudit;
+            try {
+                previousAudit = fs.readFileSync(audit, "utf8");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            if (previousAudit !== expectedAudit) {
+                const temporary = `${audit}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+                try {
+                    const fd = fs.openSync(temporary, "wx", 0o600);
+                    try {
+                        fs.writeFileSync(fd, expectedAudit);
+                        fs.fsyncSync(fd);
+                    }
+                    finally {
+                        fs.closeSync(fd);
+                    }
+                    fs.renameSync(temporary, audit);
+                }
+                finally {
+                    fs.rmSync(temporary, { force: true });
+                }
+            }
+            // Retry all durability barriers even if a previous attempt wrote the
+            // audit but failed before publishing its directory entry durably.
+            for (const file of [path.join(dir, "inbox.jsonl"), audit]) {
+                const fd = fs.openSync(file, "r");
+                try {
+                    fs.fsyncSync(fd);
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+            }
+            for (const directory of [dir, claimed]) {
+                try {
+                    const fd = fs.openSync(directory, "r");
+                    try {
+                        fs.fsyncSync(fd);
+                    }
+                    finally {
+                        fs.closeSync(fd);
+                    }
+                }
+                catch (error) {
+                    // Same known unsupported directory-flush codes as lanes store.
+                    // File flush errors and unknown directory errors remain fatal.
+                    if (!["EISDIR", "EINVAL", "ENOTSUP"].includes(error.code ?? ""))
+                        throw error;
+                }
+            }
+        }
+        if (!rows.length)
+            continue;
+        claims.push(id);
+        messages.push(...rows);
+    }
+    return { messages: messages.join("\n"), claims };
+}
+function claimLinkQueue(inbox) {
+    return withLinkQueueLock(inbox, () => claimLinkQueueUnlocked(inbox));
+}
+function acknowledgeLinkClaims(inbox, claims) {
+    return withLinkQueueLock(inbox, () => acknowledgeLinkClaimsUnlocked(inbox, claims));
+}
+function acknowledgeLinkClaimsUnlocked(inbox, claims) {
+    if (!Array.isArray(claims) || !claims.length || claims.some(id => typeof id !== "string" || !safeId(id))) {
+        throw new LaneLinkError("claim_invalid", "An exact nonempty claim receipt is required");
+    }
+    // Validate the entire receipt before changing any claim. Never resolve paths
+    // outside the current session's authoritative queue.
+    for (const id of claims) {
+        if (!fs.existsSync(path.join(inbox, "unaccepted", id, "inbox.jsonl"))) {
+            throw new LaneLinkError("claim_not_found", "Claim does not belong to this queue");
+        }
+    }
+    for (const id of claims) {
+        fs.writeFileSync(path.join(inbox, "unaccepted", id, ".consumed"), "recipient-accepted\n", { mode: 0o600 });
+    }
+}
+function countQuarantined(inbox) {
+    const claims = path.join(inbox, "unaccepted");
+    if (!fs.existsSync(claims))
+        return 0;
+    return fs.readdirSync(claims).filter(id => safeId(id) && fs.existsSync(path.join(claims, id, "invalid-rows.json"))).length;
+}
 function countPending(inbox) {
-    const payload = path.join(inbox, "pending", "inbox.jsonl");
-    try {
-        return fs.readFileSync(payload, "utf8").split(/\r?\n/).filter(Boolean).length;
+    const paths = [path.join(inbox, "pending", "inbox.jsonl")];
+    for (const name of ["claimed", "unaccepted"]) {
+        const claimed = path.join(inbox, name);
+        if (fs.existsSync(claimed))
+            for (const id of fs.readdirSync(claimed)) {
+                if (!fs.existsSync(path.join(claimed, id, ".consumed")))
+                    paths.push(path.join(claimed, id, "inbox.jsonl"));
+            }
     }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return 0;
-        throw error;
+    let count = 0;
+    for (const file of paths) {
+        try {
+            count += fs.readFileSync(file, "utf8").split(/\r?\n/).filter(Boolean).length;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
     }
+    return count;
 }
 function readText(options) {
     if (options.textFile) {
@@ -244,7 +440,7 @@ function listChildren(root, dir) {
         if (!fs.existsSync(metaPath))
             return [];
         const unread = countPending(path.join(cdir, "inbox"));
-        return [{ ...readJson(metaPath), undelivered: unread }];
+        return [{ ...readJson(metaPath), undelivered: unread, quarantined_claims: countQuarantined(path.join(cdir, "inbox")) }];
     });
 }
 async function waitForReport(dir, timeoutSeconds, sleep) {
@@ -288,6 +484,7 @@ export async function runLaneLink(subcommand, options) {
     const root = options.hqRoot;
     let sid = "";
     let childContext = false;
+    let stopHookActive = false;
     if (subcommand === "_deliver") {
         let payload = {};
         try {
@@ -299,6 +496,7 @@ export async function runLaneLink(subcommand, options) {
         const value = payload.session_id ?? payload.sessionId;
         sid = typeof value === "string" && safeId(value) ? value : "";
         childContext = isChildHookPayload(payload);
+        stopHookActive = payload.stop_hook_active === true || payload.stopHookActive === true;
     }
     const requireSid = () => sid || (sid = resolveLinkSessionId(root, options.sessionId, env));
     const links = rootDir(root);
@@ -307,21 +505,41 @@ export async function runLaneLink(subcommand, options) {
         // drain the root's queue into the subagent, so leave the message queued.
         if (!sid || childContext || !["PostToolUse", "Stop"].includes(options.event ?? ""))
             return {};
-        if (options.event === "Stop" && env.HQ_STOP_DECISION_DELIVERABLE === "0")
+        if (options.event === "Stop" && (stopHookActive || env.HQ_STOP_DECISION_DELIVERABLE === "0"))
             return {};
         const pointer = readPointer(root, sid);
         if (!pointer)
             return {};
         const target = hookMessage(root, pointer);
-        const messages = drainLinkQueue(target.inbox);
+        if (options.ackMode !== undefined && options.ackMode !== "explicit")
+            throw new LaneLinkError("ack_mode_invalid", "Unsupported acknowledgement mode");
+        const claim = options.ackMode === "explicit" ? claimLinkQueue(target.inbox) : undefined;
+        const messages = claim ? claim.messages : drainLinkQueue(target.inbox);
         if (!messages)
             return {};
-        const body = target.role === "conductor"
+        const receipt = claim ? { _hqLinkDelivery: { version: 1, sessionId: sid, link: pointer.link, child: pointer.name ?? null, claims: claim.claims } } : {};
+        const acceptance = claim ? `\n\n[conduct receipt] Stable instruction receipt IDs: ${claim.claims.join(",")}. Treat replayed IDs as the same instruction, not new execution authority. After accepting these instructions, acknowledge receipt once with: hq lanes link ack --session-id ${sid} --link ${pointer.link}${pointer.name ? ` --child ${pointer.name}` : ""} --claims ${claim.claims.join(",")}. Receipt acceptance does not approve actions, answer owner pickers, or mean work is completed.` : "";
+        const body = (target.role === "conductor"
             ? `[conduct] Sessions you are conducting reported while you were working.\nEach report names the session it came from. Relay what the operator needs to know, and answer a session with: hq lanes link send --child <name> --text '...'\n\n${messages}`
-            : `[conduct] The session conducting you sent this while you were working.\nTreat it as a new instruction from the operator, taking precedence over your current task where the two conflict. When you have something to tell the conductor - a result, a blocker, a question - send it with: hq lanes link report --state <working|blocked|idle|done> --text '...'\n\n${messages}`;
+            : `[conduct] The session conducting you sent this while you were working.\nTreat it as a new instruction from the operator, taking precedence over your current task where the two conflict. When you have something to tell the conductor - a result, a blocker, a question - send it with: hq lanes link report --state <working|blocked|idle|done> --text '...'\n\n${messages}`) + acceptance;
         return options.event === "PostToolUse"
-            ? { output: { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: body } } }
-            : { output: { decision: "block", reason: body } };
+            ? { output: { ...receipt, hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: body } } }
+            : { output: { ...receipt, decision: "block", reason: body } };
+    }
+    if (subcommand === "capabilities") {
+        return { output: { protocol: "conduct-recipient-acceptance/1", explicitClaim: true, recipientAck: true, idleWake: false } };
+    }
+    if (subcommand === "ack") {
+        const currentSid = requireSid();
+        const pointer = readPointer(root, currentSid);
+        if (!pointer)
+            throw new LaneLinkError("session_unlinked", "Session is not linked");
+        if (!options.link || options.link !== pointer.link || (options.child ?? null) !== (pointer.name ?? null)) {
+            throw new LaneLinkError("claim_owner_invalid", "Receipt does not match the current link/child binding");
+        }
+        const claims = options.claims?.split(",");
+        acknowledgeLinkClaims(hookMessage(root, pointer).inbox, claims);
+        return { output: { acknowledged: true, acceptance: "recipient_instruction_only" } };
     }
     if (subcommand === "open") {
         const sessionId = requireSid();
@@ -438,7 +656,7 @@ export async function runLaneLink(subcommand, options) {
         const dir = linkPath(root, link);
         const meta = readJson(path.join(dir, "meta.json"));
         const unread = countPending(path.join(dir, "up", "inbox"));
-        return { output: { ...meta, unread_reports: unread, children: listChildren(root, dir) } };
+        return { output: { ...meta, unread_reports: unread, quarantined_reports: countQuarantined(path.join(dir, "up", "inbox")), children: listChildren(root, dir) } };
     }
     if (subcommand === "leave") {
         const sessionId = requireSid();

package/dist/lib/lanes/registry-flag.d.ts

@@ -1,5 +1,6 @@
 import { type FlagClientOptions, type FlagResolution } from "@indigoai-us/hq-flags-client";
 import type { LaneCompanyRef } from "./types.js";
+import { type PersistedPersonFlagSnapshot } from "../flag-snapshot-file.js";
 export declare const LANES_FLAG_API_DEFAULT_ENDPOINT = "https://hqapi.hq.computer";
 export declare const LANES_FLAG_READ_TIMEOUT_MS = 5000;
 export interface LanesFlagClient {
@@ -64,5 +65,28 @@ export declare function readLanesRegistryFlagFailOpen(flagKey: string, options?:
  */
 export declare function readLanesRegistryFlagFailOff(flagKey: string, options?: ReadLanesFlagOptions, reader?: typeof readLanesRegistryFlag): Promise<boolean>;
 export declare function _resetThrownFlagReadWarningsForTests(): void;
+/** Offline value for a company-less lanes flag, with how long ago the registry confirmed it. */
+export interface OfflineLanesFlagRead {
+    value: boolean;
+    ageMs: number;
+    source: "local-override" | "lanes-cache" | "person-snapshot";
+}
+export interface ReadLanesFlagOfflineOptions {
+    defaultValue?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** Last-known-good cache directory; null disables it. Defaults to the HQ state dir. */
+    cacheDir?: string | null;
+    now?: number;
+    /** Person-scope flag snapshot reader. Defaults to the snapshot under the env's cache home. */
+    readPersonSnapshot?: () => PersistedPersonFlagSnapshot | null;
+}
+/**
+ * Read a company-less lanes flag without any network request. Order: local
+ * override, then the lanes last-known-good cache, then the person flag
+ * snapshot other hq commands keep (default registry endpoint only). Returns
+ * null when no value was confirmed within LANES_FLAG_CACHE_MAX_AGE_MS; the
+ * caller decides the fallback and whether to refresh in the background.
+ */
+export declare function readLanesRegistryFlagOffline(flagKey: string, options?: ReadLanesFlagOfflineOptions): OfflineLanesFlagRead | null;
 export declare function _resetLanesRegistryFlagCacheForTests(): void;
 //# sourceMappingURL=registry-flag.d.ts.map

package/dist/lib/lanes/registry-flag.js

@@ -1,8 +1,8 @@
 import { createFlagClient, readLocalOverride, } from "@indigoai-us/hq-flags-client";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { ensureCognitoIdToken, loadCachedTokens, refreshActivePersonTokens, wantsMachineCognitoTokens, } from "../../utils/cognito-session.js";
 import { FLAG_REGISTRY_DEFAULT_ENDPOINT, resolveFlagRegistryEndpoint, } from "../flag-registry-endpoint.js";
+import { readPersonFlagSnapshotFile } from "../flag-snapshot-file.js";
 export const LANES_FLAG_API_DEFAULT_ENDPOINT = FLAG_REGISTRY_DEFAULT_ENDPOINT;
 export const LANES_FLAG_READ_TIMEOUT_MS = 5_000;
 export function readLanesFlagLocalOverride(flagKey, env = process.env) {
@@ -55,7 +55,7 @@ function readFlagCacheFile(dir) {
         return {};
     }
 }
-function readCachedFlagValue(dir, key, now = Date.now()) {
+function readCachedFlagEntry(dir, key, now = Date.now()) {
     const entry = readFlagCacheFile(dir)[key];
     if (!entry || typeof entry.value !== "boolean" || typeof entry.resolvedAt !== "string")
         return null;
@@ -66,9 +66,15 @@ function readCachedFlagValue(dir, key, now = Date.now()) {
     // A future timestamp (clock skew or a hand-edited file) is not trusted either.
     if (age < 0 || age > LANES_FLAG_CACHE_MAX_AGE_MS)
         return null;
-    return entry.value;
+    return { value: entry.value, missing: entry.missing === true, ageMs: age };
 }
-function writeCachedFlagValue(dir, key, value) {
+function readCachedFlagValue(dir, key, defaultValue) {
+    const entry = readCachedFlagEntry(dir, key);
+    if (!entry)
+        return null;
+    return entry.missing ? defaultValue : entry.value;
+}
+function writeCachedFlagValue(dir, key, value, missing = false) {
     let tmp;
     try {
         const entries = readFlagCacheFile(dir);
@@ -76,7 +82,7 @@ function writeCachedFlagValue(dir, key, value) {
         // measures time since the registry last confirmed it. Delete first so the
         // key moves to the end and eviction drops the least recently confirmed.
         delete entries[key];
-        entries[key] = { value, resolvedAt: new Date().toISOString() };
+        entries[key] = { value, resolvedAt: new Date().toISOString(), ...(missing ? { missing: true } : {}) };
         const keys = Object.keys(entries);
         for (const stale of keys.slice(0, Math.max(0, keys.length - FLAG_CACHE_MAX_ENTRIES)))
             delete entries[stale];
@@ -237,7 +243,13 @@ function classifyAttempt(attempt) {
         return "transient";
     return "permanent";
 }
+// Loaded on first token use: the module costs ~350 ms to import, and offline
+// readers such as the SessionStart hook never need a token.
+function loadCognitoSession() {
+    return import("../../utils/cognito-session.js");
+}
 async function defaultRefreshToken() {
+    const { ensureCognitoIdToken, loadCachedTokens, refreshActivePersonTokens, wantsMachineCognitoTokens } = await loadCognitoSession();
     if (wantsMachineCognitoTokens()) {
         return ensureCognitoIdToken({ interactive: false });
     }
@@ -250,6 +262,7 @@ async function defaultRefreshToken() {
 function defaultAcquireToken() {
     return async () => {
         try {
+            const { ensureCognitoIdToken } = await loadCognitoSession();
             return await ensureCognitoIdToken({ interactive: false });
         }
         catch (error) {
@@ -388,7 +401,7 @@ async function readRegistryValue(flagKey, endpoint, key, options) {
         // 4xx, and a missing token mean the registry (or the session) refused the
         // read, so it fails closed to the caller's default instead.
         const transient = classifyAttempt(attempt) === "transient";
-        const cachedValue = transient && cacheDir ? readCachedFlagValue(cacheDir, key) : null;
+        const cachedValue = transient && cacheDir ? readCachedFlagValue(cacheDir, key, options.defaultValue ?? false) : null;
         if (cachedValue !== null) {
             return {
                 result: { state: "resolved", value: cachedValue },
@@ -397,8 +410,61 @@ async function readRegistryValue(flagKey, endpoint, key, options) {
         }
         return { result: { state: "unknown" }, failure: { ...attempt.failure, diagnostics } };
     }
+    // A clean read that fell back means the registry has no row for this flag.
+    // Remember that, so offline readers can apply their default without a request.
+    if (attempt.resolution?.source === "fallback" && cacheDir)
+        writeCachedFlagValue(cacheDir, key, attempt.resolution.value, true);
     return { result: { state: "resolved", value: attempt.resolution?.value ?? false } };
 }
+function defaultPersonSnapshotReader(env, now) {
+    return () => {
+        // Use only a cache home the env names, so a hermetic env never reads the real home.
+        const home = env.HOME?.trim() || env.USERPROFILE?.trim();
+        const cacheHome = env.XDG_CACHE_HOME?.trim() || (home ? path.join(home, ".cache") : "");
+        if (!cacheHome)
+            return null;
+        return readPersonFlagSnapshotFile({ env: { ...env, XDG_CACHE_HOME: cacheHome }, now, maxAgeMs: LANES_FLAG_CACHE_MAX_AGE_MS });
+    };
+}
+/**
+ * Read a company-less lanes flag without any network request. Order: local
+ * override, then the lanes last-known-good cache, then the person flag
+ * snapshot other hq commands keep (default registry endpoint only). Returns
+ * null when no value was confirmed within LANES_FLAG_CACHE_MAX_AGE_MS; the
+ * caller decides the fallback and whether to refresh in the background.
+ */
+export function readLanesRegistryFlagOffline(flagKey, options = {}) {
+    const env = options.env ?? process.env;
+    const defaultValue = options.defaultValue ?? false;
+    const now = options.now ?? Date.now();
+    const localOverride = readLanesFlagLocalOverride(flagKey, env);
+    if (localOverride !== null)
+        return { value: localOverride, ageMs: 0, source: "local-override" };
+    const endpoint = resolveFlagRegistryEndpoint(undefined, env);
+    const cacheDir = flagCacheDir({ env, ...(options.cacheDir !== undefined ? { cacheDir: options.cacheDir } : {}) });
+    const cached = cacheDir ? readCachedFlagEntry(cacheDir, cacheKey(flagKey, null, endpoint), now) : null;
+    let snapshot = null;
+    if (endpoint === FLAG_REGISTRY_DEFAULT_ENDPOINT) {
+        try {
+            snapshot = (options.readPersonSnapshot ?? defaultPersonSnapshotReader(env, now))();
+        }
+        catch {
+            snapshot = null;
+        }
+    }
+    const snapshotAge = snapshot ? now - Date.parse(snapshot.fetched_at) : Number.NaN;
+    const snapshotUsable = snapshot !== null && Number.isFinite(snapshotAge) && snapshotAge >= 0 &&
+        snapshotAge <= LANES_FLAG_CACHE_MAX_AGE_MS;
+    // Prefer whichever source the registry confirmed most recently.
+    if (cached && (!snapshotUsable || cached.ageMs <= snapshotAge)) {
+        return { value: cached.missing ? defaultValue : cached.value, ageMs: cached.ageMs, source: "lanes-cache" };
+    }
+    if (snapshotUsable) {
+        const value = snapshot.flags[flagKey];
+        return { value: typeof value === "boolean" ? value : defaultValue, ageMs: snapshotAge, source: "person-snapshot" };
+    }
+    return null;
+}
 function reportRegistryFailure(flagKey, key, outcome, options, failOpen) {
     if (!outcome.failure)
         return;

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

@@ -40,9 +40,11 @@ export declare function mintLaneId(deps?: Pick<StoreDeps, "now" | "hostname"> &
 export declare function mintQuestionId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
 export declare function appendCappedHistory<T>(history: readonly T[], entry: T, cap?: number): T[];
 /** Test seam: run withRecordLock with overridden deps and a shorter timeout. */
-export declare function withRecordLockForTests<T>(recordPath: string, overrides: Partial<StoreDeps>, fn: () => T, timeoutMs?: number): T;
+export declare function withRecordLockForTests<T>(recordPath: string, overrides: Partial<StoreDeps>, fn: () => T, timeoutMs?: number, reclaimByAge?: boolean): T;
 /** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
-export declare function withLaneRecordFileLock<T>(recordPath: string, fn: () => T): T;
+export declare function withLaneRecordFileLock<T>(recordPath: string, fn: () => T, options?: {
+    reclaimByAge?: boolean;
+}): T;
 export declare function parseLaneRecord(raw: unknown, filePath?: string): LaneRecord;
 export declare function parseQuestionRecord(raw: unknown, filePath?: string): QuestionRecord;
 /**

package/dist/lib/lanes/store.js

@@ -183,7 +183,7 @@ function sameFile(a, b) {
  * (another process reclaimed it and took a fresh lock in between), the fresh
  * lock is linked back into place and nothing is reclaimed.
  */
-function recordLockIsStale(lockPath, deps) {
+function recordLockIsStale(lockPath, deps, reclaimByAge = true) {
     const statSync = deps.statSync ?? ((p) => fs.statSync(p));
     const linkSync = deps.linkSync ?? fs.linkSync.bind(fs);
     const before = statSync(lockPath);
@@ -199,7 +199,7 @@ function recordLockIsStale(lockPath, deps) {
     const mtimeAge = now - before.mtimeMs;
     const age = Number.isFinite(ts) ? Math.max(now - ts, mtimeAge) : mtimeAge;
     const stale = (pidKnown && sameHost && pid !== process.pid && !lockOwnerAlive(pid)) ||
-        age > lockStaleMs();
+        (reclaimByAge && age > lockStaleMs());
     if (!stale)
         return false;
     const parked = `${lockPath}.stale.${process.pid}.${randomBytes(6).toString("hex")}`;
@@ -243,7 +243,7 @@ function recordLockIsStale(lockPath, deps) {
     removeParked();
     return reclaimed;
 }
-function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS) {
+function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS, reclaimByAge = true) {
     const lockPath = lockPathFor(recordPath);
     const statSync = deps.statSync ?? ((p) => fs.statSync(p));
     const fstatSync = deps.fstatSync ?? ((fd) => fs.fstatSync(fd));
@@ -295,7 +295,7 @@ function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS) {
                 throw new LanesError("store_lock_timeout", `Timed out waiting for lock ${lockPath}`, { path: lockPath });
             }
             try {
-                if (recordLockIsStale(lockPath, deps))
+                if (recordLockIsStale(lockPath, deps, reclaimByAge))
                     continue;
             }
             catch (statErr) {
@@ -309,12 +309,12 @@ function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS) {
     }
 }
 /** Test seam: run withRecordLock with overridden deps and a shorter timeout. */
-export function withRecordLockForTests(recordPath, overrides, fn, timeoutMs) {
-    return withRecordLock(recordPath, { ...defaultStoreDeps(), ...overrides }, fn, timeoutMs);
+export function withRecordLockForTests(recordPath, overrides, fn, timeoutMs, reclaimByAge = true) {
+    return withRecordLock(recordPath, { ...defaultStoreDeps(), ...overrides }, fn, timeoutMs, reclaimByAge);
 }
 /** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
-export function withLaneRecordFileLock(recordPath, fn) {
-    return withRecordLock(recordPath, defaultStoreDeps(), fn);
+export function withLaneRecordFileLock(recordPath, fn, options = {}) {
+    return withRecordLock(recordPath, defaultStoreDeps(), fn, LOCK_TIMEOUT_MS, options.reclaimByAge ?? true);
 }
 function readJsonFile(filePath, deps) {
     let text;

package/dist/lib/windows/ps1-shims.d.ts

@@ -0,0 +1,60 @@
+/** hq-cli's own bins and the package file each npm launcher runs. */
+export declare const HQ_CLI_BINS: Readonly<Record<string, string>>;
+/**
+ * True when `content` is npm's (cmd-shim) PowerShell launcher for the hq-cli
+ * bin `bin`. The launcher resolves its own folder, runs node on
+ * `$basedir/node_modules/@indigoai-us/hq-cli/<entry>` and exits with node's
+ * code. Either slash direction is accepted.
+ */
+export declare function isNpmGeneratedHqCliPs1Shim(content: string, bin: string): boolean;
+export interface Ps1ShimFs {
+    readFile: (file: string) => string;
+    remove: (file: string) => void;
+}
+/** The npm-generated hq-cli `.ps1` launchers present in `binDir`. */
+export declare function findHqCliPs1Shims(binDir: string, io?: Ps1ShimFs): string[];
+export interface RemovePs1ShimsResult {
+    /** Launchers removed by this call. */
+    removed: string[];
+    /** `.ps1` files with an hq-cli bin name that are not npm's launcher. */
+    kept: string[];
+    /** Launchers that could not be removed, with the reason. */
+    failed: Array<{
+        file: string;
+        reason: string;
+    }>;
+}
+/**
+ * Remove the npm-generated `.ps1` launchers for hq-cli's bins from `binDir`
+ * (the npm global prefix on Windows). Safe to run again: a missing file is
+ * not an error. Never touches another package's `.ps1` or a hand-written one.
+ */
+export declare function removeHqCliPs1Shims(binDir: string, io?: Ps1ShimFs): RemovePs1ShimsResult;
+/**
+ * True when the effective execution policy blocks npm's unsigned launcher.
+ * `Undefined` as the effective policy means no scope set one, which Windows
+ * client editions treat as `Restricted`.
+ */
+export declare function policyBlocksUnsignedScripts(policy: string): boolean;
+export type ExecutionPolicyRun = () => {
+    status: number | null;
+    stdout: string;
+};
+/**
+ * Read the current user's effective PowerShell execution policy. Read-only:
+ * it runs `Get-ExecutionPolicy` and never sets anything. Null when
+ * PowerShell could not be run or printed nothing usable.
+ */
+export declare function readExecutionPolicy(run?: ExecutionPolicyRun): string | null;
+/**
+ * Postinstall entry: after a global npm install on Windows, remove hq-cli's
+ * `.ps1` launchers from the prefix holding `packageDir`. Acts only when the
+ * package sits at `<prefix>/node_modules/@indigoai-us/hq-cli`, npm's Windows
+ * global layout. Null when it did nothing. npm 11.16+ may skip lifecycle
+ * scripts, so `hq doctor` reports any launcher left behind.
+ */
+export declare function removePs1ShimsAfterNpmInstall(packageDir: string, opts: {
+    platform: NodeJS.Platform;
+    global: boolean;
+}, io?: Ps1ShimFs): RemovePs1ShimsResult | null;
+//# sourceMappingURL=ps1-shims.d.ts.map