@indigoai-us/hq-cli 5.345.159 → 5.345.161

package/dist/lib/hook-engine/resolve.d.ts

@@ -1,3 +1,4 @@
+import { type SpawnSyncReturns } from 'node:child_process';
 export declare const HOOK_ENGINE_REPAIR = "npm install -g @indigoai-us/hq-cli --include=optional";
 export declare const HOOK_ENGINE_REPAIR_PIN = "hq core hook-engine-path --repair";
 export interface EngineOptions {
@@ -23,6 +24,19 @@ export declare function pinnedHookEngineMatches(engine: EnginePackage): boolean;
 export declare function findHookEngine(options?: EngineOptions): EnginePackage | null;
 /** Never truncate or replace a running Windows executable. */
 export declare function installHookEngine(options?: EngineOptions): string | null;
+/** master-hook.sh reads this one-line file with shell builtins to find the
+ * pinned engine without starting Node (US-021 bridge). It always names the
+ * engine of the CLI that wrote it, so a CLI update retargets it. */
+export declare function hookEnginePointerPath(options?: EngineOptions): string;
+/** Best effort and atomic: a missing pointer only keeps the bridge off. */
+export declare function writeHookEnginePointer(pinned: string, options?: EngineOptions): void;
+export declare function removeHookEnginePointer(options?: EngineOptions): void;
+export interface VerifyOptions {
+    spawn?: (command: string, args: readonly string[]) => Pick<SpawnSyncReturns<string>, 'status' | 'stdout' | 'error'>;
+}
+/** Run the engine's own `--self-check` and read its report. Returns the
+ * problem as text, or null when the binary answers as an hq-hook engine. */
+export declare function verifyHookEngine(binary: string, options?: VerifyOptions): string | null;
 /** Call only after settings no longer reference these old versions. Windows
  * refuses unlink of a mapped executable; a busy version stays for a later pass.
  * POSIX permits unlink while running, so retain those versions conservatively.

package/dist/lib/hook-engine/resolve.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
-import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, unlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 const require = createRequire(import.meta.url);
@@ -104,8 +105,61 @@ export function installHookEngine(options = {}) {
     if (!pinnedHookEngineMatches(engine)) {
         throw new Error(`Hook engine ${engine.version} differs from its pinned copy; close HQ sessions and repair with: ${HOOK_ENGINE_REPAIR_PIN}`);
     }
+    writeHookEnginePointer(engine.pinned, options);
     return engine.pinned;
 }
+/** master-hook.sh reads this one-line file with shell builtins to find the
+ * pinned engine without starting Node (US-021 bridge). It always names the
+ * engine of the CLI that wrote it, so a CLI update retargets it. */
+export function hookEnginePointerPath(options = {}) {
+    return join(options.home ?? homedir(), '.hq', 'bin', 'hq-hook', 'current');
+}
+/** Best effort and atomic: a missing pointer only keeps the bridge off. */
+export function writeHookEnginePointer(pinned, options = {}) {
+    const pointer = hookEnginePointerPath(options);
+    try {
+        mkdirSync(dirname(pointer), { recursive: true });
+        const stage = `${pointer}.${process.pid}.tmp`;
+        writeFileSync(stage, `${pinned}\n`);
+        renameSync(stage, pointer);
+    }
+    catch {
+        // The hook path falls back to bash when the pointer is absent.
+    }
+}
+export function removeHookEnginePointer(options = {}) {
+    try {
+        unlinkSync(hookEnginePointerPath(options));
+    }
+    catch { /* already absent */ }
+}
+/** Run the engine's own `--self-check` and read its report. Returns the
+ * problem as text, or null when the binary answers as an hq-hook engine. */
+export function verifyHookEngine(binary, options = {}) {
+    const spawn = options.spawn ?? ((command, args) => spawnSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 }));
+    let result;
+    try {
+        result = spawn(binary, ['--self-check']);
+    }
+    catch (error) {
+        return `hook engine self-check could not start: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    if (result.error)
+        return `hook engine self-check could not start: ${result.error.message}`;
+    let report;
+    try {
+        report = JSON.parse(String(result.stdout ?? '').trim().split('\n').pop() ?? '');
+    }
+    catch {
+        return `hook engine self-check printed no report (exit ${result.status ?? 'signal'})`;
+    }
+    if (report.engine !== 'hq-hook' || typeof report.version !== 'string' || typeof report.bridge_schema !== 'number') {
+        return 'hook engine self-check report is not from hq-hook';
+    }
+    if (result.status !== 0 || report.ok !== true)
+        return `hook engine self-check failed: ${typeof report.error === 'string' ? report.error : `exit ${result.status ?? 'signal'}`}`;
+    return null;
+}
 /** Call only after settings no longer reference these old versions. Windows
  * refuses unlink of a mapped executable; a busy version stays for a later pass.
  * POSIX permits unlink while running, so retain those versions conservatively.

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;
 /**