@indigoai-us/hq-cli 5.345.154 → 5.345.155

package/dist/commands/storage-offload.js

@@ -23,7 +23,10 @@
  *         recorded in the sync journal as synced and cloud-only, then the
  *         placeholder is written, then the local file is removed. A path the
  *         sync ignore rules exclude is refused and the excluding rule is named
- *         (for `.hqinclude`, with the exact line to add). Other unsynced
+ *         (for `.hqinclude`, with the exact line to add). A library original
+ *         restored by `hq library fetch`, which the journal does not know, is
+ *         pointed back at its verified blob `.hq-offload/blobs/<sha256>` in the
+ *         company vault (`point-at-library`), uploading nothing. Other unsynced
  *         company files are skipped with "run hq sync first".
  *       - Any other file points at its personal-vault sync object the same
  *         way, or is uploaded to the personal vault's `.hq-offload/blobs/`.
@@ -71,6 +74,12 @@ export const RUN_SYNC_FIRST = "run hq sync first";
 export const SYNC_MAX_FILE_BYTES = 50 * 1024 * 1024;
 /** Object metadata key holding the sha256 of a company-vault offload upload. */
 export const VAULT_SHA256_METADATA_KEY = "hq-sha256";
+/**
+ * Object metadata key on library blobs (`hq library add`). hq-pro's put
+ * presign binds it to the `x-amz-checksum-sha256` it signs, and S3 checks that
+ * checksum against the bytes, so it is the stored bytes' sha256.
+ */
+export const CONTENT_SHA256_METADATA_KEY = "hq-content-sha256";
 const DAY_MS = 86_400_000;
 const PERSONAL_BUCKET_PREFIX = "hq-vault-prs-";
 /** Top-level HQ-root folder that holds offloaded blobs in the personal vault. */
@@ -469,6 +478,9 @@ export function s3VaultObjectStore(bucket, s3, opts = {}) {
                     const sha = res.Metadata?.[VAULT_SHA256_METADATA_KEY];
                     if (sha && HEX64.test(sha))
                         head.sha256 = sha;
+                    const content = res.Metadata?.[CONTENT_SHA256_METADATA_KEY]?.toLowerCase();
+                    if (content && HEX64.test(content))
+                        head.contentSha256 = content;
                     return head;
                 }
                 catch (err) {
@@ -731,6 +743,145 @@ async function pointCurrentFileAtVault(file, vault, deps, fsOps) {
     }
     await fsOps.removeOriginal(abs);
 }
