@indigoai-us/hq-cli 5.345.134 → 5.345.135

package/dist/lib/lanes/spawn.js

@@ -42,6 +42,8 @@ import { MESSAGE_REPLAY_STATE_NAME } from "./message-replay.js";
 import { markAnsweredQuestionsDelivered } from "./questions.js";
 import { hasEarlierEligibleQueuedLane, laneAdmissionCapReason, withLaneAdmissionLock, } from "./admission.js";
 import { resolveAdmissionHost } from "./admission-host.js";
+import { offlineFingerprint } from "../fingerprint/offline.js";
+import { SESSION_ID_ENV_VARS } from "../fingerprint/self-core.js";
 import { checkLaneDiskSpace, laneDiskAccount } from "./disk-guard.js";
 import { LANE_ENVELOPE_JSON_SCHEMA, ENVELOPE_INVALID_REASON, parseLaneProvider, } from "./types.js";
 export const LANES_RUNS_REL = path.join("workspace", "lanes-runs");
@@ -1661,7 +1663,7 @@ export function buildProviderCommand(provider, input) {
         args: appendFastModeFlags(parsed, appendEffortFlag(parsed, appendModelFlag(parsed, appendCodexWorkerPolicyDirFlag(parsed, appendProviderProfileFlags(parsed, args, input.profile), input.workerPolicyDir), input.model), input.effort), input.fastMode),
     };
 }
-export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, meshCompany, workerPolicyDir, registryWorker, homedir) {
+export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, meshCompany, workerPolicyDir, registryWorker, homedir, session) {
     const accepted = Object.values(PROVIDER_HOME_ENV);
     if (!accepted.includes(resolved.envVar)) {
         throw new LanesError("unknown_provider_home_env", `Unknown provider home variable ${JSON.stringify(resolved.envVar)}. Accepted: ${accepted.join(", ")}`, { accepted, value: resolved.envVar });
@@ -1704,8 +1706,48 @@ export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, mes
     else {
         delete env.HQ_SPAWN_COMPANY;
     }
+    if (meshCompany?.slug) {
+        env.HQ_COMPANY = meshCompany.slug;
+    }
+    else {
+        delete env.HQ_COMPANY;
+    }
+    // Session identity precedence for the worker (the fingerprint builder and
+    // the commit-msg hook read HQ_SESSION_ID first, then the harness ids):
+    // 1. HQ_SESSION_ID is the worker's own session, the id `--resume` would
+    //    use. It is set only when that id is known before launch (a resume, or
+    //    a remote-control lane whose id hq-cli mints). A cold first turn leaves
+    //    it unset rather than guessing.
+    // 2. The harness ids (CLAUDE_CODE_SESSION_ID and the rest) are set by the
+    //    worker's own CLI once it starts. Values inherited from the senior are
+    //    dropped so a worker never reports the senior's session as its own.
+    // HQ_PARENT_SESSION_ID names the senior session when the senior is one.
+    for (const name of WORKER_SESSION_ENV_VARS)
+        delete env[name];
+    delete env.HQ_PARENT_SESSION_ID;
+    if (session?.workerSessionId)
+        env.HQ_SESSION_ID = session.workerSessionId;
+    if (session?.parentSessionId)
+        env.HQ_PARENT_SESSION_ID = session.parentSessionId;
     return env;
 }
+/** Session ids a worker must not inherit from the process that spawns it. */
+export const WORKER_SESSION_ENV_VARS = SESSION_ID_ENV_VARS;
+/**
+ * The worker's fingerprint, built offline from the worker env at lane start.
+ * Null when it cannot be built (no identity and no session id, or an error);
+ * the lane still starts.
+ */
+export function laneStartFingerprint(hqRoot, env) {
+    return offlineFingerprint(hqRoot, env, "hq lanes");
+}
+/** The session identity a lane turn exports to its worker (see `workerEnv`). */
+export function laneWorkerSessionEnv(lane, workerSessionId) {
+    return {
+        ...(workerSessionId ? { workerSessionId } : {}),
+        ...(lane.senior.kind === "session" && lane.senior.id ? { parentSessionId: lane.senior.id } : {}),
+    };
+}
 export const WORKER_POLICY_HOOK_CAPABILITY = "# hq-capability: worker-policy-dir v1";
 function installedWorkerPolicyHookSupportsDirectory(hqRoot) {
     const hookPath = path.join(hqRoot, ".claude", "hooks", "inject-policy-on-trigger.sh");
@@ -2445,9 +2487,13 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const autoCompactTokens = lane.provider === "claude"
         ? providerAutoCompactTokens(config.providers.claude)
         : undefined;
-    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: remoteControlHome ?? resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir, lane.registry_worker);
+    const remoteSessionId = existing.remote_control === true
+        ? plan.mode === "resume" ? plan.session_id : randomUUID()
+        : undefined;
+    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: remoteControlHome ?? resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir, lane.registry_worker, undefined, laneWorkerSessionEnv(existing, plan.mode === "resume" ? plan.session_id : remoteSessionId));
     const laneTurnId = randomUUID();
     childEnv.HQ_LANE_TURN_ID = laneTurnId;
