@indigoai-us/hq-cli 5.129.0 → 5.131.0

package/dist/lib/mesh/live/daemon/doctor.d.ts

@@ -33,6 +33,10 @@ export interface DaemonDoctorReport {
     tokenSource: CognitoTokenSource;
     /** human | agent | unknown — from token claims / machine signal. */
     actorKind: CognitoActorKind;
+    /** Subject in the person login file (`hq whoami`), or empty claims. */
+    whoamiSubject: string;
+    /** Subject the daemon will authenticate as (machine cache, else person file). */
+    daemonSubject: string;
     /** Credential vend refused (disabled / unsupported / 403). */
     presenceRefusal?: DaemonStateFile["presenceRefusal"];
     /** Companies the current presence credential did not include. */

package/dist/lib/mesh/live/daemon/doctor.js

@@ -5,7 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { describeCognitoTokenSource, } from "../../../../utils/cognito-session.js";
+import { describeCognitoTokenSource, formatCognitoSubject, loadMachineCachedTokens, readPersonTokenFile, } from "../../../../utils/cognito-session.js";
 import { listOutboxOperations, outboxStats, } from "../../../work-context/outbox.js";
 import { readSessionState } from "../../../work-context/state.js";
 import { workContextRoot } from "../../../work-context/paths.js";
@@ -145,6 +145,12 @@ export function collectDaemonDoctor(deps = {}) {
         unhealthyReasons.push(`presence credential refused (${presenceRefusal.code}); next retry ${presenceRefusal.nextRetryAt}`);
     }
     const auth = describeCognitoTokenSource({ home, env });
+    const whoamiTokens = readPersonTokenFile(home, env);
+    const daemonTokens = auth.tokenSource === "machine"
+        ? loadMachineCachedTokens(home, env)
+        : whoamiTokens;
+    const whoamiSubject = formatCognitoSubject(whoamiTokens);
+    const daemonSubject = formatCognitoSubject(daemonTokens);
     const emitState = readEmitState(meshRoot);
     const emitRetry = emitRetryDepth(meshRoot);
     if (emitRetry > 0) {
@@ -169,6 +175,8 @@ export function collectDaemonDoctor(deps = {}) {
         oldestSpoolAgeMs,
         tokenSource: auth.tokenSource,
         actorKind: auth.actorKind,
+        whoamiSubject,
+        daemonSubject,
         presenceRefusal,
         presenceDroppedCompanies,
         emitMode,
@@ -200,7 +208,7 @@ export function formatDaemonDoctor(report) {
         lines.push(`spool depth: ${report.spoolDepth}`, `held: ${report.heldCount}`, `held with no local evidence: ${report.heldWithNoLocalEvidence}`, `outbox depth: ${report.outboxDepth}`);
     }
     lines.push(`attributed by device default: ${report.attributedByDeviceDefault}`, `device-default authorization denials: ${report.deviceDefaultAuthorizationDenials}`, `dead-letter: ${report.deadLetterCount}`, `unattributed events: ${report.unattributedEvents.total} ` +
-        `(spool=${report.unattributedEvents.spool} held=${report.unattributedEvents.held} dead-letter=${report.unattributedEvents.deadLetter})`, `token source: ${report.tokenSource}`, `actor kind: ${report.actorKind}`);
+        `(spool=${report.unattributedEvents.spool} held=${report.unattributedEvents.held} dead-letter=${report.unattributedEvents.deadLetter})`, `token source: ${report.tokenSource}`, `actor kind: ${report.actorKind}`, `identity whoami: ${report.whoamiSubject}`, `identity daemon: ${report.daemonSubject}`);
     if (report.emitMode === "legacy") {
         lines.push(`last flush: ${report.lastFlushAt ?? "(never)"}${report.lastFlushResult
             ? ` ok=${report.lastFlushResult.ok} posted=${report.lastFlushResult.posted}`

package/dist/lib/mesh/live/daemon/run.js

@@ -137,6 +137,9 @@ export async function runMeshDaemon(deps = {}) {
     // expires after ~1h to every vend/flush forever, so the second credential
     // renewal (~96 min in) and everything after it failed with HTTP 401 and the
     // daemon went dark once its IoT credentials expired.
+    // ensureCognitoToken refuses a refresh whose subject differs from the
+    // active person cache and restores the file. The daemon must not replace
+    // the operator login with another cached session.
     const defaultGetToken = async () => ensureCognitoToken({ interactive: false, tokenSource: "machine" });
     const getToken = deps.getToken ?? defaultGetToken;
     const resolveMembership = deps.resolveMembership ?? resolveActiveMembershipCompany;

package/dist/lib/mesh/live/emit-client.d.ts

@@ -23,6 +23,8 @@ export interface EmitEventResult {
     status: EmitEventStatus;
     /** Present when status != accepted (no_company_evidence | not_a_member | …). */
     reason?: string;
+    /** Server rejection code when status is rejected (`code`, else `reason`). */
+    code?: string;
     /** Resolved company (accepted, or unassigned-into-single-company). */
     companyUid?: string;
 }

package/dist/lib/mesh/live/emit-client.js

@@ -58,10 +58,7 @@ export function parseEmitResults(body) {
             if (!status)
                 continue;
             const res = { eventId, status };
-            if (typeof r.reason === "string" && r.reason.trim())
-                res.reason = r.reason.trim();
-            else if (typeof r.code === "string" && r.code.trim())
-                res.reason = r.code.trim();
+            applyEmitReasonAndCode(res, r);
             if (typeof r.companyUid === "string" && r.companyUid.trim()) {
                 res.companyUid = r.companyUid.trim();
             }
@@ -86,16 +83,26 @@ export function parseEmitResults(body) {
                 if (!eventId)
                     continue;
                 const res = { eventId, status: "rejected" };
-                if (typeof r.reason === "string" && r.reason.trim())
-                    res.reason = r.reason.trim();
-                else if (typeof r.code === "string" && r.code.trim())
-                    res.reason = r.code.trim();
+                applyEmitReasonAndCode(res, r);
                 out.push(res);
             }
         }
     }
     return out.length > 0 ? out : null;
 }
+function applyEmitReasonAndCode(res, raw) {
+    const reason = typeof raw.reason === "string" ? raw.reason.trim() : "";
+    const code = typeof raw.code === "string" ? raw.code.trim() : "";
+    if (reason)
+        res.reason = reason;
+    else if (code)
+        res.reason = code;
+    if (res.status !== "rejected")
+        return;
+    const rejectionCode = code || reason;
+    if (rejectionCode)
+        res.code = rejectionCode;
+}
 function normalizeStatus(v) {
     if (typeof v !== "string")
         return null;

package/dist/lib/mesh/live/emit.d.ts

@@ -47,8 +47,17 @@ export interface EmitEventsSummary {
     retryDepth: number;
     batches: number;
     statuses: Record<EmitEventStatus, number>;
+    /** Server code for each terminally rejected event. */
+    rejections: Array<{
+        eventId: string;
+        code: string;
+    }>;
     lastPostAt?: string;
 }
+export declare function formatEmitRejectionLines(rejections: ReadonlyArray<{
+    eventId: string;
+    code: string;
+}>): string[];
 /** Drain the retry file, post pending + new events, persist failures. */
 export declare function emitEvents(deps: EmitEventsDeps): Promise<EmitEventsSummary>;
 //# sourceMappingURL=emit.d.ts.map

package/dist/lib/mesh/live/emit.js

@@ -41,9 +41,23 @@ function writeEmitState(workMeshRoot, state) {
         /* best-effort */
     }
 }
+function rejectionCodeFromBody(body, status) {
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+        const rec = body;
+        if (typeof rec.code === "string" && rec.code.trim())
+            return rec.code.trim();
+        if (typeof rec.error === "string" && /^[A-Z0-9_]+$/.test(rec.error.trim())) {
+            return rec.error.trim();
+        }
+    }
+    return `HTTP_${status}`;
+}
 function eventIdOf(e) {
     return typeof e.eventId === "string" && e.eventId.trim() ? e.eventId.trim() : null;
 }
+export function formatEmitRejectionLines(rejections) {
+    return rejections.map((row) => `work-mesh: rejected eventId=${row.eventId} code=${row.code}`);
+}
 /** Drain the retry file, post pending + new events, persist failures. */
 export async function emitEvents(deps) {
     const now = deps.now ?? (() => new Date());
@@ -74,6 +88,7 @@ export async function emitEvents(deps) {
         retryDepth: 0,
         batches: 0,
         statuses: { accepted: 0, unassigned: 0, rejected: 0 },
+        rejections: [],
     };
     const keep = [];
     let anyPosted = false;
@@ -95,7 +110,13 @@ export async function emitEvents(deps) {
                 // Non-retryable 4xx (e.g. 401/400) → drop with a log (never user data).
                 summary.rejected += chunk.length;
                 summary.statuses.rejected += chunk.length;
-                deps.log?.(`emit batch dropped (${chunk.length}) non-retryable status=${result.status}`);
+                const batchCode = rejectionCodeFromBody(result.body, result.status);
+                for (const event of chunk) {
+                    const id = eventIdOf(event);
+                    if (id)
+                        summary.rejections.push({ eventId: id, code: batchCode });
+                }
+                deps.log?.(`emit batch dropped (${chunk.length}) non-retryable status=${result.status} code=${batchCode}`);
             }
             continue;
         }
@@ -121,8 +142,13 @@ export async function emitEvents(deps) {
                 summary.accepted += 1;
             else if (r.status === "unassigned")
                 summary.unassigned += 1;
-            else
+            else if (id) {
                 summary.rejected += 1;
+                summary.rejections.push({
+                    eventId: id,
+                    code: r.code || r.reason || "rejected",
+                });
+            }
         }
     }
     const written = writeEmitRetry(deps.workMeshRoot, keep, retryMax);

package/dist/lib/mesh/live/flush.js

@@ -92,8 +92,14 @@ function isLocallyReconcilableHeldEvent(event, state, workContextRoot) {
         repoIdentityKey,
     }).status === "resolved");
 }
-function deadLetterEnvelope(event, reason, responseCode, at) {
-    return JSON.stringify({ event, reason, responseCode, at });
+function deadLetterEnvelope(event, reason, responseCode, at, code) {
+    return JSON.stringify({
+        event,
+        reason,
+        responseCode,
+        at,
+        ...(code ? { code } : {}),
+    });
 }
 function groupBySession(events) {
     const map = new Map();
@@ -431,7 +437,7 @@ function accountBatchSuccess(body, originalChunk, meshRoot, now, summary, markDi
         const item = byId.get(row.eventId);
         if (!item)
             continue;
-        appendDeadLetterLine(deadLetterEnvelope(item.event, row.code, row.code, at), meshRoot);
+        appendDeadLetterLine(deadLetterEnvelope(item.event, row.code, row.code, at, row.code), meshRoot);
         summary.deadLettered += 1;
         rejectedIds.add(row.eventId);
         markDisposed(item.event);

package/dist/lib/search-index/index.js

@@ -1,6 +1,5 @@
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
-import { createRequire } from 'node:module';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -10,9 +9,9 @@ import { isQmdNativeBindingError } from '../../utils/qmd-native-binding-error.js
 import { isQmdQueryDocumentError } from '../../utils/qmd-query-document-error.js';
 import { isQmdStoreMissingError } from '../../utils/qmd-store-missing-error.js';
 import { isQmdStoreUnopenableError } from '../../utils/qmd-store-unopenable-error.js';
+import { markExpectedUserError } from '../../utils/expected-cli-error.js';
 import { redactErrorText } from '../../utils/redact-error-text.js';
 import { planCommandSpawn } from '../../utils/windows-spawn.js';
-const require = createRequire(import.meta.url);
 /** The `path` implementation for a (possibly injected) platform. */
 function pathFor(platform) {
     return platform === 'win32' ? path.win32 : path.posix;
@@ -1005,6 +1004,22 @@ function describeQmdTermination(stdout, stderr) {
         return `qmd reported: ${summary.reason}`;
     return '';
 }
+/**
+ * qmd caller-state failures that the top-level boundary may surface without a
+ * crash report. The match is deliberately against qmd's raw stderr and a
+ * closed subcommand set: a query containing these words must not change the
+ * disposition of an unrelated qmd exit.
+ */
+function isExpectedQmdCallerFailure(args, stderr) {
+    const subcommand = args[0];
+    if (subcommand === 'get') {
+        return /^Document not found:\s+[^\r\n]+$/m.test(stderr);
+    }
+    if (subcommand === 'collection') {
+        return /(?:^|\b)Failed to parse\s+[^\r\n]+:\s*.+$/m.test(stderr);
+    }
+    return false;
+}
 /** Normalise a spawn result and raise the typed qmd failures. */
 function finishRunQmd(result, bin, args, attribution) {
     const normalized = {
@@ -1215,7 +1230,11 @@ function finishRunQmd(result, bin, args, attribution) {
     if (alreadyExists) {
         throw new QmdCollectionExistsError(message, args, normalized.status, normalized.stdout, normalized.stderr, alreadyExists[1]);
     }
-    throw new QmdExitError(message, args, normalized.status, normalized.stdout, normalized.stderr);
+    const exitError = new QmdExitError(message, args, normalized.status, normalized.stdout, normalized.stderr);
+    if (isExpectedQmdCallerFailure(args, normalized.stderr)) {
+        throw markExpectedUserError(exitError);
+    }
+    throw exitError;
 }
 /** Run qmd with captured output and typed failures. */
 export function runQmd(args, options = {}) {

package/dist/lib/work-context/preflight-contract.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Offline preflight ContextResult shapes that `hq mesh context reconcile --offline`
+ * can emit. migration_pending is a migrate-path status, not a preflight result.
+ *
+ * contractVersion is WORK_CONTEXT_CONTRACT_VERSION. Bump it only together with
+ * contracts/preflight/v<N>/ and the vendored copy in hq-core
+ * (core/hooks/SessionStart/preflight-fixtures.json). Each side pins the version
+ * in tests; a one-sided bump fails that side until the other is updated.
+ */
+import { type ContextResult } from "./contract.js";
+export declare const PREFLIGHT_CONTRACT_VERSION: 1;
+/** Classifications reconcile actually returns on the offline preflight path. */
+export declare const OFFLINE_PREFLIGHT_CLASSIFICATIONS: readonly ["unresolved", "needs_company", "company_conflict", "needs_project", "needs_task", "bound", "untracked"];
+export type OfflinePreflightClassification = (typeof OFFLINE_PREFLIGHT_CLASSIFICATIONS)[number];
+/**
+ * One representative result per emitted classification, using the kind and
+ * delivery the offline path actually returns (company-resolved results are
+ * kind "queued" / delivery "queued"; local-only results are delivery "clean").
+ */
+export declare function preflightFixtureFor(classification: OfflinePreflightClassification): ContextResult;
+export interface PreflightFixtureFile {
+    contractVersion: typeof PREFLIGHT_CONTRACT_VERSION;
+    source: "hq-cli contracts/preflight/v1/fixtures.json";
+    classifications: readonly OfflinePreflightClassification[];
+    fixtures: ContextResult[];
+}
+export declare function buildPreflightFixtures(): PreflightFixtureFile;
+//# sourceMappingURL=preflight-contract.d.ts.map

package/dist/lib/work-context/preflight-contract.js

@@ -0,0 +1,85 @@
+/**
+ * Offline preflight ContextResult shapes that `hq mesh context reconcile --offline`
+ * can emit. migration_pending is a migrate-path status, not a preflight result.
+ *
+ * contractVersion is WORK_CONTEXT_CONTRACT_VERSION. Bump it only together with
+ * contracts/preflight/v<N>/ and the vendored copy in hq-core
+ * (core/hooks/SessionStart/preflight-fixtures.json). Each side pins the version
+ * in tests; a one-sided bump fails that side until the other is updated.
+ */
+import { WORK_CONTEXT_CONTRACT_VERSION, } from "./contract.js";
+export const PREFLIGHT_CONTRACT_VERSION = WORK_CONTEXT_CONTRACT_VERSION;
+/** Classifications reconcile actually returns on the offline preflight path. */
+export const OFFLINE_PREFLIGHT_CLASSIFICATIONS = [
+    "unresolved",
+    "needs_company",
+    "company_conflict",
+    "needs_project",
+    "needs_task",
+    "bound",
+    "untracked",
+];
+const FIXTURE_SESSION = "sid-preflight-fixture";
+const FIXTURE_OP = "op-preflight-fixture";
+function base(classification, kind, delivery) {
+    return {
+        contractVersion: PREFLIGHT_CONTRACT_VERSION,
+        kind,
+        classification,
+        delivery,
+        lifecycle: "open",
+        sessionId: FIXTURE_SESSION,
+        clientOperationId: FIXTURE_OP,
+    };
+}
+/**
+ * One representative result per emitted classification, using the kind and
+ * delivery the offline path actually returns (company-resolved results are
+ * kind "queued" / delivery "queued"; local-only results are delivery "clean").
+ */
+export function preflightFixtureFor(classification) {
+    switch (classification) {
+        case "unresolved":
+            return base("unresolved", "queued", "queued");
+        case "needs_company":
+            return base("needs_company", "needs_company", "clean");
+        case "company_conflict":
+            return base("company_conflict", "company_conflict", "clean");
+        case "needs_project":
+            return {
+                ...base("needs_project", "queued", "queued"),
+                companySlug: "acme",
+                companyUid: "cmp_acme",
+            };
+        case "needs_task":
+            return {
+                ...base("needs_task", "queued", "queued"),
+                companySlug: "acme",
+                companyUid: "cmp_acme",
+                projectId: "dispatch-proj",
+            };
+        case "bound":
+            return {
+                ...base("bound", "queued", "queued"),
+                companySlug: "acme",
+                companyUid: "cmp_acme",
+                projectId: "dispatch-proj",
+                taskId: "US-9",
+            };
+        case "untracked":
+            return base("untracked", "untracked", "clean");
+        default: {
+            const never = classification;
+            return never;
+        }
+    }
+}
+export function buildPreflightFixtures() {
+    return {
+        contractVersion: PREFLIGHT_CONTRACT_VERSION,
+        source: "hq-cli contracts/preflight/v1/fixtures.json",
+        classifications: [...OFFLINE_PREFLIGHT_CLASSIFICATIONS],
+        fixtures: OFFLINE_PREFLIGHT_CLASSIFICATIONS.map(preflightFixtureFor),
+    };
+}
+//# sourceMappingURL=preflight-contract.js.map

package/dist/main.js

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { finishSentrySession, initSentry, Sentry } from "./sentry.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
-import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { environmentalFsErrorMessage, filesystemErrorCaptureContext, filesystemErrorMessage, } from "./utils/environmental-error.js";
 import { syncStateLockMessage } from "./utils/sync-state-lock-error.js";
 import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
 import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.js";
@@ -690,6 +690,12 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             lockMsg
             ? null
             : networkTransportErrorMessage(err);
+        // Windows EPERM/EACCES/EBUSY/UNKNOWN filesystem failures are not proven
+        // caller-owned conditions. Keep them at error level and attach bounded,
+        // installation-independent context so OneDrive/antivirus/path-length
+        // hypotheses can be separated without creating one issue per host path.
+        const fsContext = filesystemErrorCaptureContext(err);
+        const fsMsg = fsContext ? filesystemErrorMessage(err) : null;
         if (qmdMsg) {
             deps.stderr.write(`hq: ${qmdMsg}\n`);
         }
@@ -735,6 +741,10 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (transportMsg) {
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }
+        else if (fsMsg && fsContext) {
+            deps.sentry.captureException(err, fsContext);
+            deps.stderr.write(`hq: ${fsMsg}\n`);
+        }
         else {
             // A genuinely unclassified fault is still captured exactly once. Two
             // shapes attach bounded, hq-derived context so the next occurrence

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

@@ -153,6 +153,45 @@ export declare function wantsMachineCognitoTokens(options?: Pick<EnsureCognitoTo
  * not flip this to machine.
  */
 export declare function resolveCognitoTokenSource(env?: NodeJS.ProcessEnv): CognitoTokenSource;
+/**
+ * Refresh wrote a different Cognito subject than the active cache.
+ * Callers must not fall through to browser login or machine mint — that
+ * would replace the operator session the refusal is protecting.
+ */
+export declare class IdentitySwapRefusal extends Error {
+    constructor(message: string);
+}
+export declare function isIdentitySwapRefusal(err: unknown): err is IdentitySwapRefusal;
+/** `sub` plus `custom:entityUid` from an unverified JWT. Either may be absent. */
+export declare function cognitoSubjectFromToken(token: string | undefined): {
+    sub: string | null;
+    entityUid: string | null;
+};
+/** Stable subject key. Null when neither sub nor entity uid is present. */
+export declare function cognitoSubjectKey(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined): string | null;
+/** Doctor/status line. Claims only — never token material. */
+export declare function formatCognitoSubject(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined): string;
+/**
+ * Person cache as stored on disk for `env`. 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): CognitoTokens | null;
+/**
+ * Refresh the active person session and refuse a subject change.
+ *
+ * hq-cloud's `refreshTokens` saves as soon as Cognito responds, and on a
+ * cache miss or unreadable file it can refresh an in-memory session for a
+ * different subject (same app client). Snapshot the active file first; if
+ * the response subject differs, put the bytes back and leave them there.
+ */
+export declare function refreshActivePersonTokens(cached: CognitoTokens, env?: NodeJS.ProcessEnv): Promise<CognitoTokens>;
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export declare function actorKindFromIdToken(idToken: string | undefined): CognitoActorKind;
 /**

package/dist/utils/cognito-session.js

@@ -409,6 +409,115 @@ function decodeJwtPayload(token) {
         return null;
     }
 }
+/**
+ * Refresh wrote a different Cognito subject than the active cache.
+ * Callers must not fall through to browser login or machine mint — that
+ * would replace the operator session the refusal is protecting.
+ */
+export class IdentitySwapRefusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdentitySwapRefusal";
+    }
+}
+export function isIdentitySwapRefusal(err) {
+    return err instanceof IdentitySwapRefusal;
+}
+/** `sub` plus `custom:entityUid` from an unverified JWT. Either may be absent. */
+export function cognitoSubjectFromToken(token) {
+    const claims = decodeJwtPayload(token);
+    const sub = typeof claims?.sub === "string" && claims.sub.length > 0 ? claims.sub : null;
+    const entity = claims?.["custom:entityUid"];
+    const entityUid = typeof entity === "string" && entity.length > 0 ? entity : null;
+    return { sub, entityUid };
+}
+/** Stable subject key. Null when neither sub nor entity uid is present. */
+export function cognitoSubjectKey(tokens) {
+    if (!tokens)
+        return null;
+    const fromId = cognitoSubjectFromToken(tokens.idToken);
+    const fromAccess = cognitoSubjectFromToken(tokens.accessToken);
+    const sub = fromId.sub ?? fromAccess.sub;
+    const entityUid = fromId.entityUid ?? fromAccess.entityUid;
+    if (!sub && !entityUid)
+        return null;
+    return `${sub ?? ""}|${entityUid ?? ""}`;
+}
+/** Doctor/status line. Claims only — never token material. */
+export function formatCognitoSubject(tokens) {
+    if (!tokens)
+        return "sub=- entityUid=-";
+    const fromId = cognitoSubjectFromToken(tokens.idToken);
+    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;
+    }
+}
+/**
+ * Person cache as stored on disk for `env`. 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) {
+    return readTokenFile(personTokenCacheFile(home, env));
+}
+function restoreTokenFile(file, before) {
+    if (before) {
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = path.join(dir, `.cognito-tokens.json.restore.${process.pid}`);
+        fs.writeFileSync(tmp, before, { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        return;
+    }
+    if (fs.existsSync(file))
+        fs.unlinkSync(file);
+}
+/**
+ * Refresh the active person session and refuse a subject change.
+ *
+ * hq-cloud's `refreshTokens` saves as soon as Cognito responds, and on a
+ * cache miss or unreadable file it can refresh an in-memory session for a
+ * different subject (same app client). Snapshot the active file first; if
+ * the response subject differs, put the bytes back and leave them there.
+ */
+export async function refreshActivePersonTokens(cached, env = process.env) {
+    const file = personTokenCacheFile(os.homedir(), env);
+    const onDisk = readTokenFile(file);
+    const diskKey = cognitoSubjectKey(onDisk);
+    const cachedKey = cognitoSubjectKey(cached);
+    if (diskKey && cachedKey && diskKey !== cachedKey) {
+        const message = `refusing token refresh: cached subject ${formatCognitoSubject(cached)} ` +
+            `does not match active subject ${formatCognitoSubject(onDisk)}; token file left unchanged`;
+        console.error(message);
+        throw new IdentitySwapRefusal(message);
+    }
+    const activeTokens = diskKey && cachedKey && diskKey === cachedKey ? onDisk : cached;
+    const activeKey = cognitoSubjectKey(activeTokens);
+    const before = fs.existsSync(file) ? fs.readFileSync(file) : null;
+    const refreshed = await refreshTokens(DEFAULT_COGNITO, activeTokens.refreshToken, activeTokens.accessToken);
+    const nextKey = cognitoSubjectKey(refreshed);
+    if (activeKey && nextKey && nextKey !== activeKey) {
+        restoreTokenFile(file, before);
+        const message = `refusing token refresh: refreshed subject ${formatCognitoSubject(refreshed)} ` +
+            `does not match active subject ${formatCognitoSubject(activeTokens)}; token file left unchanged`;
+        console.error(message);
+        throw new IdentitySwapRefusal(message);
+    }
+    return refreshed;
+}
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export function actorKindFromIdToken(idToken) {
     const claims = decodeJwtPayload(idToken);
@@ -616,10 +725,12 @@ async function ensureCognitoTokenUnserialized(options) {
             if (interactive) {
                 console.error(chalk.dim("  Refreshing expiring HQ session..."));
             }
-            const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+            const refreshed = await refreshActivePersonTokens(cached);
             return refreshed.accessToken;
         }
         catch (err) {
+            if (isIdentitySwapRefusal(err))
+                throw err;
             // Transient/network/server errors stay person errors — never mint machine.
             if (!isDefinitivePersonAuthRejection(err)) {
                 throw err;
@@ -676,10 +787,12 @@ async function ensureCognitoIdTokenUnserialized(options) {
             if (interactive) {
                 console.error(chalk.dim("  Refreshing expiring HQ session..."));
             }
-            const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+            const refreshed = await refreshActivePersonTokens(cached);
             return refreshed.idToken;
         }
         catch (err) {
+            if (isIdentitySwapRefusal(err))
+                throw err;
             if (!isDefinitivePersonAuthRejection(err)) {
                 throw err;
             }
@@ -778,10 +891,13 @@ async function refreshCachedSessionUnserialized(options) {
         return { refreshed: true };
     }
     try {
-        await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+        await refreshActivePersonTokens(cached);
         return { refreshed: true };
     }
     catch (err) {
+        if (isIdentitySwapRefusal(err)) {
+            return { refreshed: false, reason: err.message };
+        }
         // Transient/network/server refresh errors stay person failures.
         if (!isDefinitivePersonAuthRejection(err)) {
             return {

package/dist/utils/environmental-error.d.ts

@@ -7,4 +7,22 @@
  * result means "this is a normal error; handle it as usual (capture to Sentry)".
  */
 export declare function environmentalFsErrorMessage(err: unknown): string | null;
+export type FilesystemErrorCaptureContext = {
+    fingerprint: ["fs-error", string, string, string];
+    tags: Record<string, string>;
+    extra: {
+        fs_path: string;
+        fs_reason: string;
+    };
+};
+/** Return only the registered command path, never positional user data. */
+export declare function hqCommand(argv?: readonly string[]): string;
+/**
+ * Build stable Sentry context for known OS filesystem refusals. The failure is
+ * intentionally still captured: this is instrumentation for the OneDrive /
+ * antivirus / path-length hypotheses, not an expected-error suppression.
+ */
+export declare function filesystemErrorCaptureContext(err: unknown, argv?: readonly string[]): FilesystemErrorCaptureContext | null;
+/** Plain operator guidance for a captured filesystem failure. */
+export declare function filesystemErrorMessage(err: unknown): string | null;
 //# sourceMappingURL=environmental-error.d.ts.map