@indigoai-us/hq-cli 5.345.133 → 5.345.135

package/dist/lib/fingerprint/self.js

@@ -0,0 +1,191 @@
+/**
+ * Build the fingerprint for the current HQ session (`hq fingerprint self`).
+ *
+ * Sources, in order:
+ * - session id: the first valid value of HQ_SESSION_ID, CLAUDE_CODE_SESSION_ID,
+ *   CLAUDE_SESSION_ID, CODEX_SESSION_ID, CODEX_THREAD_ID, GROK_SESSION_ID (same
+ *   order as core/scripts/lib/session-id.sh). workspace/sessions/.current is
+ *   never read: it names whichever session wrote last, not this one.
+ * - identity: `custom:entityUid` on the cached ID token, then the agent uid in
+ *   the machine creds, then this session's fingerprint.yaml cache (only when
+ *   it was written for the same token owner), then a person lookup (3s cap,
+ *   skipped with --offline, without a session id, and for outpost and agent
+ *   principals). A lookup is cached once it succeeds or the server says the
+ *   caller has no person entity; transient failures retry next time.
+ * - machine: HQ_MACHINE_ID, then `<hqRoot>/.hq/machine-id`.
+ * - company: the session's meta.yaml company_slug, then HQ_COMPANY, then
+ *   HQ_SPAWN_COMPANY. A value that is not a slug is replaced with `-`.
+ *
+ * The result is written to workspace/sessions/<sid>/fingerprint.yaml when a
+ * session id is known. registerSelfFingerprint (US-007) then records the
+ * fingerprint with hq-pro once per session and writes `registered_at`, or
+ * `registration_skipped` when hq-pro will never accept it (outpost hosts, a
+ * 403). It never prints and never throws; failures go to ~/.hq/fingerprint.log.
+ * registry-client is imported lazily, only on the registration path.
+ *
+ * The commit-msg hook runs `self --offline` on every commit, so this module
+ * keeps its static imports light: cognito-session, hq-cloud, and vault-api are
+ * loaded only on the paths that need them. The network-free core lives in
+ * self-core.ts so lane start and the handoff commits never reach them.
+ */
+import * as fs from "node:fs";
+import { finishFingerprint, IDENTITY_LOOKUP_TIMEOUT_MS, IDENTITY_UID_RE, identityContext, machineIdForFingerprint, readRegistrationState, recordRegistrationState, } from "./self-core.js";
+export * from "./self-core.js";
+async function defaultLoadIdToken() {
+    const { loadCachedTokens } = await import("../../utils/cognito-session.js");
+    return loadCachedTokens()?.idToken ?? null;
+}
+/** An unparseable creds file yields null, so it never marks the host as fleet. */
+export async function defaultLoadMachineCreds() {
+    const { loadMachineCreds, machineCredsFilePath } = await import("@indigoai-us/hq-cloud");
+    if (!fs.existsSync(machineCredsFilePath()))
+        return null;
+    const creds = loadMachineCreds();
+    return creds ? { entityType: creds.entityType, entityUid: creds.entityUid } : null;
+}
+async function defaultResolveIdentity(idToken, signal) {
+    const { resolveCallerUid } = await import("../../utils/vault-api.js");
+    return resolveCallerUid(idToken, undefined, { signal });
+}
+/** Races the lookup against the timeout and aborts the request when time runs out. */
+async function withTimeout(run, ms) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            const err = new Error(`identity lookup timed out after ${ms}ms`);
+            controller.abort(err);
+            reject(err);
+        }, ms);
+    });
+    try {
+        return await Promise.race([run(controller.signal), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** vault-api's NoPersonEntityError, matched by name so vault-api stays lazily loaded. */
+function isNoPersonEntityError(err) {
+    return err instanceof Error && err.name === "NoPersonEntityError";
+}
+export async function buildSelfFingerprint(deps) {
+    const warn = deps.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    let idToken = null;
+    try {
+        idToken = await (deps.loadIdToken ?? defaultLoadIdToken)();
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not read the cached token: ${err.message}`);
+    }
+    let creds = null;
+    try {
+        creds = await (deps.loadMachineCreds ?? defaultLoadMachineCreds)();
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not read machine creds: ${err.message}`);
+    }
+    const ctx = identityContext(deps, idToken, creds);
+    if (ctx.needsLookup && ctx.idToken) {
+        const resolveIdentity = deps.resolveIdentity ?? defaultResolveIdentity;
+        const token = ctx.idToken;
+        try {
+            const resolved = await withTimeout((signal) => resolveIdentity(token, signal), deps.lookupTimeoutMs ?? IDENTITY_LOOKUP_TIMEOUT_MS);
+            ctx.lookupDone = true;
+            if (IDENTITY_UID_RE.test(resolved.uid)) {
+                ctx.identityUid = resolved.uid;
+                ctx.source = "lookup";
+            }
+        }
+        catch (err) {
+            // "No person entity" is a definitive answer; anything else may be transient.
+            if (isNoPersonEntityError(err))
+                ctx.lookupDone = true;
+            warn(`hq fingerprint: identity lookup failed: ${err.message}`);
+        }
+    }
+    return finishFingerprint(deps, ctx);
+}
+/**
+ * Records this session's fingerprint with hq-pro (POST /v1/fingerprints), at
+ * most once per session. Fire-and-forget: it never writes to stdout or stderr
+ * and never throws, so the printed fingerprint and the exit code stay the
+ * same whatever the registry does.
+ *
+ * hq-pro denies company-outpost machine tokens, so outpost hosts skip the call
+ * and record `registration_skipped: outpost`. A 403 is also final and is
+ * recorded the same way. A 404 means the registry is not deployed for this
+ * API, so it records `registration_skipped: unavailable` and the session stops
+ * calling. Any other failure is logged and retried next run.
+ */
+export async function registerSelfFingerprint(self, deps) {
+    const env = deps.env ?? process.env;
+    if (deps.register === false)
+        return { status: "skipped", reason: "--no-register" };
+    if (deps.offline || env.HQ_FINGERPRINT_OFFLINE === "1")
+        return { status: "skipped", reason: "offline" };
+    const { fingerprint, company, identityUid, sessionId, machineId, hostKind } = self;
+    if (!fingerprint || !company || company === "-" || !identityUid || !sessionId || !machineId) {
+        return { status: "skipped", reason: "incomplete fingerprint" };
+    }
+    // Cache read and write problems stay quiet here: the build already warned.
+    const quiet = () => { };
+    const state = readRegistrationState(deps.hqRoot, sessionId, fingerprint, quiet);
+    if (!state)
+        return { status: "skipped", reason: "no session cache" };
+    if (state.registeredAt)
+        return { status: "already-registered" };
+    if (state.skipped)
+        return { status: "skipped", reason: state.skipped };
+    try {
+        const registry = await import("./registry-client.js");
+        const log = (op, detail) => registry.appendFingerprintLog(op, detail, { dir: deps.logDir, now: deps.now });
+        if (hostKind === "outpost") {
+            log("register", `skipped outpost: hq-pro denies company-outpost machine tokens fingerprint=${fingerprint}`);
+            recordRegistrationState(deps.hqRoot, sessionId, fingerprint, { skipped: "outpost" }, quiet);
+            return { status: "skipped", reason: "outpost" };
+        }
+        let token = null;
+        try {
+            token = await (deps.loadIdToken ?? defaultLoadIdToken)();
+        }
+        catch (err) {
+            log("register", `failed: could not read the cached token: ${err.name}`);
+            return { status: "failed", reason: "token unreadable" };
+        }
+        if (!token)
+            return { status: "skipped", reason: "not signed in" };
+        const result = await registry.registerFingerprint({
+            fingerprint,
+            companySlug: company,
+            identityUid,
+            machineId: machineIdForFingerprint(machineId),
+            hostKind,
+            sessionId,
+        }, token, { fetch: deps.fetch, timeoutMs: deps.timeoutMs });
+        if (result.ok) {
+            const at = (deps.now ?? (() => new Date()))().toISOString();
+            recordRegistrationState(deps.hqRoot, sessionId, fingerprint, { registeredAt: at }, quiet);
+            return { status: "registered" };
+        }
+        const detail = registry.describeFailure(result);
+        if (result.status === 403) {
+            // A denial will not change on retry; stop calling for this fingerprint.
+            log("register", `skipped forbidden: ${detail} fingerprint=${fingerprint}`);
+            recordRegistrationState(deps.hqRoot, sessionId, fingerprint, { skipped: "forbidden" }, quiet);
+            return { status: "skipped", reason: "forbidden" };
+        }
+        if (result.status === 404) {
+            // The registry route is not deployed here; stop calling for this session.
+            log("register", `skipped unavailable: ${detail} fingerprint=${fingerprint}`);
+            recordRegistrationState(deps.hqRoot, sessionId, fingerprint, { skipped: "unavailable" }, quiet);
+            return { status: "skipped", reason: "unavailable" };
+        }
+        log("register", `failed: ${detail} fingerprint=${fingerprint}`);
+        return { status: "failed", reason: detail };
+    }
+    catch (err) {
+        return { status: "failed", reason: err.message };
+    }
+}
+//# sourceMappingURL=self.js.map

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

@@ -66,6 +66,8 @@ export type ProveDetachedFn = (pid: number) => DetachProof;
 export type KillProcessFn = (pid: number, signal?: NodeJS.Signals) => void;
 export interface SpawnLaneDeps {
     env?: NodeJS.ProcessEnv;
+    /** Builds the lane's fingerprint from the worker env. Defaults to laneStartFingerprint. */
+    buildFingerprint?: (hqRoot: string, workerEnv: NodeJS.ProcessEnv) => string | null;
     /** Test seam for the default-off quota account failover registry gate. */
     quotaAccountFailoverEnabled?: boolean;
     /** Return the selected retry transition without writing or starting a worker. */
@@ -255,7 +257,23 @@ export declare function buildProviderCommand(provider: LaneProvider, input: {
 export declare function workerEnv(base: NodeJS.ProcessEnv, resolved: {
     envVar: string;
     home: string;
-}, laneId: string, hqRoot: string, autoCompactTokens?: number, meshCompany?: LaneCompanyRef, workerPolicyDir?: string, registryWorker?: LaneRecord["registry_worker"], homedir?: () => string): NodeJS.ProcessEnv;
+}, laneId: string, hqRoot: string, autoCompactTokens?: number, meshCompany?: LaneCompanyRef, workerPolicyDir?: string, registryWorker?: LaneRecord["registry_worker"], homedir?: () => string, session?: WorkerSessionEnv): NodeJS.ProcessEnv;
+/** Session ids a worker must not inherit from the process that spawns it. */
+export declare const WORKER_SESSION_ENV_VARS: readonly ["HQ_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CLAUDE_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "GROK_SESSION_ID"];
+/**
+ * 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 declare function laneStartFingerprint(hqRoot: string, env: NodeJS.ProcessEnv): string | null;
+export interface WorkerSessionEnv {
+    /** The worker's own provider session id, when known before launch. */
+    workerSessionId?: string;
+    /** The senior's session id, when the senior is a session. */
+    parentSessionId?: string;
+}
+/** The session identity a lane turn exports to its worker (see `workerEnv`). */
+export declare function laneWorkerSessionEnv(lane: Pick<LaneRecord, "senior">, workerSessionId: string | undefined): WorkerSessionEnv;
 export declare const WORKER_POLICY_HOOK_CAPABILITY = "# hq-capability: worker-policy-dir v1";
 /** Grok does not run HQ hooks; Claude and Codex use the installed capability marker. */
 export declare function workerPolicyDeliveryMode(hqRoot: string, provider: LaneProvider): "hook" | "prompt";

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