+    const fingerprint = (deps.buildFingerprint ?? laneStartFingerprint)(hqRoot, childEnv);
     const model = resolveLaneModel({
         cliModel: pinnedModel,
         profileModel,
@@ -2507,9 +2553,6 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             }),
         }
         : undefined;
-    const remoteSessionId = existing.remote_control === true
-        ? plan.mode === "resume" ? plan.session_id : randomUUID()
-        : undefined;
     const providerCommand = buildProviderCommand(lane.provider, {
         hqRoot,
         briefPath,
@@ -2682,6 +2725,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             pending_settings: undefined,
             account: resolved.id,
             provider_home_at_spawn: remoteControlHome ?? resolved.home,
+            fingerprint,
             working_directory_at_spawn: workerCwd,
             ...(model !== undefined ? { model } : {}),
             ...(model !== undefined
@@ -3094,7 +3138,7 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
     const autoCompactTokens = lane.provider === "claude"
         ? providerAutoCompactTokens(config.providers.claude)
         : undefined;
-    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir, lane.registry_worker);
+    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir, lane.registry_worker, undefined, laneWorkerSessionEnv(lane, mode === "resume" && sessionId !== null ? sessionId : undefined));
     const accountCfg = config.providers[lane.provider].accounts[resolved.id];
     const model = resolveLaneModel({
         cliModel: pinnedModel,

package/dist/lib/lanes/story-ledger.d.ts

@@ -54,6 +54,7 @@ export interface LaneStatusSnapshot {
         no_story_reason: string | null;
         state: LaneState;
         queued_reason: string | null;
+        fingerprint: string | null;
     }>;
     prs: Array<{
         story_id: string;

package/dist/lib/lanes/story-ledger.js

@@ -812,6 +812,7 @@ export function buildLaneStatusSnapshot(input) {
         no_story_reason: lane.no_story_reason ?? null,
         state: lane.state,
         queued_reason: lane.queued_reason ?? null,
+        fingerprint: lane.fingerprint ?? null,
     }));
     const projectPrs = [];
     const blockers = [];
@@ -905,7 +906,8 @@ export function formatLaneStatusHuman(snapshot) {
                 const account = worker.account ? " account " + worker.account : "";
                 const queued = worker.queued_reason ? " queued: " + worker.queued_reason : "";
                 return "  " + worker.lane_id + "  " + worker.state + "  " + storyLabel +
-                    "  " + worker.provider + model + effort + account + queued;
+                    "  " + worker.provider + model + effort + account + queued +
+                    "\n    fingerprint: " + (worker.fingerprint ?? "-");
             })),
         "PRs (may include merged):",
         ...(snapshot.prs.length === 0

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

@@ -81,6 +81,10 @@ export declare const LANE_ENVELOPE_JSON_SCHEMA: {
             readonly type: "string";
             readonly minLength: 1;
         };
+        readonly fingerprint: {
+            readonly type: readonly ["string", "null"];
+            readonly description: "Optional worker fingerprint (hq fingerprint self); null when it could not be built. Older readers ignore it.";
+        };
     };
     readonly allOf: readonly [{
         readonly if: {
@@ -770,6 +774,12 @@ export interface LaneRecord {
      */
     provider_session_id?: string;
     provider_session_id_absent?: string;
+    /**
+     * The worker's fingerprint, built offline from the worker env when the
+     * lane's run starts (`hq fingerprint self --offline`). Null when it could
+     * not be built; absent on lanes started before fingerprints existed.
+     */
+    fingerprint?: string | null;
     /** Provider home used by the most recently spawned run, for transcript recovery. */
     provider_home_at_spawn?: string;
     /**
@@ -1002,6 +1012,8 @@ export interface LaneEnvelope {
     blocked_reason?: string;
     story_complete?: boolean;
     story_complete_reason?: string;
+    /** The worker's fingerprint, or null when it could not be built. Optional. */
+    fingerprint?: string | null;
 }
 export interface AccountConfig {
     home: string;

package/dist/lib/lanes/types.js

@@ -49,6 +49,10 @@ export const LANE_ENVELOPE_JSON_SCHEMA = {
         blocked_reason: { type: "string" },
         story_complete: { type: "boolean" },
         story_complete_reason: { type: "string", minLength: 1 },
+        fingerprint: {
+            type: ["string", "null"],
+            description: "Optional worker fingerprint (hq fingerprint self); null when it could not be built. Older readers ignore it.",
+        },
     },
     allOf: [
         {
@@ -243,7 +247,7 @@ export const LANE_FIELD_WRITERS = {
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
     admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command", "reconcile"], settings_history: ["command"], pending_settings: ["command", "spawn"], interrupted_at: ["command", "watcher", "reconcile", "spawn"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
     quota_reset_at: ["watcher", "reconcile", "spawn", "command"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
-    provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], working_directory_at_spawn: ["spawn"], last_resume: ["spawn"], resume_history: ["spawn", "watcher"], last_run_usage: ["watcher"], last_run_usage_at: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
+    provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], fingerprint: ["spawn"], provider_home_at_spawn: ["spawn"], working_directory_at_spawn: ["spawn"], last_resume: ["spawn"], resume_history: ["spawn", "watcher"], last_run_usage: ["watcher"], last_run_usage_at: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
 };
 function isPlainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -299,6 +303,7 @@ export function parseLaneEnvelope(raw) {
         "blocked_reason",
         "story_complete",
         "story_complete_reason",
+        "fingerprint",
     ].includes(key));
     if (extra.length > 0) {
         throw new LaneSchemaError(`Lane envelope rejects unknown properties: ${extra.join(", ")}`, { extra });
@@ -382,6 +387,12 @@ export function parseLaneEnvelope(raw) {
     };
     if (nextCheckAt !== undefined)
         envelope.next_check_at = nextCheckAt;
+    if (raw.fingerprint !== undefined) {
+        if (raw.fingerprint !== null && (typeof raw.fingerprint !== "string" || raw.fingerprint.trim().length === 0)) {
+            throw new LaneSchemaError("fingerprint must be a non-empty string or null", { field: "fingerprint" });
+        }
+        envelope.fingerprint = raw.fingerprint;
+    }
     if (storyComplete !== undefined) {
         envelope.story_complete = storyComplete;
         envelope.story_complete_reason = storyCompleteReason;

package/dist/utils/cli-network-lifecycle.d.ts

@@ -1,4 +1,6 @@
 export declare function isMonitorFastPathCommand(argv: readonly string[]): boolean;
+/** The commit-msg hook runs `hq fingerprint self --offline`; it must stay fast and offline. */
+export declare function isOfflineFingerprintCommand(argv: readonly string[]): boolean;
 /** Skip process-wide network lifecycle work for hooks and detached monitor supervisors. */
 export declare function runGlobalNetworkLifecycle<T>(argv: readonly string[], operation: () => T): T | undefined;
 //# sourceMappingURL=cli-network-lifecycle.d.ts.map

package/dist/utils/cli-network-lifecycle.js

@@ -2,9 +2,13 @@ const MONITOR_HIDDEN_NETWORK_BYPASS = new Set(["drain", "wait", "enabled", "_run
 export function isMonitorFastPathCommand(argv) {
     return argv[2] === "monitor" && MONITOR_HIDDEN_NETWORK_BYPASS.has(argv[3] ?? "");
 }
+/** The commit-msg hook runs `hq fingerprint self --offline`; it must stay fast and offline. */
+export function isOfflineFingerprintCommand(argv) {
+    return argv[2] === "fingerprint" && argv[3] === "self" && argv.slice(4).includes("--offline");
+}
 /** Skip process-wide network lifecycle work for hooks and detached monitor supervisors. */
 export function runGlobalNetworkLifecycle(argv, operation) {
-    if (isMonitorFastPathCommand(argv))
+    if (isMonitorFastPathCommand(argv) || isOfflineFingerprintCommand(argv))
         return undefined;
     return operation();
 }

package/dist/utils/cognito-session.d.ts

@@ -19,7 +19,8 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 import { isExpiring, isMachineIdentity, type CognitoAuthConfig, type CognitoTokens, type ClientInfo, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
-import { type KeychainReadOptions } from "./token-keychain.js";
+import { loadCachedTokens, personTokenCacheFile, readPersonTokenFile } from "./person-token-cache.js";
+export { loadCachedTokens, personTokenCacheFile, readPersonTokenFile };
 export { isExpiring, isMachineIdentity };
 /** Person browser/login cache vs machine-creds USER_PASSWORD_AUTH mint. */
 export type CognitoTokenSource = "person" | "machine";
@@ -118,13 +119,6 @@ export type EnsureCognitoTokenOptions = {
     /** Cancels bounded, non-interactive person-session refreshes. */
     signal?: AbortSignal;
 };
-/**
- * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
- * Deliberately does not use hq-cloud's `loadCachedTokens()`: after a machine
- * mint in this process, that helper returns in-memory machine tokens when the
- * person file is absent, which would falsely block the fresh-box fallback.
- */
-export declare function personTokenCacheFile(home?: string, env?: NodeJS.ProcessEnv): string;
 /**
  * True when a usable person Cognito cache file exists under the effective
  * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the
@@ -186,19 +180,6 @@ export declare function formatCognitoSubject(tokens: {
     idToken?: string;
     accessToken?: string;
 } | null | undefined): string;
-/**
- * Person session for `env`: the Keychain item and the token file, the newer
- * by `expiresAt` (see ./token-keychain.ts). Does not consult hq-cloud's
- * in-memory fallback, which can surface a different session when the file
- * is missing or unreadable.
- */
-export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
-/**
- * The person's cached session: the shared Keychain item and hq-cloud's file
- * loader, the newer by `expiresAt`. Writes still go only to the file in this
- * step.
- */
-export declare function loadCachedTokens(env?: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
 /**
  * Refresh the active person session and refuse a subject change.
  *

package/dist/utils/cognito-session.js

@@ -25,13 +25,14 @@ import * as os from "os";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import chalk from "chalk";
-import { loadCachedTokens as loadCachedTokensFromFile, isExpiring, refreshTokens, saveCachedTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
+import { isExpiring, refreshTokens, saveCachedTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { daemonDir } from "../lib/mesh/live/daemon/paths.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
 import { acquireLockFileExclusively } from "./exclusive-lock.js";
 import { reportNoninteractivePersonRefreshRejection } from "./cognito-refresh-sentry.js";
-import { pickNewerSession, readKeychainTokens } from "./token-keychain.js";
+import { decodeJwtPayload, loadCachedTokens, personTokenCacheFile, readPersonTokenFile, readTokenFile, } from "./person-token-cache.js";
+export { loadCachedTokens, personTokenCacheFile, readPersonTokenFile };
 // Re-export the cached-session primitives for callers that must deliberately
 // avoid the refresh/login behavior in the higher-level helpers below.
 export { isExpiring, isMachineIdentity };
@@ -294,17 +295,6 @@ function withAlignedMachineCredsEnv(env, fn) {
         }
     }
 }
-/**
- * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
- * Deliberately does not use hq-cloud's `loadCachedTokens()`: after a machine
- * mint in this process, that helper returns in-memory machine tokens when the
- * person file is absent, which would falsely block the fresh-box fallback.
- */
-export function personTokenCacheFile(home = os.homedir(), env = process.env) {
-    const override = env.HQ_STATE_DIR?.trim();
-    const stateDir = override && override.length > 0 ? override : path.join(home, ".hq");
-    return path.join(stateDir, "cognito-tokens.json");
-}
 /**
  * True when a usable person Cognito cache file exists under the effective
  * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the
@@ -396,23 +386,6 @@ export function wantsMachineCognitoTokens(options = {}, env = process.env) {
 export function resolveCognitoTokenSource(env = process.env) {
     return wantsMachineCognitoTokens({}, env) ? "machine" : "person";
 }
-function decodeJwtPayload(token) {
-    if (!token)
-        return null;
-    const parts = token.split(".");
-    if (parts.length < 2 || !parts[1])
-        return null;
-    try {
-        const json = Buffer.from(parts[1], "base64url").toString("utf8");
-        const parsed = JSON.parse(json);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            return null;
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Refresh wrote a different Cognito subject than the active cache.
  * Callers must not fall through to browser login or machine mint — that
@@ -460,60 +433,6 @@ export function formatCognitoSubject(tokens) {
     const fromAccess = cognitoSubjectFromToken(tokens.accessToken);
     return `sub=${fromId.sub ?? fromAccess.sub ?? "-"} entityUid=${fromId.entityUid ?? fromAccess.entityUid ?? "-"}`;
 }
-function readTokenFile(file) {
-    try {
-        if (!fs.existsSync(file))
-            return null;
-        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
-        if (typeof raw.accessToken !== "string" || typeof raw.idToken !== "string")
-            return null;
-        return raw;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * The person session from the shared macOS Keychain item (see
- * ./token-keychain.ts), or null. Not read when the token file is missing:
- * no file means signed out. Machine-identity and invalidated tokens are
- * refused, the same as the file loader.
- */
-function personKeychainTokens(file, home, env, keychain = {}) {
-    if (!fs.existsSync(file))
-        return null;
-    const tokens = readKeychainTokens({ env, home, ...keychain });
-    if (!tokens)
-        return null;
-    const claims = decodeJwtPayload(tokens.idToken);
-    const entityType = claims?.["custom:entityType"];
-    if (typeof entityType === "string" && entityType.trim().length > 0)
-        return null;
-    if (fs.existsSync(`${file}.invalid.${accessTokenFingerprint(tokens.accessToken)}`))
-        return null;
-    return tokens;
-}
-/**
- * Person session for `env`: the Keychain item and the token file, the newer
- * by `expiresAt` (see ./token-keychain.ts). Does not consult hq-cloud's
- * in-memory fallback, which can surface a different session when the file
- * is missing or unreadable.
- */
-export function readPersonTokenFile(home = os.homedir(), env = process.env, keychain = {}) {
-    const file = personTokenCacheFile(home, env);
-    return pickNewerSession(personKeychainTokens(file, home, env, keychain), readTokenFile(file));
-}
-/**
- * The person's cached session: the shared Keychain item and hq-cloud's file
- * loader, the newer by `expiresAt`. Writes still go only to the file in this
- * step.
- */
-export function loadCachedTokens(env = process.env, keychain = {}) {
-    const home = os.homedir();
-    const file = personTokenCacheFile(home, env);
-    const fromFile = loadCachedTokensFromFile();
-    return pickNewerSession(personKeychainTokens(file, home, env, keychain), fromFile);
-}
 function restoreTokenFile(file, before) {
     if (before) {
         const dir = path.dirname(file);

package/dist/utils/person-token-cache.d.ts

@@ -0,0 +1,32 @@
+import { type CognitoTokens } from "@indigoai-us/hq-cloud";
+import { type KeychainReadOptions } from "./token-keychain.js";
+/**
+ * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
+ * Deliberately does not use hq-cloud's `loadCachedTokens()`: after a machine
+ * mint in this process, that helper returns in-memory machine tokens when the
+ * person file is absent, which would falsely block the fresh-box fallback.
+ */
+export declare function personTokenCacheFile(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function decodeJwtPayload(token: string | undefined): Record<string, unknown> | null;
+export declare function readTokenFile(file: string): CognitoTokens | null;
+/**
+ * The person session from the shared macOS Keychain item (see
+ * ./token-keychain.ts), or null. Not read when the token file is missing:
+ * no file means signed out. Machine-identity and invalidated tokens are
+ * refused, the same as the file loader.
+ */
+export declare function personKeychainTokens(file: string, home: string, env: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
+/**
+ * Person session for `env`: the Keychain item and the token file, the newer
+ * by `expiresAt` (see ./token-keychain.ts). Does not consult hq-cloud's
+ * in-memory fallback, which can surface a different session when the file
+ * is missing or unreadable.
+ */
+export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
+/**
+ * The person's cached session: the shared Keychain item and hq-cloud's file
+ * loader, the newer by `expiresAt`. Writes still go only to the file in this
+ * step.
+ */
+export declare function loadCachedTokens(env?: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
+//# sourceMappingURL=person-token-cache.d.ts.map

package/dist/utils/person-token-cache.js

@@ -0,0 +1,95 @@
+/**
+ * The person's cached Cognito session, read from disk and the shared Keychain
+ * item without any network call. Split out of cognito-session.ts so offline
+ * callers (lane start and the handoff commits) can read the cached ID token
+ * without bundling the refresh and login clients. cognito-session.ts
+ * re-exports these readers.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { accessTokenFingerprint, loadCachedTokens as loadCachedTokensFromFile } from "@indigoai-us/hq-cloud";
+import { pickNewerSession, readKeychainTokens } from "./token-keychain.js";
+/**
+ * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
+ * Deliberately does not use hq-cloud's `loadCachedTokens()`: after a machine
+ * mint in this process, that helper returns in-memory machine tokens when the
+ * person file is absent, which would falsely block the fresh-box fallback.
+ */
+export function personTokenCacheFile(home = os.homedir(), env = process.env) {
+    const override = env.HQ_STATE_DIR?.trim();
+    const stateDir = override && override.length > 0 ? override : path.join(home, ".hq");
+    return path.join(stateDir, "cognito-tokens.json");
+}
+export function decodeJwtPayload(token) {
+    if (!token)
+        return null;
+    const parts = token.split(".");
+    if (parts.length < 2 || !parts[1])
+        return null;
+    try {
+        const json = Buffer.from(parts[1], "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function readTokenFile(file) {
+    try {
+        if (!fs.existsSync(file))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof raw.accessToken !== "string" || typeof raw.idToken !== "string")
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The person session from the shared macOS Keychain item (see
+ * ./token-keychain.ts), or null. Not read when the token file is missing:
+ * no file means signed out. Machine-identity and invalidated tokens are
+ * refused, the same as the file loader.
+ */
+export function personKeychainTokens(file, home, env, keychain = {}) {
+    if (!fs.existsSync(file))
+        return null;
+    const tokens = readKeychainTokens({ env, home, ...keychain });
+    if (!tokens)
+        return null;
+    const claims = decodeJwtPayload(tokens.idToken);
+    const entityType = claims?.["custom:entityType"];
+    if (typeof entityType === "string" && entityType.trim().length > 0)
+        return null;
+    if (fs.existsSync(`${file}.invalid.${accessTokenFingerprint(tokens.accessToken)}`))
+        return null;
+    return tokens;
+}
+/**
+ * Person session for `env`: the Keychain item and the token file, the newer
+ * by `expiresAt` (see ./token-keychain.ts). Does not consult hq-cloud's
+ * in-memory fallback, which can surface a different session when the file
+ * is missing or unreadable.
+ */
+export function readPersonTokenFile(home = os.homedir(), env = process.env, keychain = {}) {
+    const file = personTokenCacheFile(home, env);
+    return pickNewerSession(personKeychainTokens(file, home, env, keychain), readTokenFile(file));
+}
+/**
+ * The person's cached session: the shared Keychain item and hq-cloud's file
+ * loader, the newer by `expiresAt`. Writes still go only to the file in this
+ * step.
+ */
+export function loadCachedTokens(env = process.env, keychain = {}) {
+    const home = os.homedir();
+    const file = personTokenCacheFile(home, env);
+    const fromFile = loadCachedTokensFromFile();
+    return pickNewerSession(personKeychainTokens(file, home, env, keychain), fromFile);
+}
+//# sourceMappingURL=person-token-cache.js.map

package/dist/utils/vault-api.d.ts

@@ -109,7 +109,17 @@ export type CallerIdentity = {
  * {@link resolveCallerPersonUid} does. Use this where the server accepts an
  * agent principal; use `resolveCallerPersonUid` where only a person can act.
  */
-export declare function resolveCallerUid(token: string, baseUrl?: string): Promise<CallerIdentity>;
+export declare function resolveCallerUid(token: string, baseUrl?: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<CallerIdentity>;
+/**
+ * Thrown when the person lookup succeeds but the caller has no person entity.
+ * This is a definitive answer, unlike a network or HTTP failure, so callers
+ * that cache lookups may remember it.
+ */
+export declare class NoPersonEntityError extends Error {
+    constructor();
+}
 /** Thrown when a person-only command runs under an agent machine identity. */
 export declare function agentIdentityUnsupportedError(agentUid: string, command?: string): Error;
 /**
@@ -120,6 +130,16 @@ export declare function agentIdentityUnsupportedError(agentUid: string, command?
 export declare function resolveCallerPersonUid(token: string, baseUrl?: string, opts?: {
     command?: string;
 }): Promise<string>;
+/**
+ * A signal that aborts when any input signal aborts, with that signal's
+ * reason. It stands in for `AbortSignal.any`, which Node only added in 20.3,
+ * so the CLI keeps working on Node 20.0. Call `dispose` once the guarded work
+ * settles to remove the listeners from the inputs.
+ */
+export declare function anySignal(signals: AbortSignal[]): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
 export declare function getEntityUid(token: string, opts: {
     personal?: boolean;
     companySlug?: string;

package/dist/utils/vault-api.js

@@ -735,11 +735,22 @@ export function agentUidFromToken(token) {
  * {@link resolveCallerPersonUid} does. Use this where the server accepts an
  * agent principal; use `resolveCallerPersonUid` where only a person can act.
  */
-export async function resolveCallerUid(token, baseUrl) {
+export async function resolveCallerUid(token, baseUrl, opts = {}) {
     const agentUid = agentUidFromToken(token);
     if (agentUid)
         return { kind: 'agent', uid: agentUid };
-    return { kind: 'person', uid: await lookupCallerPersonUid(token, baseUrl) };
+    return { kind: 'person', uid: await lookupCallerPersonUid(token, baseUrl, opts.signal) };
+}
+/**
+ * Thrown when the person lookup succeeds but the caller has no person entity.
+ * This is a definitive answer, unlike a network or HTTP failure, so callers
+ * that cache lookups may remember it.
+ */
+export class NoPersonEntityError extends Error {
+    constructor() {
+        super('No person entity found for the caller. Sign in to HQ once to provision one.');
+        this.name = 'NoPersonEntityError';
+    }
 }
 /** Thrown when a person-only command runs under an agent machine identity. */
 export function agentIdentityUnsupportedError(agentUid, command) {
@@ -758,14 +769,52 @@ export async function resolveCallerPersonUid(token, baseUrl, opts = {}) {
         throw agentIdentityUnsupportedError(agentUid, opts.command);
     return lookupCallerPersonUid(token, baseUrl);
 }
+/**
+ * A signal that aborts when any input signal aborts, with that signal's
+ * reason. It stands in for `AbortSignal.any`, which Node only added in 20.3,
+ * so the CLI keeps working on Node 20.0. Call `dispose` once the guarded work
+ * settles to remove the listeners from the inputs.
+ */
+export function anySignal(signals) {
+    const controller = new AbortController();
+    const listeners = [];
+    const dispose = () => {
+        for (const [input, listener] of listeners.splice(0))
+            input.removeEventListener('abort', listener);
+    };
+    for (const input of signals) {
+        if (input.aborted) {
+            dispose();
+            controller.abort(input.reason);
+            break;
+        }
+        const listener = () => {
+            dispose();
+            controller.abort(input.reason);
+        };
+        input.addEventListener('abort', listener, { once: true });
+        listeners.push([input, listener]);
+    }
+    return { signal: controller.signal, dispose };
+}
 // Same selection rule as the backend's `resolveCallerPersonUid`: ascending by
 // createdAt, tie-break by uid ascending. Returns the `prs_*` UID.
-async function lookupCallerPersonUid(token, baseUrl) {
+async function lookupCallerPersonUid(token, baseUrl, signal) {
+    const timeout = AbortSignal.timeout(identityLookupTimeoutMs());
+    const combined = signal ? anySignal([timeout, signal]) : { signal: timeout, dispose: () => { } };
+    try {
+        return await lookupCallerPersonUidWith(token, baseUrl, combined.signal);
+    }
+    finally {
+        combined.dispose();
+    }
+}
+async function lookupCallerPersonUidWith(token, baseUrl, signal) {
     const res = await vaultApiFetch({
         token,
         path: '/entity/by-type/person',
         baseUrl,
-        signal: AbortSignal.timeout(identityLookupTimeoutMs()),
+        signal,
     });
     if (!res.ok) {
         if (isUnavailableSecretLoadHttpStatus(res.status)) {
@@ -776,7 +825,7 @@ async function lookupCallerPersonUid(token, baseUrl) {
     const data = (await res.json());
     const persons = (data.entities ?? []).filter((e) => e.type === 'person');
     if (persons.length === 0) {
-        throw new Error('No person entity found for the caller. Sign in to HQ once to provision one.');
+        throw new NoPersonEntityError();
     }
     persons.sort((a, b) => {
         const ac = a.createdAt ?? '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.134",
+  "version": "5.345.135",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {