@indigoai-us/hq-cli 5.345.42 → 5.345.44

package/dist/lib/daemon/run.js

@@ -35,6 +35,7 @@ import { detectMachineType } from "./machine-type.js";
 import { appendPrivate, daemonPaths, ensurePrivateDir, openPrivateAppend } from "./paths.js";
 import { hqdSocketPath } from "./protocol.js";
 import { startHqdServer } from "./server.js";
+import { startHqdRuntimeListener } from "./anywhere-listener.js";
 import { heartbeatFile, startHeartbeat } from "./heartbeat.js";
 import { createProtocolTail, ensureProtocolFifo, openProtocolWriter } from "./protocol-tail.js";
 import { takeControlRequests } from "./requests.js";
@@ -835,14 +836,19 @@ export async function runDaemon(opts) {
         return on;
     };
     // hqd: the session/company socket every runtime talks to (hq-anywhere US-008).
-    let hqd = null;
     let hqdShutdown = null;
-    if (shouldStartHqd(await anywhereRuntimeAllowed(env, {
-        onError: (name) => log("warn", `hqd person setting read failed (${name}); runtime remains off`),
-    }))) {
-        try {
+    let stopHeartbeat = () => { };
+    const hqdListener = await startHqdRuntimeListener({
+        isEnabled: async () => shouldStartHqd(await anywhereRuntimeAllowed(env, {
+            refreshFlag: async () => {
+                const { refreshFlagRegistrySnapshot } = await import("../flag-registry.js");
+                await refreshFlagRegistrySnapshot(5_000);
+            },
+            onError: (name) => log("warn", `hqd person setting read failed (${name}); runtime remains off`),
+        })),
+        startServer: async () => {
             const startConfig = readDaemonConfig(paths.configPath);
-            hqd = await startHqdServer({
+            return startHqdServer({
                 socketPath: hqdSocketPath(home, env),
                 registryPath: registryFile(registryDir(home, env)),
                 hqRoot: startConfig.hqRoot ?? (env.HQ_ROOT?.trim() || undefined),
@@ -850,24 +856,25 @@ export async function runDaemon(opts) {
                 onShutdown: () => hqdShutdown?.(),
                 reportError: reportHqdCrash,
             });
-        }
-        catch (err) {
-            log("error", `hqd socket did not start; services run without it: ${err.message}`);
-        }
-    }
-    // US-012: 60s presence heartbeat with version and session count.
-    const liveHqd = hqd;
-    const stopHeartbeat = liveHqd
-        ? startHeartbeat({
-            version: CLI_VERSION,
-            sessionCount: () => liveHqd.sessions.size,
-            file: heartbeatFile(home, env),
-            log,
-        })
-        : () => { };
+        },
+        onServerChange: (server) => {
+            stopHeartbeat();
+            stopHeartbeat = () => { };
+            if (!server)
+                return;
+            // US-012: 60s presence heartbeat with version and session count.
+            stopHeartbeat = startHeartbeat({
+                version: CLI_VERSION,
+                sessionCount: () => server.sessions.size,
+                file: heartbeatFile(home, env),
+                log,
+            });
+        },
+        intervalMs: 60_000,
+        log: (error) => log("error", `hqd socket listener update failed: ${error.message ?? String(error)}`),
+    });
     const closeHqd = () => {
-        stopHeartbeat();
-        void hqd?.close().catch((err) => log("warn", `hqd socket did not close cleanly: ${err.message}`));
+        void hqdListener.close().catch((err) => log("warn", `hqd socket did not close cleanly: ${err.message}`));
     };
     return await new Promise((resolve) => {
         let stopping = false;

package/dist/lib/db/control-plane.d.ts

@@ -130,4 +130,9 @@ export declare class ControlPlaneDbClient {
         appId: string;
     }): Promise<RemoteDestroyAppResponse>;
 }
+export type ControlPlaneHttpError = Error & {
+    status?: number;
+    code?: string;
+    reason?: string;
+};
 //# sourceMappingURL=control-plane.d.ts.map

package/dist/lib/db/control-plane.js

@@ -48,6 +48,8 @@ export class ControlPlaneDbClient {
             err.status = res.status;
             if (typeof payload?.code === "string")
                 err.code = payload.code;
+            if (typeof payload?.reason === "string")
+                err.reason = payload.reason;
             throw err;
         }
         return JSON.parse(text);
@@ -145,12 +147,15 @@ export class ControlPlaneDbClient {
 function httpError(label, status, text) {
     let msg = `${label} failed (${status})`;
     let code;
+    let reason;
     try {
         const j = JSON.parse(text);
         if (typeof j.error === "string")
             msg = j.error;
         if (typeof j.code === "string")
             code = j.code;
+        if (typeof j.reason === "string")
+            reason = j.reason;
     }
     catch {
         /* keep */
@@ -159,6 +164,8 @@ function httpError(label, status, text) {
     err.status = status;
     if (code)
         err.code = code;
+    if (reason)
+        err.reason = reason;
     return err;
 }
 //# sourceMappingURL=control-plane.js.map

package/dist/lib/doctor/checks/anywhere.d.ts

@@ -13,6 +13,8 @@ import type { CheckFamily } from "../types.js";
 export declare const REMEDIATION: {
     readonly installClaude: "hq install --global --runtime claude";
     readonly installCodex: "hq install --global --runtime codex";
+    readonly repairClaudeSkills: "hq uninstall --global --runtime claude && hq install --global --runtime claude";
+    readonly repairCodexSkills: "hq uninstall --global --runtime codex && hq install --global --runtime codex";
     readonly daemonInstall: "hq daemon install";
     readonly daemonRestart: "hq daemon restart --daemon";
     readonly link: "hq link <repo-dir> <company>";
@@ -22,6 +24,13 @@ interface DaemonServiceState {
     loaded: boolean;
     detail: string;
 }
+export interface DaemonServiceProbeOptions {
+    platform?: NodeJS.Platform;
+    uid?: number;
+    launchdProbe?: (target: string) => boolean;
+    /** Test seam for the desktop app's live managed daemon state. */
+    hostedDaemonProbe?: () => boolean;
+}
 export interface AnywhereDeps {
     home?: string;
     env?: NodeJS.ProcessEnv;
@@ -40,5 +49,6 @@ export interface AnywhereDeps {
 }
 export declare function createAnywhereFamily(deps?: AnywhereDeps): CheckFamily;
 export declare const anywhereFamily: CheckFamily;
+export declare function defaultServiceState(home: string, options?: DaemonServiceProbeOptions): DaemonServiceState;
 export {};
 //# sourceMappingURL=anywhere.d.ts.map

package/dist/lib/doctor/checks/anywhere.js

@@ -21,6 +21,8 @@ import { GROK_MODE } from "../../install/grok-targets.js";
 import { HqdClientError, hqdRequest } from "../../daemon/protocol.js";
 import { daemonPresenceLabel, heartbeatFile, readHeartbeat } from "../../daemon/heartbeat.js";
 import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK } from "../../daemon/install.js";
+import { hostedDaemonRunning } from "../../daemon/handoff.js";
+import { daemonPaths } from "../../daemon/paths.js";
 import { hqdSocketPath } from "../../daemon/protocol.js";
 import { readRegistry, registryDir, registryFile } from "../../registry/registry.js";
 import { anywhereRuntimeEnabled } from "../../../commands/anywhere-runtime-flag.js";
@@ -29,6 +31,8 @@ const ANYWHERE_FAMILY_ID = "anywhere";
 export const REMEDIATION = {
     installClaude: "hq install --global --runtime claude",
     installCodex: "hq install --global --runtime codex",
+    repairClaudeSkills: "hq uninstall --global --runtime claude && hq install --global --runtime claude",
+    repairCodexSkills: "hq uninstall --global --runtime codex && hq install --global --runtime codex",
     daemonInstall: "hq daemon install",
     daemonRestart: "hq daemon restart --daemon",
     link: "hq link <repo-dir> <company>",
@@ -137,13 +141,14 @@ async function runAnywhereChecks(context, deps = {}) {
     else
         out.push(result("PASS", "daemon-installed", `daemon service is installed and loaded (${service.detail})`));
     const running = health.reachable ? health.version : null;
+    const daemonFix = service.installed ? REMEDIATION.daemonRestart : REMEDIATION.daemonInstall;
     if (health.reachable)
         out.push(result("PASS", "socket", `hqd answered on ${socketPath}`, undefined, socketPath));
     else
-        out.push(result("FAIL", "socket", `hqd is not reachable on ${socketPath}`, REMEDIATION.daemonInstall, socketPath));
+        out.push(result("FAIL", "socket", `hqd is not reachable on ${socketPath}`, daemonFix, socketPath));
     const cliVersion = deps.cliVersion ?? CLI_VERSION;
     if (running === null)
-        out.push(result("FAIL", "version", `cannot compare versions: hqd did not answer (hq-cli is ${cliVersion})`, REMEDIATION.daemonInstall));
+        out.push(result("FAIL", "version", `cannot compare versions: hqd did not answer (hq-cli is ${cliVersion})`, daemonFix));
     else if (running !== cliVersion)
         out.push(result("FAIL", "version", `hqd runs ${running} but hq-cli ${cliVersion} is installed`, REMEDIATION.daemonRestart));
     else
@@ -159,9 +164,9 @@ async function runAnywhereChecks(context, deps = {}) {
     if (pluginInstall)
         out.push(result("PASS", "claude-skills", `HQ Claude skills are provided by plugin ${pluginInstall.pluginId}`));
     else
-        out.push(checkSkillLinks("claude", claude.skillsDir, REMEDIATION.installClaude));
+        out.push(checkSkillLinks("claude", claude.skillsDir, REMEDIATION.installClaude, REMEDIATION.repairClaudeSkills));
     if (mcp.runtimes.codex.installed)
-        out.push(checkSkillLinks("codex", codex.skillsDir, REMEDIATION.installCodex));
+        out.push(checkSkillLinks("codex", codex.skillsDir, REMEDIATION.installCodex, REMEDIATION.repairCodexSkills));
     return out;
 }
 function unreachableHealth(socketPath) {
@@ -321,7 +326,7 @@ function checkRegistration(runtimeName, status, runtimeState, fix) {
         return result("FAIL", id, `${runtimeName} hq MCP entry does not use absolute paths that exist (${status.target ?? ""})`, fix);
     return result("PASS", id, `hq MCP server registered in ${runtimeName} with absolute paths`);
 }
-function checkSkillLinks(runtime, dir, fix) {
+function checkSkillLinks(runtime, dir, fix, repair = fix) {
     const id = `${runtime}-skills`;
     let names;
     try {
@@ -335,19 +340,42 @@ function checkSkillLinks(runtime, dir, fix) {
         return result("WARN", id, `no hq-* skill links in ${dir}`, fix, dir);
     const broken = links.filter((n) => !fs.existsSync(path.join(dir, n)));
     if (broken.length > 0)
-        return result("FAIL", id, `${broken.length} broken skill links in ${dir}: ${broken.slice(0, 5).join(", ")}`, fix, dir);
+        return result("FAIL", id, `${broken.length} broken skill links in ${dir}: ${broken.slice(0, 5).join(", ")}`, repair, dir);
     return result("PASS", id, `${links.length} hq-* skill links in ${dir} resolve`, undefined, dir);
 }
-function defaultServiceState(home) {
-    if (process.platform === "darwin") {
-        const plist = path.join(home, "Library", "LaunchAgents", `${DAEMON_LAUNCHD_LABEL}.plist`);
-        if (!fs.existsSync(plist))
-            return { installed: false, loaded: false, detail: `no ${plist}` };
-        const uid = process.getuid?.() ?? 0;
-        const probe = spawnSync("launchctl", ["print", `gui/${uid}/${DAEMON_LAUNCHD_LABEL}`], { encoding: "utf8", timeout: 5_000 });
-        return { installed: true, loaded: probe.status === 0, detail: `launchd ${DAEMON_LAUNCHD_LABEL}` };
+export function defaultServiceState(home, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "darwin") {
+        const launchAgents = path.join(home, "Library", "LaunchAgents");
+        const nativePlist = path.join(launchAgents, `${DAEMON_LAUNCHD_LABEL}.plist`);
+        const desktopLabel = "ai.indigo.hq-sync-menubar";
+        const desktopPlist = path.join(launchAgents, `${desktopLabel}.plist`);
+        const uid = options.uid ?? process.getuid?.() ?? 0;
+        const probe = options.launchdProbe ?? ((target) => spawnSync("launchctl", ["print", target], { encoding: "utf8", timeout: 5_000 }).status === 0);
+        const hasNative = fs.existsSync(nativePlist);
+        const hasDesktop = fs.existsSync(desktopPlist);
+        const nativeTarget = `gui/${uid}/${DAEMON_LAUNCHD_LABEL}`;
+        if (hasNative && probe(nativeTarget)) {
+            return { installed: true, loaded: true, detail: `launchd ${DAEMON_LAUNCHD_LABEL}` };
+        }
+        const desktopTarget = `gui/${uid}/${desktopLabel}`;
+        const desktopHostedDaemon = options.hostedDaemonProbe
+            ? options.hostedDaemonProbe()
+            : hostedDaemonRunning(daemonPaths(home));
+        if (desktopHostedDaemon) {
+            return { installed: true, loaded: true, detail: "HQ Desktop-hosted hqd is running (host=desktop)" };
+        }
+        if (hasNative)
+            return { installed: true, loaded: false, detail: `launchd ${DAEMON_LAUNCHD_LABEL}` };
+        if (!hasDesktop)
+            return { installed: false, loaded: false, detail: `no ${nativePlist} or live desktop-hosted hqd` };
+        const desktopAgentLoaded = hasDesktop && probe(desktopTarget);
+        const desktopDetail = hasDesktop
+            ? `HQ Desktop LaunchAgent ${desktopLabel}${desktopAgentLoaded ? " is loaded" : " is not loaded"}, but no live desktop-hosted hqd was found`
+            : "no live desktop-hosted hqd was found";
+        return { installed: false, loaded: false, detail: `no ${nativePlist}; ${desktopDetail}` };
     }
-    if (process.platform === "linux") {
+    if (platform === "linux") {
         const unit = path.join(home, ".config", "systemd", "user", DAEMON_SYSTEMD_UNIT);
         const systemUnit = path.join("/etc/systemd/system", DAEMON_SYSTEMD_UNIT);
         if (!fs.existsSync(unit) && !fs.existsSync(systemUnit))
@@ -356,13 +384,13 @@ function defaultServiceState(home) {
         const probe = spawnSync("systemctl", [...(systemScope ? [] : ["--user"]), "is-active", DAEMON_SYSTEMD_UNIT], { encoding: "utf8", timeout: 5_000 });
         return { installed: true, loaded: probe.status === 0, detail: `systemd ${systemScope ? "system" : "user"} ${DAEMON_SYSTEMD_UNIT}` };
     }
-    if (process.platform === "win32") {
+    if (platform === "win32") {
         const probe = spawnSync("schtasks.exe", ["/Query", "/TN", DAEMON_WINDOWS_TASK, "/FO", "CSV", "/NH"], { encoding: "utf8", timeout: 5_000 });
         if (probe.status !== 0)
             return { installed: false, loaded: false, detail: `no Scheduled Task ${DAEMON_WINDOWS_TASK}` };
         const loaded = /,\s*"?Running"?\s*$/i.test(probe.stdout.trim());
         return { installed: true, loaded, detail: `Scheduled Task ${DAEMON_WINDOWS_TASK}${loaded ? " is running" : " is not running"}` };
     }
-    return { installed: false, loaded: false, detail: `${process.platform}: service probe not available` };
+    return { installed: false, loaded: false, detail: `${platform}: service probe not available` };
 }
 //# sourceMappingURL=anywhere.js.map

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

@@ -31,6 +31,8 @@ export interface FlagRegistryDependencies {
     sentry?: FlagRegistrySentry;
     /** Test seam for exercising the no-source fail-open path. */
     workerSource?: string;
+    /** Start another bounded one-shot worker after an earlier process refresh. */
+    forceRefresh?: boolean;
     captureWorkerFailure?: (error: Error, tags: Record<string, string>) => void;
 }
 export interface CompanyFlagGateDependencies {
@@ -54,6 +56,8 @@ export declare function createProcessSnapshotReader(companyIdentifiers: string[]
  * null and the caller's exact legacy fallback decides the gate.
  */
 export declare function kickFlagRegistryReadiness(dependencies?: FlagRegistryDependencies): FlagReader | null;
+/** Refresh the registry snapshot for a long-running process and wait briefly for its result. */
+export declare function refreshFlagRegistrySnapshot(timeoutMs?: number): Promise<void>;
 /**
  * Evaluate a registry-backed gate without changing its outage default.
  * `isEnabled` itself is synchronous and snapshot-only; any reader failure

package/dist/lib/flag-registry.js

@@ -11,7 +11,7 @@ import { resolveFlagRegistryEndpoint, } from "./flag-registry-endpoint.js";
 import { FLAG_REGISTRY_WORKER_SOURCE } from "./flag-registry-worker-source.generated.js";
 import { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
 import { registerFlagRegistryRefreshWaiter } from "./flag-registry-refresh-wait.js";
-import { flagSnapshotWriteFailureTags, readFlagSnapshotFile, writeFlagSnapshotFile, } from "./flag-snapshot-file.js";
+import { flagSnapshotWriteFailureTags, readFlagSnapshotFile, writePersonFlagSnapshotFile, writeFlagSnapshotFile, } from "./flag-snapshot-file.js";
 function captureFlagRegistryException(error, tags, sentry) {
     if (!sentry)
         return;
@@ -50,6 +50,7 @@ let refreshCompanyUid;
 let refreshHasCompanyContext = false;
 let refreshPendingSnapshot = null;
 let refreshSentry;
+let refreshDependencies = {};
 /** Wait briefly for the current company refresh to persist or report completion. */
 export async function waitForFlagRegistryRefresh(timeoutMs = 500, companyUid) {
     const resolvedCompanyUid = normalizedCompanyUid(companyUid);
@@ -70,6 +71,21 @@ export async function waitForFlagRegistryRefresh(timeoutMs = 500, companyUid) {
         completeRefresh?.();
         completeRefresh = null;
     }
+    else if (refreshPendingSnapshot && !refreshHasCompanyContext) {
+        try {
+            writePersonFlagSnapshotFile(refreshPendingSnapshot.flags);
+        }
+        catch (error) {
+            captureFlagRegistryException(error instanceof Error ? error : new Error(String(error)), {
+                component: "flag-snapshot-cache-write",
+                company_uid_present: "false",
+                ...flagSnapshotWriteFailureTags(error),
+            }, refreshSentry);
+        }
+        refreshPendingSnapshot = null;
+        completeRefresh?.();
+        completeRefresh = null;
+    }
     if (!completeRefresh)
         return;
     const worker = refreshWorker;
@@ -123,8 +139,10 @@ function processSnapshotReader(companyIdentifiers) {
  * null and the caller's exact legacy fallback decides the gate.
  */
 export function kickFlagRegistryReadiness(dependencies = {}) {
-    if (processReader)
+    if (processReader && !dependencies.forceRefresh)
         return processReader;
+    if (!dependencies.forceRefresh)
+        refreshDependencies = { ...dependencies };
     const endpoint = resolveFlagRegistryEndpoint(dependencies.endpoint, process.env);
     const companyScope = dependencies.companyScope ?? explicitCompanyScopeFromArgv(dependencies.argv ?? []);
     const companyEnv = companyScope
@@ -233,6 +251,16 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
                     finishRefresh();
                 }
                 else if (!refreshHasCompanyContext) {
+                    try {
+                        writePersonFlagSnapshotFile(value.flags);
+                    }
+                    catch (error) {
+                        captureFlagRegistryException(error instanceof Error ? error : new Error(String(error)), {
+                            component: "flag-snapshot-cache-write",
+                            company_uid_present: "false",
+                            ...flagSnapshotWriteFailureTags(error),
+                        }, sentry);
+                    }
                     refreshPendingSnapshot = null;
                     finishRefresh();
                 }
@@ -258,6 +286,18 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
     }
     return processReader;
 }
+/** Refresh the registry snapshot for a long-running process and wait briefly for its result. */
+export async function refreshFlagRegistrySnapshot(timeoutMs = 5_000) {
+    const refreshIsPending = () => completeRefresh !== null;
+    if (refreshIsPending()) {
+        await waitForFlagRegistryRefresh(timeoutMs);
+        if (refreshIsPending())
+            return;
+    }
+    processReader = null;
+    kickFlagRegistryReadiness({ ...refreshDependencies, forceRefresh: true });
+    await waitForFlagRegistryRefresh(timeoutMs);
+}
 /**
  * Evaluate a registry-backed gate without changing its outage default.
  * `isEnabled` itself is synchronous and snapshot-only; any reader failure
@@ -348,5 +388,6 @@ export function _resetFlagRegistryForTests() {
     refreshHasCompanyContext = false;
     refreshPendingSnapshot = null;
     refreshSentry = undefined;
+    refreshDependencies = {};
 }
 //# sourceMappingURL=flag-registry.js.map

package/dist/lib/flag-snapshot-file.d.ts

@@ -7,8 +7,25 @@ export interface PersistedFlagSnapshot {
     fetched_at: string;
     flags: Record<string, boolean>;
 }
+export interface PersistedPersonFlagSnapshot {
+    scope: "person";
+    fetched_at: string;
+    flags: Record<string, boolean>;
+}
 export declare function _resetFlagSnapshotCacheForTests(): void;
 export declare function flagSnapshotPath(companyUid: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function personFlagSnapshotPath(env?: NodeJS.ProcessEnv): string;
+/** Persist the no-company flag resolution without storing identity or token data. */
+export declare function writePersonFlagSnapshotFile(flags: Readonly<Record<string, unknown>>, options?: {
+    env?: NodeJS.ProcessEnv;
+    fetchedAt?: string;
+}): string;
+/** Read only a fresh, correctly scoped person snapshot. Every invalid state is a cache miss. */
+export declare function readPersonFlagSnapshotFile(options?: {
+    env?: NodeJS.ProcessEnv;
+    now?: number;
+    maxAgeMs?: number;
+}): PersistedPersonFlagSnapshot | null;
 /** Write just the validated flag decisions and company scope, never auth data. */
 export declare function writeFlagSnapshotFile(companyUid: string, flags: Readonly<Record<string, unknown>>, options?: {
     env?: NodeJS.ProcessEnv;

package/dist/lib/flag-snapshot-file.js

@@ -102,19 +102,169 @@ function fallbackSnapshotPath(companyUid, create) {
     }
     return path.join(directories[2], `snapshot-${companyUid}.json`);
 }
+function fallbackPersonSnapshotPath(create) {
+    if (typeof process.getuid !== "function")
+        return undefined;
+    const uid = process.getuid();
+    const root = path.join(os.tmpdir(), `hq-cli-flag-snapshots-${uid}`);
+    const directories = [root, path.join(root, "hq"), path.join(root, "hq", "flags")];
+    for (const directory of directories) {
+        try {
+            if (create)
+                fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const stat = fs.lstatSync(directory);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== uid)
+                return undefined;
+            if (create)
+                fs.chmodSync(directory, 0o700);
+            else if ((stat.mode & 0o077) !== 0)
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return path.join(directories[2], "snapshot-person.json");
+}
 export function flagSnapshotPath(companyUid, env = process.env) {
     if (!COMPANY_UID_RE.test(companyUid))
         return undefined;
     const cacheHome = env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), ".cache");
     return path.join(cacheHome, "hq", "flags", `snapshot-${companyUid}.json`);
 }
+export function personFlagSnapshotPath(env = process.env) {
+    const cacheHome = env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), ".cache");
+    return path.join(cacheHome, "hq", "flags", "snapshot-person.json");
+}
+function normalizedFlagValues(flags) {
+    return Object.fromEntries(Object.entries(flags).filter((entry) => Boolean(entry[0].trim()) && typeof entry[1] === "boolean"));
+}
+function writeSnapshotAt(destination, snapshot, cacheRootKind) {
+    const directory = path.dirname(destination);
+    const context = (step) => ({
+        step,
+        cacheRootKind,
+        directory,
+    });
+    atWriteStep(context("mkdir"), () => fs.mkdirSync(directory, { recursive: true, mode: 0o700 }));
+    const temporary = `${destination}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    let fd;
+    try {
+        fd = atWriteStep(context("open_tmp"), () => fs.openSync(temporary, "wx", 0o600));
+        atWriteStep(context("write_tmp"), () => {
+            fs.writeFileSync(fd, `${JSON.stringify(snapshot)}\n`, "utf8");
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = undefined;
+        });
+        atWriteStep(context("rename"), () => fs.renameSync(temporary, destination));
+    }
+    catch (error) {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (cleanupError) {
+            if (cleanupError.code !== "ENOENT")
+                throw cleanupError;
+        }
+        throw error;
+    }
+    return destination;
+}
+function writePersonFallback(snapshot, originalError) {
+    const fallbackFile = fallbackPersonSnapshotPath(true);
+    if (!fallbackFile) {
+        if (originalError) {
+            markFallbackFailed(originalError);
+            throw originalError;
+        }
+        const error = Object.assign(new Error("Flag snapshot fallback directory is unavailable"), { code: "EACCES" });
+        markFallbackFailed(error);
+        throw error;
+    }
+    try {
+        const written = writeSnapshotAt(fallbackFile, snapshot, "home");
+        fallbackCacheUsed = true;
+        return written;
+    }
+    catch (fallbackError) {
+        if (originalError) {
+            markFallbackFailed(originalError);
+            throw originalError;
+        }
+        markFallbackFailed(fallbackError);
+        throw fallbackError;
+    }
+}
+/** Persist the no-company flag resolution without storing identity or token data. */
+export function writePersonFlagSnapshotFile(flags, options = {}) {
+    const env = options.env ?? process.env;
+    const snapshot = {
+        scope: "person",
+        fetched_at: options.fetchedAt ?? new Date().toISOString(),
+        flags: normalizedFlagValues(flags),
+    };
+    if (!Number.isFinite(Date.parse(snapshot.fetched_at))) {
+        throw new Error("Cannot persist a flag snapshot with an invalid fetched_at timestamp");
+    }
+    if (fallbackCacheUsed)
+        return writePersonFallback(snapshot);
+    try {
+        return writeSnapshotAt(personFlagSnapshotPath(env), snapshot, env.XDG_CACHE_HOME?.trim() ? "xdg" : "home");
+    }
+    catch (error) {
+        if (!isPermissionFailure(error))
+            throw error;
+        return writePersonFallback(snapshot, error);
+    }
+}
+/** Read only a fresh, correctly scoped person snapshot. Every invalid state is a cache miss. */
+export function readPersonFlagSnapshotFile(options = {}) {
+    const env = options.env ?? process.env;
+    const files = [personFlagSnapshotPath(env)];
+    const fallback = fallbackPersonSnapshotPath(false);
+    if (fallbackCacheUsed && fallback)
+        files.unshift(fallback);
+    else if (fallback)
+        files.push(fallback);
+    for (const file of files) {
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const value = parsed;
+        if (Object.keys(value).sort().join(",") !== "fetched_at,flags,scope" ||
+            value.scope !== "person" ||
+            typeof value.fetched_at !== "string" ||
+            !value.flags || typeof value.flags !== "object" || Array.isArray(value.flags))
+            continue;
+        const fetchedAt = Date.parse(value.fetched_at);
+        const age = (options.now ?? Date.now()) - fetchedAt;
+        if (!Number.isFinite(fetchedAt) || age < 0 || age > (options.maxAgeMs ?? FLAG_SNAPSHOT_MAX_AGE_MS))
+            continue;
+        const flags = value.flags;
+        if (!Object.values(flags).every((enabled) => typeof enabled === "boolean"))
+            continue;
+        if (file === fallback && fallback)
+            fallbackCacheUsed = true;
+        return { scope: "person", fetched_at: value.fetched_at, flags: flags };
+    }
+    return null;
+}
 /** Write just the validated flag decisions and company scope, never auth data. */
 export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
     const env = options.env ?? process.env;
     const file = flagSnapshotPath(companyUid, env);
     if (!file)
         throw new Error("Cannot persist a flag snapshot without a valid company uid");
-    const normalizedFlags = Object.fromEntries(Object.entries(flags).filter((entry) => Boolean(entry[0].trim()) && typeof entry[1] === "boolean"));
+    const normalizedFlags = normalizedFlagValues(flags);
     const snapshot = {
         company_uid: companyUid,
         fetched_at: options.fetchedAt ?? new Date().toISOString(),
@@ -124,40 +274,6 @@ export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
         throw new Error("Cannot persist a flag snapshot with an invalid fetched_at timestamp");
     }
     const cacheRootKind = env.XDG_CACHE_HOME?.trim() ? "xdg" : "home";
-    const writeAt = (destination) => {
-        const directory = path.dirname(destination);
-        const context = (step) => ({
-            step,
-            cacheRootKind,
-            directory,
-        });
-        atWriteStep(context("mkdir"), () => fs.mkdirSync(directory, { recursive: true, mode: 0o700 }));
-        const temporary = `${destination}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-        let fd;
-        try {
-            fd = atWriteStep(context("open_tmp"), () => fs.openSync(temporary, "wx", 0o600));
-            atWriteStep(context("write_tmp"), () => {
-                fs.writeFileSync(fd, `${JSON.stringify(snapshot)}\n`, "utf8");
-                fs.fsyncSync(fd);
-                fs.closeSync(fd);
-                fd = undefined;
-            });
-            atWriteStep(context("rename"), () => fs.renameSync(temporary, destination));
-        }
-        catch (error) {
-            if (fd !== undefined)
-                fs.closeSync(fd);
-            try {
-                fs.unlinkSync(temporary);
-            }
-            catch (cleanupError) {
-                if (cleanupError.code !== "ENOENT")
-                    throw cleanupError;
-            }
-            throw error;
-        }
-        return destination;
-    };
     const writeFallback = (originalError) => {
         const fallbackFile = fallbackSnapshotPath(companyUid, true);
         if (!fallbackFile) {
@@ -170,7 +286,7 @@ export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
             throw error;
         }
         try {
-            const written = writeAt(fallbackFile);
+            const written = writeSnapshotAt(fallbackFile, snapshot, cacheRootKind);
             fallbackCacheUsed = true;
             return written;
         }
@@ -186,7 +302,7 @@ export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
     if (fallbackCacheUsed)
         return writeFallback();
     try {
-        return writeAt(file);
+        return writeSnapshotAt(file, snapshot, cacheRootKind);
     }
     catch (error) {
         if (!isPermissionFailure(error))

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

@@ -1,5 +1,8 @@
 /** hq-flags keys used by lane command behavior. */
+export declare const LANE_FOCUS_DASHBOARD_FLAG = "lanes-focus-dashboard";
 export declare const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
+/** Enables same-provider automatic lane recovery after provider quota exhaustion. */
+export declare const LANE_QUOTA_ACCOUNT_FAILOVER_FLAG = "lanes.quota-account-failover";
 /** Gives live senior lanes Claude admission precedence and reserves host capacity for them. */
 export declare const LANE_LEAD_ADMISSION_PRIORITY_FLAG = "lanes.lead-admission-priority";
 /** Refresh provider/model/effort from a worker profile when a done lane takes a new story. */
@@ -24,4 +27,6 @@ export declare const LEAD_AUTOPILOT_HEADLINE_STALENESS_FLAG = "lanes.autopilot-h
 export declare const LEAD_AUTOPILOT_OUTPOST_NATIVE_LEADS_FLAG = "lanes.autopilot-outpost-native-leads";
 /** Allows applying an operator-reviewed repair of messages stranded in bare-ULID dropboxes. */
 export declare const LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG = "lanes.orphaned-bare-id-dropbox-repair";
+/** Allows a Claude lane to leave an exhausted profile account pin for an eligible account. */
+export declare const LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG = "lanes.profile-pin-exhausted-fallback";
 //# sourceMappingURL=flag-keys.d.ts.map