+// ── Restored library originals (`hq library fetch`) ─────────────────────────
+/** Library placeholders are small; anything bigger is not one. */
+const MAX_LIBRARY_PLACEHOLDER_BYTES = 64 * 1024;
+/**
+ * The library placeholder at `file`, when it is a blob-keyed company library
+ * copy (`hq library add`) for exactly `rel`. Anything else (a synced-path
+ * placeholder, a personal offload, another path, not a placeholder): null.
+ */
+function readLibraryPlaceholder(file, rel) {
+    let text;
+    try {
+        const st = fs.lstatSync(file);
+        if (!st.isFile() || st.size > MAX_LIBRARY_PLACEHOLDER_BYTES)
+            return null;
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    return libraryPointerFor(text, rel);
+}
+function libraryPointerFor(text, rel) {
+    const pointer = parsePointer(text);
+    if (!pointer || !isCompanyOffloadCopy(pointer) || pointer.orphaned || pointer.path !== toPosix(rel))
+        return null;
+    return { pointer, text };
+}
+/**
+ * Why a local file cannot be pointed at its library blob, or null when it
+ * can: the blob `.hq-offload/blobs/<sha256>` is in the company vault, its size
+ * matches, and its recorded sha256 (`hq-content-sha256`, or `hq-sha256`)
+ * equals the local file's. With `pointer` (the placeholder beside the file),
+ * the placeholder must also name these exact bytes.
+ */
+async function libraryBlobRefusal(pointer, digest, vault) {
+    if (pointer && (pointer.sha256 !== digest.sha256 || pointer.size !== digest.size)) {
+        return "This file differs from the library copy its placeholder points at, so it was kept.";
+    }
+    const key = companyOffloadKey(digest.sha256);
+    const head = await vault.head(key);
+    if (!head)
+        return `The library copy (${key}) is not in the company vault, so this file was kept.`;
+    const stored = head.contentSha256 ?? head.sha256;
+    if (head.size !== digest.size || (stored !== undefined && stored !== digest.sha256)) {
+        return `The library copy in the company vault (${key}) does not match this file, so it was kept.`;
+    }
+    if (stored === undefined) {
+        return `The library copy in the company vault (${key}) has no sha256 to check against, so this file was kept.`;
+    }
+    return null;
+}
+/** Whether `digest`'s verified library blob is in the company vault. A failed check counts as no. */
+async function libraryBlobMatches(digest, vault) {
+    try {
+        return (await libraryBlobRefusal(null, digest, vault)) === null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Placeholder text for a restored library original that has none on disk:
+ * the company vault's own placeholder for this path when it is still there
+ * and names these exact bytes (so its `hq-asset` block, tags and caption are
+ * kept byte for byte), otherwise a plain library pointer to the blob.
+ */
+async function libraryPlaceholderText(rel, target, digest, vault, deps) {
+    const key = `${target.key}${PLACEHOLDER_SUFFIX}`;
+    const head = await vault.head(key).catch(() => null);
+    if (head && head.size > 0 && head.size <= MAX_LIBRARY_PLACEHOLDER_BYTES) {
+        const tmp = path.join(deps.tmpDir(), `hq-offload-placeholder-${crypto.randomBytes(6).toString("hex")}`);
+        try {
+            await vault.download(key, tmp, head.etag);
+            const found = libraryPointerFor(await fs.promises.readFile(tmp, "utf8"), rel);
+            if (found && found.pointer.sha256 === digest.sha256 && found.pointer.size === digest.size)
+                return found.text;
+        }
+        catch {
+            // Fall back to a plain pointer below.
+        }
+        finally {
+            await fs.promises.rm(tmp, { force: true });
+        }
+    }
+    return renderPointer({
+        path: toPosix(rel),
+        size: digest.size,
+        sha256: digest.sha256,
+        vault: "company",
+        key: companyOffloadKey(digest.sha256),
+        offloadedAt: deps.now().toISOString().replace(/\.\d{3}Z$/, "Z"),
+    });
+}
+/**
+ * Turn a restored library original back into a placeholder. Its bytes are
+ * already in the company vault at `.hq-offload/blobs/<sha256>`, so nothing is
+ * uploaded. Right before the local file is removed, the blob is checked again
+ * and the local file is hashed again; both must still match. With the library
+ * placeholder beside the file, that placeholder is left exactly as it is;
+ * otherwise one is written (fsynced) first.
+ */
+async function pointCurrentFileAtLibrary(file, vault, deps, fsOps) {
+    const { plan, target, stat: before, digest, besideText } = file;
+    if (target.vault !== "company" || !before || !digest)
+        throw new Error(`'${plan.path}' is not a company file.`);
+    const abs = containedPath(deps.hqRoot, plan.path);
+    const placeholder = `${abs}${PLACEHOLDER_SUFFIX}`;
+    const beside = besideText === undefined ? null : libraryPointerFor(besideText, plan.path);
+    if (besideText !== undefined && !beside)
+        throw new Error(`'${plan.path}${PLACEHOLDER_SUFFIX}' is not a library placeholder.`);
+    const refusal = await libraryBlobRefusal(beside?.pointer ?? null, digest, vault);
+    if (refusal)
+        throw new Error(refusal);
+    const changed = new Error(`'${plan.path}' changed while offloading. Nothing was replaced.`);
+    const unchanged = async () => {
+        const st = await fs.promises.stat(abs);
+        return st.size === before.size && st.mtimeMs === before.mtimeMs && st.size === digest.size;
+    };
+    if (!(await unchanged()))
+        throw changed;
+    let wrote = false;
+    if (beside) {
+        const current = await fs.promises.readFile(placeholder, "utf8").catch(() => null);
+        if (current !== besideText) {
+            throw new Error(`'${plan.path}${PLACEHOLDER_SUFFIX}' changed while offloading. Nothing was replaced.`);
+        }
+    }
+    else {
+        await fsOps.writePlaceholder(placeholder, await libraryPlaceholderText(plan.path, target, digest, vault, deps));
+        wrote = true;
+    }
+    const again = await digestFile(abs);
+    if (again.sha256 !== digest.sha256 || again.size !== digest.size || !(await unchanged())) {
+        if (wrote)
+            await fs.promises.rm(placeholder, { force: true });
+        throw changed;
+    }
+    await fsOps.removeOriginal(abs);
+}
 /** Resumable upload state for one company vault key. */
 function uploadStatePath(deps, target) {
     const dir = deps.uploadStateDir ? deps.uploadStateDir() : path.join(os.homedir(), ".hq", "offload-uploads");
@@ -914,8 +1065,17 @@ async function planCurrentFiles(rels, opts, deps, openVault) {
                 continue;
             throw err;
         }
-        if (!st.isFile() || fs.existsSync(`${abs}${PLACEHOLDER_SUFFIX}`))
+        if (!st.isFile())
             continue;
+        // A file with a placeholder beside it is left alone, except a restored
+        // library original next to its own blob-keyed library placeholder (what
+        // `hq library fetch` leaves once HQ sync restores the placeholder).
+        let beside;
+        if (fs.existsSync(`${abs}${PLACEHOLDER_SUFFIX}`)) {
+            beside = readLibraryPlaceholder(`${abs}${PLACEHOLDER_SUFFIX}`, rel) ?? undefined;
+            if (!beside)
+                continue;
+        }
         const idle = Math.max(0, Math.floor((now - st.mtimeMs) / DAY_MS));
         if (st.size < opts.minBytes || idle < opts.idleDays)
             continue;
@@ -938,6 +1098,23 @@ async function planCurrentFiles(rels, opts, deps, openVault) {
             }
         }
         const record = deps.syncRecord ? await deps.syncRecord(target) : null;
+        if (beside) {
+            // A file the sync journal knows keeps the old behaviour: left alone.
+            if (record || target.vault !== "company" || !deps.openVaultObjects)
+                continue;
+            const besideDigest = await digestFile(abs);
+            plan.vault_key = beside.pointer.key;
+            const refusal = await libraryBlobRefusal(beside.pointer, besideDigest, await openVault(target)).catch((err) => `Could not check the library copy in the company vault (${failureMessage(err)}), so this file was kept.`);
+            if (refusal) {
+                plan.reason = refusal;
+            }
+            else {
+                plan.action = "point-at-library";
+                plan.placeholder = "kept";
+            }
+            planned.push({ plan, target, stat: st, digest: besideDigest, besideText: beside.text });
+            continue;
+        }
         let digest;
         if (record?.remoteEtag && record.hash && record.size === st.size) {
             digest = await digestFile(abs);
@@ -946,9 +1123,22 @@ async function planCurrentFiles(rels, opts, deps, openVault) {
                 plan.synced = head !== null && head.etag === normalizeEtag(record.remoteEtag) && head.size === st.size;
             }
         }
+        let libraryBlob = false;
+        if (!plan.synced && !record && target.vault === "company" && deps.openVaultObjects) {
+            // Not in the sync journal at all, e.g. a library original restored by
+            // `hq library fetch` after HQ sync dropped its placeholder. Its bytes
+            // may already be in the company vault at their content-addressed key.
+            digest ??= await digestFile(abs);
+            libraryBlob = await libraryBlobMatches(digest, await openVault(target));
+        }
         if (plan.synced) {
             plan.action = "point-at-vault";
         }
+        else if (libraryBlob && digest) {
+            plan.action = "point-at-library";
+            plan.vault_key = companyOffloadKey(digest.sha256);
+            plan.placeholder = "written";
+        }
         else if (target.vault === "company") {
             const ex = deps.syncExclusion?.(rel);
             if (ex?.excluded) {
@@ -1046,6 +1236,10 @@ async function runCurrent(opts, deps, result) {
                 await pointCurrentFileAtVault(file, await openVault(target), deps, fsOps);
                 action = "point-at-vault";
             }
+            else if (plan.action === "point-at-library") {
+                await pointCurrentFileAtLibrary(file, await openVault(target), deps, fsOps);
+                action = "point-at-library";
+            }
             else if (plan.action === "upload+offload") {
                 if (target.vault !== "company" || !deps.openCompanyUploader)
                     throw new Error(UPDATE_SYNC);

package/dist/commands/storage.js

@@ -839,6 +839,7 @@ const CURRENT_ACTION_LABEL = {
     "point-at-vault": "point at vault",
     upload: "upload",
     "upload+offload": "upload+offload",
+    "point-at-library": "point at library copy",
     skip: "skip",
 };
 /** One `--current` plan line: path, size, owning vault, sync state, action. */
@@ -848,6 +849,10 @@ function formatCurrentFile(f) {
     if (f.action === "upload+offload") {
         parts.push(`(${f.bytes} bytes to the company ${f.company ?? "?"} vault at ${f.vault_key ?? f.path})`);
     }
+    if (f.action === "point-at-library") {
+        const placeholder = f.placeholder === "kept" ? "placeholder kept as is" : "placeholder written";
+        parts.push(`(already in the company ${f.company ?? "?"} vault at ${f.vault_key ?? "?"}, nothing uploaded, ${placeholder})`);
+    }
     if (f.action === "skip" && f.reason)
         parts.push(`(${f.reason})`);
     return parts.join("  ");

package/dist/lib/daemon/machine-login.d.ts

@@ -17,4 +17,24 @@ export interface MachineAuthenticatorOptions {
 export declare function machineTokenExpiresAt(token: string): number;
 /** Authenticate without using hq-cloud's persistent machine token cache. */
 export declare function authenticateMachineCredentials(credentials: StdinMachineCredentials, options?: MachineAuthenticatorOptions): Promise<string>;
+export interface MachineSessionTokens {
+    accessToken: string;
+    idToken: string;
+    /** Present only when Cognito returned one for this app client. */
+    refreshToken?: string;
+    expiresAt: number;
+}
+/**
+ * Mint a full machine session in memory. Unlike hq-cloud's
+ * getValidMachineTokens, this writes no token cache and takes no lock file,
+ * and it keeps the refresh token Cognito returns (hq-cloud discards it).
+ * The client is the creds file's clientId, else HQ_COGNITO_CLIENT_ID, else
+ * DEFAULT_COGNITO.clientId, the same order hq-cloud uses for a machine mint.
+ *
+ * Before returning, the token pair must pass the same identity check hq-cloud
+ * runs on every machine mint (client_id/aud, username/sub, entity type and
+ * uid, and no company markers on a non-company identity). A mismatch throws
+ * `identity_mismatch` and no token leaves this function.
+ */
+export declare function authenticateMachineSession(credentials: StdinMachineCredentials, options?: MachineAuthenticatorOptions): Promise<MachineSessionTokens>;
 //# sourceMappingURL=machine-login.d.ts.map

package/dist/lib/daemon/machine-login.js

@@ -1,5 +1,6 @@
 /** Ephemeral Cognito machine login for a resident hqd process. */
 import { DEFAULT_COGNITO } from "../../utils/cognito-session.js";
+import { machineTokenPairMatchesIdentity } from "./machine-token-identity.js";
 const MAX_STDIN_BYTES = 64 * 1024;
 export class MachineLoginError extends Error {
     code;
@@ -57,11 +58,16 @@ export function machineTokenExpiresAt(token) {
         throw new MachineLoginError("auth_failed", "hqd sign-in failed; the identity provider returned an invalid token");
     }
 }
-/** Authenticate without using hq-cloud's persistent machine token cache. */
-export async function authenticateMachineCredentials(credentials, options = {}) {
+const DEFAULT_AUTH_FAILURE = "hqd sign-in failed; check the machine credentials and try again";
+/** Client resolution order shared with hq-cloud: creds, then env, then default. */
+function resolveMachineClientId(credentials, env) {
+    return credentials.clientId ?? env.HQ_COGNITO_CLIENT_ID ?? DEFAULT_COGNITO.clientId;
+}
+/** Run USER_PASSWORD_AUTH and return the AuthenticationResult object. Never persists anything. */
+async function initiateMachineAuth(credentials, options, failureMessage) {
     const env = options.env ?? process.env;
     const region = credentials.region ?? env.AWS_REGION ?? DEFAULT_COGNITO.region;
-    const clientId = credentials.clientId ?? env.HQ_COGNITO_CLIENT_ID ?? DEFAULT_COGNITO.clientId;
+    const clientId = resolveMachineClientId(credentials, env);
     const endpoint = options.endpoint ?? `https://cognito-idp.${region}.amazonaws.com/`;
     let response;
     try {
@@ -80,23 +86,62 @@ export async function authenticateMachineCredentials(credentials, options = {})
         });
     }
     catch {
-        throw new MachineLoginError("auth_failed", "hqd sign-in failed; check the machine credentials and try again");
+        throw new MachineLoginError("auth_failed", failureMessage);
     }
     let body;
     try {
         body = await response.json();
     }
     catch {
-        throw new MachineLoginError("auth_failed", "hqd sign-in failed; check the machine credentials and try again");
+        throw new MachineLoginError("auth_failed", failureMessage);
     }
     if (!response.ok || !body || typeof body !== "object" || Array.isArray(body)) {
-        throw new MachineLoginError("auth_failed", "hqd sign-in failed; check the machine credentials and try again");
+        throw new MachineLoginError("auth_failed", failureMessage);
     }
     const result = body.AuthenticationResult;
-    const idToken = result && typeof result === "object" ? result.IdToken : undefined;
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+        throw new MachineLoginError("auth_failed", failureMessage);
+    }
+    return result;
+}
+/** Authenticate without using hq-cloud's persistent machine token cache. */
+export async function authenticateMachineCredentials(credentials, options = {}) {
+    const result = await initiateMachineAuth(credentials, options, DEFAULT_AUTH_FAILURE);
+    const idToken = result.IdToken;
     if (typeof idToken !== "string" || !idToken) {
-        throw new MachineLoginError("auth_failed", "hqd sign-in failed; check the machine credentials and try again");
+        throw new MachineLoginError("auth_failed", DEFAULT_AUTH_FAILURE);
     }
     return idToken;
 }
+/**
+ * Mint a full machine session in memory. Unlike hq-cloud's
+ * getValidMachineTokens, this writes no token cache and takes no lock file,
+ * and it keeps the refresh token Cognito returns (hq-cloud discards it).
+ * The client is the creds file's clientId, else HQ_COGNITO_CLIENT_ID, else
+ * DEFAULT_COGNITO.clientId, the same order hq-cloud uses for a machine mint.
+ *
+ * Before returning, the token pair must pass the same identity check hq-cloud
+ * runs on every machine mint (client_id/aud, username/sub, entity type and
+ * uid, and no company markers on a non-company identity). A mismatch throws
+ * `identity_mismatch` and no token leaves this function.
+ */
+export async function authenticateMachineSession(credentials, options = {}) {
+    const failure = "Machine sign-in failed; check the machine credentials and try again";
+    const result = await initiateMachineAuth(credentials, options, failure);
+    const { AccessToken, IdToken, RefreshToken, ExpiresIn } = result;
+    if (typeof AccessToken !== "string" || !AccessToken || typeof IdToken !== "string" || !IdToken) {
+        throw new MachineLoginError("auth_failed", failure);
+    }
+    const clientId = resolveMachineClientId(credentials, options.env ?? process.env);
+    if (!machineTokenPairMatchesIdentity({ accessToken: AccessToken, idToken: IdToken }, credentials, clientId)) {
+        throw new MachineLoginError("identity_mismatch", "Machine sign-in returned tokens that do not match the requested machine identity");
+    }
+    const lifetimeSeconds = typeof ExpiresIn === "number" && Number.isFinite(ExpiresIn) ? ExpiresIn : 3600;
+    return {
+        accessToken: AccessToken,
+        idToken: IdToken,
+        ...(typeof RefreshToken === "string" && RefreshToken ? { refreshToken: RefreshToken } : {}),
+        expiresAt: Date.now() + lifetimeSeconds * 1000,
+    };
+}
 //# sourceMappingURL=machine-login.js.map

package/dist/lib/daemon/machine-token-identity.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Faithful port of hq-cloud's private `machineTokenPairMatchesIdentity` and its
+ * helpers (`decodeJwtClaims`, `hasCompanyMarkers`, `companyClaimsMatch`).
+ *
+ * Source: @indigoai-us/hq-cloud v6.18.91, dist/cognito-auth.js (search for
+ * `function machineTokenPairMatchesIdentity`). hq-cloud does not export it in
+ * that version. Keep this file in step with that function; once hq-cloud
+ * exports it, import the export and delete this port.
+ *
+ * Claims are decoded without verifying the signature. That matches hq-cloud:
+ * the tokens come straight from Cognito over TLS, and the check exists to bind
+ * them to the requested machine identity and to refuse company-scoped tokens
+ * on a non-company identity, not to authenticate the issuer.
+ */
+import type { MachineCreds } from "@indigoai-us/hq-cloud";
+type Claims = Record<string, unknown>;
+export interface MachineTokenPair {
+    accessToken: string;
+    idToken: string;
+}
+export type MachineIdentityCreds = Pick<MachineCreds, "username"> & Partial<Pick<MachineCreds, "entityType" | "entityUid">>;
+export declare function decodeJwtClaims(token: string): Claims | null;
+/** True when a token carries any company-outpost marker claim. */
+export declare function hasCompanyMarkers(claims: Claims): boolean;
+/**
+ * True only when the access/ID token pair belongs to `creds` on
+ * `expectedClientId`: access `client_id` and ID `aud` equal the client, the
+ * entity type and uid match (agt_* agent, or out_* outpost with delegated
+ * claims), the ID token binds to the creds username or entityUid, both tokens
+ * share a subject, and a non-company identity carries no company markers.
+ */
+export declare function machineTokenPairMatchesIdentity(tokens: MachineTokenPair, creds: MachineIdentityCreds, expectedClientId: string): boolean;
+export {};
+//# sourceMappingURL=machine-token-identity.d.ts.map

package/dist/lib/daemon/machine-token-identity.js

@@ -0,0 +1,123 @@
+/**
+ * Faithful port of hq-cloud's private `machineTokenPairMatchesIdentity` and its
+ * helpers (`decodeJwtClaims`, `hasCompanyMarkers`, `companyClaimsMatch`).
+ *
+ * Source: @indigoai-us/hq-cloud v6.18.91, dist/cognito-auth.js (search for
+ * `function machineTokenPairMatchesIdentity`). hq-cloud does not export it in
+ * that version. Keep this file in step with that function; once hq-cloud
+ * exports it, import the export and delete this port.
+ *
+ * Claims are decoded without verifying the signature. That matches hq-cloud:
+ * the tokens come straight from Cognito over TLS, and the check exists to bind
+ * them to the requested machine identity and to refuse company-scoped tokens
+ * on a non-company identity, not to authenticate the issuer.
+ */
+export function decodeJwtClaims(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length < 2)
+            return null;
+        const payloadB64 = parts[1];
+        const normalized = payloadB64.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+        const json = Buffer.from(padded, "base64").toString("utf-8");
+        const claims = JSON.parse(json);
+        return claims && typeof claims === "object" && !Array.isArray(claims) ? claims : null;
+    }
+    catch {
+        return null;
+    }
+}
+const owns = (bag, key) => Object.prototype.hasOwnProperty.call(bag, key);
+/** True when a token carries any company-outpost marker claim. */
+export function hasCompanyMarkers(claims) {
+    return (claims["custom:entityType"] === "company-outpost" ||
+        owns(claims, "custom:ownerCompanyUid") ||
+        owns(claims, "custom:companyOutpostId"));
+}
+function companyClaimsMatch(claims, creds, clientId) {
+    const company = claims["custom:ownerCompanyUid"];
+    return (claims["custom:entityType"] === "company-outpost" &&
+        claims["custom:entityUid"] === creds.entityUid &&
+        claims["custom:authClientId"] === clientId &&
+        typeof company === "string" &&
+        /^cmp_[A-Za-z0-9]+$/.test(company) &&
+        claims["custom:companyOutpostId"] === `outpost_${company}` &&
+        (!process.env.HQ_COMPANY_UID || company === process.env.HQ_COMPANY_UID) &&
+        (!process.env.HQ_COMPANY_OUTPOST_ID || claims["custom:companyOutpostId"] === process.env.HQ_COMPANY_OUTPOST_ID) &&
+        !owns(claims, "custom:delegatedSub") &&
+        !owns(claims, "custom:delegatedEmail") &&
+        typeof claims.sub === "string" &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(claims.sub) &&
+        typeof claims.exp === "number" &&
+        claims.exp * 1000 > Date.now());
+}
+/**
+ * True only when the access/ID token pair belongs to `creds` on
+ * `expectedClientId`: access `client_id` and ID `aud` equal the client, the
+ * entity type and uid match (agt_* agent, or out_* outpost with delegated
+ * claims), the ID token binds to the creds username or entityUid, both tokens
+ * share a subject, and a non-company identity carries no company markers.
+ */
+export function machineTokenPairMatchesIdentity(tokens, creds, expectedClientId) {
+    const accessClaims = decodeJwtClaims(tokens.accessToken);
+    const idClaims = decodeJwtClaims(tokens.idToken);
+    if (!accessClaims || !idClaims)
+        return false;
+    if (creds.entityType === "company-outpost") {
+        if (!creds.entityUid ||
+            !/^out_[0-9A-HJKMNP-TV-Z]{26}$/.test(creds.entityUid) ||
+            !companyClaimsMatch(idClaims, creds, expectedClientId) ||
+            !companyClaimsMatch(accessClaims, creds, expectedClientId) ||
+            idClaims["custom:ownerCompanyUid"] !== accessClaims["custom:ownerCompanyUid"])
+            return false;
+    }
+    else if (hasCompanyMarkers(idClaims) || hasCompanyMarkers(accessClaims))
+        return false;
+    const stringClaim = (claims, key) => {
+        const value = claims[key];
+        return typeof value === "string" && value.length > 0 ? value : null;
+    };
+    const accessClientId = accessClaims.client_id;
+    const idAudience = idClaims.aud;
+    const accessUsername = stringClaim(accessClaims, "username") ?? stringClaim(accessClaims, "cognito:username");
+    const accessSub = stringClaim(accessClaims, "sub");
+    const idUsername = stringClaim(idClaims, "cognito:username") ?? stringClaim(idClaims, "username");
+    const idSub = stringClaim(idClaims, "sub");
+    const entityType = stringClaim(idClaims, "custom:entityType");
+    const entityUid = stringClaim(idClaims, "custom:entityUid");
+    const delegatedSub = stringClaim(idClaims, "custom:delegatedSub");
+    const delegatedEmail = stringClaim(idClaims, "custom:delegatedEmail");
+    const hasValidMachineClaimShape = entityType === "company-outpost" ||
+        (entityType === "agent" && entityUid !== null && entityUid.startsWith("agt_")) ||
+        (entityType === "outpost" &&
+            entityUid !== null &&
+            entityUid.startsWith("out_") &&
+            delegatedSub !== null &&
+            delegatedEmail !== null);
+    // Legacy agent credentials did not persist entityType; "agent" is the only
+    // valid inference (same as hq-cloud).
+    const expectedEntityType = creds.entityType ?? "agent";
+    const entityMatchesCreds = entityType === expectedEntityType && (creds.entityUid === undefined || entityUid === creds.entityUid);
+    // In the email-alias pool the canonical username is a UUID, so creds that
+    // persist entityUid bind through the unique custom:entityUid claim; legacy
+    // creds without entityUid keep the username binding (same as hq-cloud).
+    const idTokenMatchesCreds = idUsername === creds.username ||
+        idSub === creds.username ||
+        (creds.entityUid !== undefined && entityUid === creds.entityUid);
+    const subjectBindings = [];
+    if (accessUsername !== null && idUsername !== null)
+        subjectBindings.push(accessUsername === idUsername);
+    if (accessSub !== null && idSub !== null)
+        subjectBindings.push(accessSub === idSub);
+    const tokensShareSubject = subjectBindings.length > 0 && subjectBindings.every(Boolean);
+    return (accessClaims.token_use === "access" &&
+        accessClientId === expectedClientId &&
+        idClaims.token_use === "id" &&
+        idAudience === expectedClientId &&
+        hasValidMachineClaimShape &&
+        entityMatchesCreds &&
+        idTokenMatchesCreds &&
+        tokensShareSubject);
+}
+//# sourceMappingURL=machine-token-identity.js.map

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

@@ -18,7 +18,15 @@ export interface ReadLanesFlagOptions {
     env?: NodeJS.ProcessEnv;
     createClient?: LanesFlagClientFactory;
     getToken?: () => string | Promise<string>;
+    /** Second token source used once after a 401. Defaults to `getToken`, else a forced session refresh. */
+    refreshToken?: () => string | Promise<string>;
     reportFailure?: (error: unknown) => void;
+    /** Fetch used by the default flag client; tests inject this to drive HTTP outcomes. */
+    fetch?: typeof fetch;
+    /** Last-known-good cache directory; null disables it. Defaults to the HQ state dir. */
+    cacheDir?: string | null;
+    retryBackoffMs?: number;
+    sleep?: (ms: number) => Promise<void>;
 }
 export declare function readLanesFlagLocalOverride(flagKey: string, env?: NodeJS.ProcessEnv): boolean | null;
 export type LanesRegistryFlagResult = {
@@ -27,10 +35,23 @@ export type LanesRegistryFlagResult = {
 } | {
     state: "unknown";
 };
+export declare const LANES_FLAG_RETRY_BACKOFF_MS = 250;
+export declare const LANES_FLAG_CACHE_FILE = "lanes-flag-cache.json";
+/**
+ * Oldest last-known-good entry a failed read may serve. Every successful
+ * snapshot read restamps resolvedAt, so this bounds how long a value can
+ * outlive its last confirmation by the registry.
+ */
+export declare const LANES_FLAG_CACHE_MAX_AGE_MS: number;
+/** Error message safe for stderr: token-like substrings removed, length bounded. */
+export declare function sanitizeFlagErrorMessage(error: unknown): string;
 /**
  * Read a lanes flag once for each company identity in this CLI process. The
- * cache contains only an in-flight or settled decision result; it is never
- * written to disk. A local override is checked on every call and wins first.
+ * in-process cache holds the in-flight or settled result. The last registry
+ * snapshot value per flag and company is also kept in the HQ state dir and
+ * used when a later read fails transiently (timeout, network error, 5xx) and
+ * the value was confirmed within LANES_FLAG_CACHE_MAX_AGE_MS. A local override
+ * is checked on every call and wins first.
  */
 export declare function readLanesRegistryFlag(flagKey: string, options?: ReadLanesFlagOptions): Promise<boolean>;
 /** Read a lanes flag while preserving registry failure as an explicit unknown state. */