@indigoai-us/hq-cli 5.345.160 → 5.345.162

package/dist/lib/lanes/loop.js

@@ -1,5 +1,5 @@
 /** Durable envelope queue and runtime primitives for conduct worker lanes. */
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { providerSupportsSessionResume } from "./delivery.js";
@@ -14,6 +14,174 @@ export function loopAdmissionPath(state, hasPendingResume, initialAdmission) {
         return "deferred";
     return "resume";
 }
+export const HANDOFF_HOLD_CHOICES = [
+    "Use the repaired handoff without running the phase again",
+    "Retry the phase; I understand external effects may repeat",
+    "Keep this phase held",
+];
+function handoffHoldPath(runDir) { return path.join(runDir, "loop", "handoff-hold.json"); }
+function readHandoffHold(runDir) {
+    const file = handoffHoldPath(runDir);
+    if (!fs.existsSync(file))
+        return undefined;
+    const hold = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readHandoffBytes(file, LOOP_ENVELOPE_LIMIT * 8)));
+    if (!isRecord(hold) || hold.schema !== "hq-loop-handoff-hold.v1" || !nonEmpty(hold.envelope_id) || !nonEmpty(hold.question_id)) {
+        throw new Error("Invalid durable handoff hold; operator investigation required");
+    }
+    return hold;
+}
+async function notifyHandoffHold(options, hold, envelope) {
+    if (hold.notified || hold.resolution || !options.raiseQuestion)
+        return;
+    const record = envelope ? undefined : ["stalled", "active"].flatMap((dir) => envelopeFiles(path.join(options.runDir, "loop", dir)))
+        .map(fileEnvelope).find((entry) => entry.envelope_id === hold.envelope_id);
+    const heldEnvelope = envelope ?? record?.envelope;
+    if (!heldEnvelope)
+        throw new Error("Held handoff envelope is missing; cannot deliver its repair question");
+    await options.raiseQuestion({ envelope: heldEnvelope, envelopeId: hold.envelope_id, attempt: 1, error: hold.error, questionId: hold.question_id, reason: "handoff_needs_repair" });
+    const current = readHandoffHold(options.runDir);
+    if (current?.question_id === hold.question_id)
+        atomicJson(handoffHoldPath(options.runDir), { ...current, notified: true });
+}
+export function loopHandoffHoldIdentity(runDir) {
+    const hold = readHandoffHold(runDir);
+    return hold ? { envelope_id: hold.envelope_id, question_id: hold.question_id, unresolved: !hold.resolution } : undefined;
+}
+function readHandoffBytes(file, limit = LOOP_ENVELOPE_LIMIT) {
+    const before = fs.lstatSync(file);
+    if (!before.isFile())
+        throw new Error("Repaired handoff must be a bounded regular file");
+    if (!Number.isSafeInteger(before.ino) || before.ino <= 0 || !Number.isSafeInteger(before.dev))
+        throw new Error("Cannot establish handoff file identity on this filesystem");
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = fs.fstatSync(fd);
+        const current = fs.lstatSync(file);
+        if (!current.isFile() || stat.dev !== before.dev || stat.ino !== before.ino || current.dev !== stat.dev || current.ino !== stat.ino)
+            throw new Error("Handoff file identity changed while opening it");
+        if (!stat.isFile() || stat.size > limit)
+            throw new Error("Repaired handoff must be a bounded regular file");
+        const bytes = Buffer.alloc(limit + 1);
+        let count = 0;
+        while (count < bytes.length) {
+            const read = fs.readSync(fd, bytes, count, bytes.length - count, null);
+            if (read === 0)
+                break;
+            count += read;
+        }
+        if (count > limit)
+            throw new Error("Repaired handoff exceeds the 1 MiB limit");
+        return bytes.subarray(0, count);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function validateAcceptedHandoff(output, envelope) {
+    if (Buffer.byteLength(output, "utf8") > LOOP_ENVELOPE_LIMIT)
+        throw new Error("Repaired handoff exceeds the 1 MiB limit");
+    if (envelope.schema !== PHASE_ENVELOPE_SCHEMA)
+        throw new Error("Repair hold requires a section 8 phase");
+    const phase = envelope;
+    const handoff = validateSection8Handoff(JSON.parse(output), phase);
+    if (handoff.worker_id !== phase.worker_id || handoff.status !== "passed") {
+        throw new Error("Repaired handoff must match the worker and have passed status");
+    }
+    const criteria = phase.acceptance_criteria;
+    if (!Array.isArray(criteria) || !criteria.every((item) => typeof item === "string"))
+        throw new Error("Held phase requires string acceptance criteria");
+    if (!Array.isArray(handoff.ac_evidence))
+        throw new Error("Repaired handoff requires acceptance-criterion evidence");
+    for (let index = 0; index < criteria.length; index += 1) {
+        const evidence = handoff.ac_evidence.filter((item) => isRecord(item) && item.index === index);
+        if (evidence.length !== 1)
+            throw new Error(`Repaired handoff requires exactly one evidence entry for criterion ${index}`);
+        const item = evidence[0];
+        if (item.criterion !== criteria[index] || item.met !== true || !nonEmpty(item.evidence)) {
+            throw new Error(`Repaired handoff must copy criterion ${index} verbatim with met=true and string evidence`);
+        }
+    }
+    for (const item of handoff.ac_evidence) {
+        if (!isRecord(item) || !Number.isInteger(item.index) || Number(item.index) < 0 || Number(item.index) >= criteria.length) {
+            throw new Error("Repaired handoff contains an unknown criterion index");
+        }
+    }
+    return handoff;
+}
+function applyHandoffHoldAnswer(input) {
+    const release = acquireEnqueueLock(input.runDir);
+    try {
+        const hold = readHandoffHold(input.runDir);
+        if (!hold || hold.question_id !== input.questionId)
+            throw new Error("Handoff hold identity changed");
+        if (!HANDOFF_HOLD_CHOICES.includes(input.choice))
+            throw new Error("Choose an explicit handoff repair disposition");
+        if (loopStatus(input.runDir, path.basename(input.runDir)).state === "stopped")
+            throw new Error("An intentionally stopped loop cannot resume from a handoff answer");
+        if (fs.existsSync(path.join(input.runDir, "loop", "runner.lock")))
+            throw new Error("Handoff controller has not released its lease yet; retry the same answer after it exits");
+        const resultPath = path.join(resultsDir(input.runDir), resultName(hold.envelope_id));
+        const result = fs.existsSync(resultPath) ? readJson(resultPath) : undefined;
+        if (input.choice === HANDOFF_HOLD_CHOICES[2]) {
+            if (hold.resolution)
+                throw new Error("A handoff disposition is already being committed");
+            if (isRecord(result))
+                atomicJson(resultPath, { ...result, decision: { question_id: input.questionId, choice: input.choice, at: input.at, ...(input.notes ? { notes: input.notes } : {}) } });
+            return { lane_id: path.basename(input.runDir), envelope_id: hold.envelope_id, action: "parked" };
+        }
+        if (hold.resolution && hold.resolution.choice !== input.choice)
+            throw new Error("A different handoff disposition is already recorded");
+        if (!hold.resolution) {
+            if (!isRecord(result) || result.hold_reason !== "handoff_needs_repair" || result.question_id !== input.questionId || result.envelope_id !== hold.envelope_id)
+                throw new Error("Handoff result identity changed");
+            const held = envelopeFiles(path.join(input.runDir, "loop", "stalled")).find((file) => fileEnvelope(file).envelope_id === hold.envelope_id);
+            if (!held)
+                throw new Error("Held handoff envelope is missing");
+            const record = fileEnvelope(held);
+            if (input.choice === HANDOFF_HOLD_CHOICES[0]) {
+                const externalPath = record.envelope.result_path;
+                if (typeof externalPath !== "string" || !externalPath.trim())
+                    throw new Error("Held phase has no handoff path");
+                const output = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readHandoffBytes(externalPath));
+                validateAcceptedHandoff(output, record.envelope);
+                delete record.handoff_retry;
+                record.accepted_handoff = { output, sha256: createHash("sha256").update(output).digest("hex") };
+            }
+            else {
+                delete record.accepted_handoff;
+                record.handoff_retry = true;
+            }
+            record.stall_attempts = 0;
+            hold.resolution = { choice: input.choice, at: input.at, ...(input.notes ? { notes: input.notes } : {}), pending_name: `0000000000000-answer-${path.basename(held)}`, record };
+            // Durable authorization precedes every queue/result move. The hold gates
+            // raw controllers until all those moves have completed, including retries.
+            atomicJson(handoffHoldPath(input.runDir), hold);
+        }
+        const resolution = hold.resolution;
+        const pending = path.join(pendingDir(input.runDir), resolution.pending_name);
+        if (path.basename(resolution.pending_name) !== resolution.pending_name || resolution.record.envelope_id !== hold.envelope_id)
+            throw new Error("Invalid handoff disposition record");
+        const held = envelopeFiles(path.join(input.runDir, "loop", "stalled")).find((file) => fileEnvelope(file).envelope_id === hold.envelope_id);
+        if (held) {
+            atomicJson(held, resolution.record);
+            fs.mkdirSync(pendingDir(input.runDir), { recursive: true });
+            fs.renameSync(held, pending);
+        }
+        else if (!fs.existsSync(pending) || JSON.stringify(fileEnvelope(pending)) !== JSON.stringify(resolution.record)) {
+            throw new Error("Disposition envelope changed before it could be resumed");
+        }
+        if (fs.existsSync(resultPath)) {
+            atomicJson(resultPath, { ...readJson(resultPath), decision: { question_id: input.questionId, choice: resolution.choice, at: resolution.at, ...(resolution.notes ? { notes: resolution.notes } : {}) } });
+            fs.renameSync(resultPath, asidePath(resultPath, "stalled"));
+        }
+        persistStatus(input.runDir, path.basename(input.runDir), { state: "waiting" });
+        fs.unlinkSync(handoffHoldPath(input.runDir));
+        return { lane_id: path.basename(input.runDir), envelope_id: hold.envelope_id, action: "requeued" };
+    }
+    finally {
+        release();
+    }
+}
 function asidePath(file, marker) {
     const parsed = path.parse(file);
     let suffix = 1;
@@ -520,6 +688,11 @@ export function findLoopStallResult(runDir, questionId) {
     return resultPath ? readJson(resultPath) : undefined;
 }
 export function applyLoopStallAnswer(input) {
+    const hold = readHandoffHold(input.runDir);
+    if (hold?.question_id === input.questionId)
+        return applyHandoffHoldAnswer(input);
+    if (hold)
+        throw new Error("A different handoff hold must be resolved first");
     const result = findLoopStallResult(input.runDir, input.questionId);
     if (!result) {
         for (const name of stalledResultArchives(input.runDir)) {
@@ -586,12 +759,14 @@ export function loopStatus(runDir, laneId) {
     const stallCounts = isRecord(loop.stall_counts)
         ? Object.fromEntries(Object.entries(loop.stall_counts).filter((entry) => typeof entry[1] === "number"))
         : {};
+    const hold = readHandoffHold(runDir);
     const processState = loop.state === "running" || loop.state === "parked" || loop.state === "stopped" || loop.state === "failed" ? loop.state : "waiting";
     return {
-        mode: "loop", lane_id: laneId, state: processState, queue_depth: queueDepth,
+        mode: "loop", lane_id: laneId, state: hold && processState !== "stopped" ? "parked" : processState, queue_depth: queueDepth,
         active_envelope_id: active?.envelope_id ?? null,
         active_phase: active ? phaseName(active.envelope, active.envelope_id) : null,
         stall_counts: stallCounts,
+        ...(hold ? { handoff_hold: { envelope_id: hold.envelope_id, question_id: hold.question_id } } : {}),
         ...(typeof loop.pid === "number" ? { pid: loop.pid } : {}),
         updated_at: typeof loop.updated_at === "string" ? loop.updated_at : new Date(0).toISOString(),
     };
@@ -746,6 +921,13 @@ function abortAfter(ms, parent) {
 /** Run queued phases serially. Sessions are isolated by story and provider. */
 export async function runLoopLane(options) {
     const now = options.now ?? (() => new Date());
+    const held = readHandoffHold(options.runDir);
+    if (held) {
+        if (loopStatus(options.runDir, options.lane.lane_id).state === "stopped")
+            return { state: "stopped", completed: 0 };
+        await notifyHandoffHold(options, held);
+        return { state: "parked", completed: 0 };
+    }
     const defaultDeadlineSeconds = options.defaultDeadlineSeconds ?? 3600;
     const sessions = new Map();
     try {
@@ -766,6 +948,10 @@ export async function runLoopLane(options) {
     let completed = 0;
     fs.mkdirSync(options.runDir, { recursive: true });
     let releaseRunner = acquireRunnerLease(options.runDir);
+    if (readHandoffHold(options.runDir)) {
+        releaseRunner();
+        return { state: loopStatus(options.runDir, options.lane.lane_id).state === "stopped" ? "stopped" : "parked", completed: 0 };
+    }
     persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid });
     try {
         const previous = readJson(loopPath(options.runDir));
@@ -821,7 +1007,7 @@ export async function runLoopLane(options) {
         const provider = envelopeProvider(envelope, options.lane.provider);
         const story = envelopeStory(envelope);
         const sessionKey = `${story}\0${provider}`;
-        const fresh = envelope.fresh === true || envelope.fresh_call === true;
+        const fresh = record.handoff_retry === true || envelope.fresh === true || envelope.fresh_call === true;
         const previousSession = sessions.get(sessionKey);
         const startedAt = now().toISOString();
         const startedAtMs = Date.parse(startedAt);
@@ -835,14 +1021,29 @@ export async function runLoopLane(options) {
         atomicJson(file, record);
         persistStatus(options.runDir, options.lane.lane_id, { state: "running", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: record.envelope_id, active_phase: phaseName(envelope, record.envelope_id) });
         const timer = abortAfter(budget * 1000, options.signal);
+        let malformedHandoff;
         try {
             let result;
             let fallback = false;
             try {
                 const resumable = options.canResume?.(provider) ?? providerSupportsSessionResume(provider);
-                result = await options.execute({ lane: options.lane, envelope, envelopeId: record.envelope_id, signal: timer.signal, fresh: fresh || previousSession === undefined || !resumable, ...(fresh || previousSession === undefined || !resumable ? {} : { sessionId: previousSession }) });
+                if (record.accepted_handoff) {
+                    malformedHandoff = "Accepted handoff changed before continuation";
+                    const externalPath = envelope.result_path;
+                    if (typeof externalPath !== "string" || createHash("sha256").update(readHandoffBytes(externalPath)).digest("hex") !== record.accepted_handoff.sha256)
+                        throw new Error(malformedHandoff);
+                    if (createHash("sha256").update(record.accepted_handoff.output).digest("hex") !== record.accepted_handoff.sha256)
+                        throw new Error("Accepted handoff hash changed");
+                    validateAcceptedHandoff(record.accepted_handoff.output, envelope);
+                    result = { output: record.accepted_handoff.output };
+                    malformedHandoff = undefined;
+                }
+                else
+                    result = await options.execute({ lane: options.lane, envelope, envelopeId: record.envelope_id, signal: timer.signal, fresh: fresh || previousSession === undefined || !resumable, ...(fresh || previousSession === undefined || !resumable ? {} : { sessionId: previousSession }) });
             }
             catch (error) {
+                if (record.accepted_handoff)
+                    throw error;
                 const resumable = options.canResume?.(provider) ?? providerSupportsSessionResume(provider);
                 if (!fresh && previousSession && resumable && !timer.signal.aborted) {
                     fallback = true;
@@ -875,6 +1076,7 @@ export async function runLoopLane(options) {
                     }
                 }
                 catch (validationError) {
+                    malformedHandoff = validationError instanceof Error ? validationError.message : String(validationError);
                     if (options.repairInvalidHandoff !== false && !timer.signal.aborted) {
                         const repairError = validationError instanceof Error ? validationError.message : String(validationError);
                         const repaired = await options.execute({
@@ -899,6 +1101,7 @@ export async function runLoopLane(options) {
                         if (repairedValidated.worker_id !== envelope.worker_id) {
                             throw new Error(`handoff worker_id must match the queued phase envelope: ${repairError}`);
                         }
+                        malformedHandoff = undefined;
                         result = repaired;
                         success = {
                             ...success,
@@ -932,6 +1135,33 @@ export async function runLoopLane(options) {
                 persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                 return { state: "aborted", completed };
             }
+            if (malformedHandoff !== undefined) {
+                const message = error instanceof Error ? error.message : String(error);
+                const questionId = randomUUID();
+                const hold = { schema: "hq-loop-handoff-hold.v1", envelope_id: record.envelope_id, question_id: questionId, error: `${malformedHandoff}; repair failed: ${message}` };
+                try {
+                    atomicJson(handoffHoldPath(options.runDir), hold);
+                    const externalPath = envelope.result_path;
+                    if (typeof externalPath === "string" && fs.existsSync(externalPath)) {
+                        const stat = fs.lstatSync(externalPath);
+                        if (stat.isFile() && stat.size <= LOOP_ENVELOPE_LIMIT) {
+                            const backup = path.join(options.runDir, "loop", "handoff-original", `${resultName(record.envelope_id)}.${questionId}`);
+                            fs.mkdirSync(path.dirname(backup), { recursive: true });
+                            fs.writeFileSync(backup, readHandoffBytes(externalPath), { flag: "wx", mode: 0o600 });
+                            hold.original_copy = backup;
+                            atomicJson(handoffHoldPath(options.runDir), hold);
+                        }
+                    }
+                    writeResultAt(options.runDir, file, record, { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "stalled", hold_reason: "handoff_needs_repair", question_id: questionId, started_at: startedAt, finished_at: now().toISOString(), error: hold.error }, options.repairInvalidHandoff !== false);
+                    persistStatus(options.runDir, options.lane.lane_id, { state: "parked", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
+                }
+                finally {
+                    releaseRunner();
+                    clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+                }
+                await notifyHandoffHold(options, hold, envelope);
+                return { state: "parked", completed };
+            }
             if (!timer.signal.aborted) {
                 const failure = error instanceof Error ? error.message : String(error);
                 writeResultAt(options.runDir, file, record, { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "failed", started_at: startedAt, finished_at: now().toISOString(), error: failure }, options.repairInvalidHandoff !== false);
@@ -1035,7 +1265,7 @@ function writeResultAt(runDir, activeFile, record, result, includeHandoffValidat
                         schema: PHASE_HANDOFF_SCHEMA,
                         story_id: String(envelope.story_id), phase: String(envelope.phase),
                         worker_id: String(envelope.worker_id), status: stalled ? "blocked" : "failed",
-                        summary: stalled ? "Phase stalled twice and needs operator direction." : includeHandoffValidationError ? `Phase execution failed: ${result.error ?? "unknown error"}` : "Phase execution failed.",
+                        summary: result.hold_reason === "handoff_needs_repair" ? `Handoff needs repair: ${result.error ?? "invalid handoff"}` : stalled ? "Phase stalled twice and needs operator direction." : includeHandoffValidationError ? `Phase execution failed: ${result.error ?? "unknown error"}` : "Phase execution failed.",
                         files_changed: [], commits: [],
                         back_pressure: { tests: "skip", lint: "skip", typecheck: "skip", build: "skip" },
                         context_for_next: [result.error ?? result.status, ...(result.question_id ? [`Decision question: ${result.question_id}`] : [])].join("\n"),

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

@@ -9,6 +9,7 @@ export interface QuestionBody {
         lane_id: string;
         envelope_id: string;
         attempt: number;
+        reason?: "handoff_needs_repair";
     };
 }
 export declare function assertQuestionBodySecretSafe(body: QuestionBody): void;

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