@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/lib/sync-core/rollout-state.d.ts

@@ -0,0 +1,24 @@
+import { type SyncCorePlanFigures, type SyncCoreVaultKind, type SyncCoreVaultPhase } from "./engine-home.js";
+export interface RolloutVault {
+    uid: string;
+    kind: SyncCoreVaultKind;
+    slug?: string;
+    phase: SyncCoreVaultPhase;
+    engineHome: string;
+    legacyOffSince?: string;
+    legacyAlreadyOff?: true;
+    plan?: SyncCorePlanFigures;
+    hold?: string;
+}
+export interface SyncCoreRolloutState {
+    version: 1;
+    readAt: string;
+    release: string;
+    binaryPath: string;
+    vaults: RolloutVault[];
+    error?: string;
+}
+export declare function syncCoreRolloutStatePath(home: string): string;
+export declare function readSyncCoreRolloutState(home: string): SyncCoreRolloutState | null;
+export declare function writeSyncCoreRolloutState(home: string, state: SyncCoreRolloutState): void;
+//# sourceMappingURL=rollout-state.d.ts.map

package/dist/lib/sync-core/rollout-state.js

@@ -0,0 +1,94 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isSyncCoreVaultUid } from "./engine-home.js";
+function planFigures(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const p = value;
+    if (typeof p.at !== "string")
+        return null;
+    const numbers = ["uploads", "downloads", "deletes", "remoteRows", "localFiles"];
+    if (numbers.some((key) => typeof p[key] !== "number" || !Number.isFinite(p[key])))
+        return null;
+    return {
+        at: p.at,
+        uploads: p.uploads,
+        downloads: p.downloads,
+        deletes: p.deletes,
+        remoteRows: p.remoteRows,
+        localFiles: p.localFiles,
+    };
+}
+export function syncCoreRolloutStatePath(home) {
+    return path.join(home, ".hq", "sync-core", "rollout.json");
+}
+function vault(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const v = value;
+    if (!isSyncCoreVaultUid(v.uid))
+        return null;
+    if (v.kind !== "personal" && v.kind !== "company")
+        return null;
+    if (typeof v.engineHome !== "string" || !path.isAbsolute(v.engineHome))
+        return null;
+    if (v.legacyOffSince !== undefined && typeof v.legacyOffSince !== "string")
+        return null;
+    if (v.phase === undefined && typeof v.legacyOffSince === "string")
+        v.phase = "full";
+    if (v.phase !== "warming" && v.phase !== "full")
+        return null;
+    if (v.kind === "company" && (typeof v.slug !== "string" || !/^[a-z0-9][a-z0-9_-]*$/.test(v.slug)))
+        return null;
+    const plan = v.plan === undefined ? undefined : planFigures(v.plan);
+    if (plan === null)
+        return null;
+    if (v.hold !== undefined && typeof v.hold !== "string")
+        return null;
+    return {
+        uid: v.uid,
+        kind: v.kind,
+        ...(typeof v.slug === "string" ? { slug: v.slug } : {}),
+        phase: v.phase,
+        engineHome: v.engineHome,
+        ...(typeof v.legacyOffSince === "string" ? { legacyOffSince: v.legacyOffSince } : {}),
+        ...(v.legacyAlreadyOff === true ? { legacyAlreadyOff: true } : {}),
+        ...(plan ? { plan } : {}),
+        ...(typeof v.hold === "string" ? { hold: v.hold } : {}),
+    };
+}
+export function readSyncCoreRolloutState(home) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(syncCoreRolloutStatePath(home), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    if (obj.version !== 1 || typeof obj.release !== "string" || typeof obj.binaryPath !== "string")
+        return null;
+    if (typeof obj.readAt !== "string" || !Array.isArray(obj.vaults))
+        return null;
+    const vaults = obj.vaults.map(vault);
+    if (vaults.some((v) => v === null))
+        return null;
+    return {
+        version: 1,
+        readAt: obj.readAt,
+        release: obj.release,
+        binaryPath: obj.binaryPath,
+        vaults: vaults,
+        ...(typeof obj.error === "string" ? { error: obj.error } : {}),
+    };
+}
+export function writeSyncCoreRolloutState(home, state) {
+    const file = syncCoreRolloutStatePath(home);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+//# sourceMappingURL=rollout-state.js.map

package/dist/lib/vault-sync-switches.d.ts

@@ -38,4 +38,9 @@ export declare function unreadableSwitchesWarning(reason: string): string;
  * (`HQ_SYNC_SKIP_COMPANIES`, `HQ_SYNC_SKIP_PERSONAL`). Empty when all are on.
  */
 export declare function vaultSkipEnv(switches: VaultSyncSwitches): Record<string, string>;
+export interface VaultSyncSwitchPatch {
+    personal?: boolean;
+    companies?: Record<string, boolean>;
+}
+export declare function writeVaultSyncSwitches(home: string, patch: VaultSyncSwitchPatch): boolean;
 //# sourceMappingURL=vault-sync-switches.d.ts.map

package/dist/lib/vault-sync-switches.js

@@ -83,4 +83,47 @@ export function vaultSkipEnv(switches) {
         env.HQ_SYNC_SKIP_PERSONAL = "1";
     return env;
 }
+export function writeVaultSyncSwitches(home, patch) {
+    const file = vaultSyncSettingsPath(home);
+    let prefs = {};
+    let text = null;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT")
+            throw err;
+    }
+    if (text !== null) {
+        const raw = JSON.parse(text);
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            throw new Error(`${file} is not a JSON object`);
+        prefs = { ...raw };
+    }
+    let changed = false;
+    if (patch.personal !== undefined && prefs.personalSyncEnabled !== patch.personal) {
+        prefs.personalSyncEnabled = patch.personal;
+        changed = true;
+    }
+    if (patch.companies && Object.keys(patch.companies).length > 0) {
+        const existing = prefs.workspaceSyncEnabled;
+        const map = typeof existing === "object" && existing !== null && !Array.isArray(existing)
+            ? { ...existing }
+            : {};
+        for (const [slug, enabled] of Object.entries(patch.companies)) {
+            if (map[slug] !== enabled) {
+                map[slug] = enabled;
+                changed = true;
+            }
+        }
+        prefs.workspaceSyncEnabled = map;
+    }
+    if (!changed)
+        return false;
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(prefs, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    return true;
+}
 //# sourceMappingURL=vault-sync-switches.js.map

package/dist/run/script-bound-schema.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Strict env-schema reader for `hq run --script` (feedback_0e6abcb8).
+ *
+ * With --script, `hq run` must not load the caller's schema through varlock:
+ * a varlock graph can run `exec()` resolvers, load plugins, or import other
+ * files, and any of that runs inside the CLI process while the fetched
+ * secrets are in memory. A caller could write `LEAK=exec(...)` next to a
+ * script-locked `hq()` item and read the secret before the script binding is
+ * checked.
+ *
+ * So the --script path reads the schema and local files with this parser and
+ * never builds a varlock graph. Only these lines are accepted (allowlist):
+ *   - blank lines and `#` comments. A comment may carry only the decorators
+ *     listed in ALLOWED_DECORATORS; any other `@decorator` is refused.
+ *   - `KEY=hq()` or `KEY=hq("NAME")` / `KEY=hq('NAME')`: an HQ secret.
+ *   - `KEY=literal`, optionally quoted, with no `(`, `)`, `$`, `{`, `}` or
+ *     backtick: a static value. An empty value is allowed.
+ * Everything else is refused with an error before any secret is fetched.
+ * Later files override earlier ones, as in the varlock path.
+ */
+export interface StrictSchema {
+    statics: Record<string, string>;
+    /** Env key -> vault secret name. */
+    secrets: Map<string, string>;
+}
+export declare function parseStrictSchemaFiles(paths: string[]): StrictSchema;
+//# sourceMappingURL=script-bound-schema.d.ts.map

package/dist/run/script-bound-schema.js

@@ -0,0 +1,97 @@
+/**
+ * Strict env-schema reader for `hq run --script` (feedback_0e6abcb8).
+ *
+ * With --script, `hq run` must not load the caller's schema through varlock:
+ * a varlock graph can run `exec()` resolvers, load plugins, or import other
+ * files, and any of that runs inside the CLI process while the fetched
+ * secrets are in memory. A caller could write `LEAK=exec(...)` next to a
+ * script-locked `hq()` item and read the secret before the script binding is
+ * checked.
+ *
+ * So the --script path reads the schema and local files with this parser and
+ * never builds a varlock graph. Only these lines are accepted (allowlist):
+ *   - blank lines and `#` comments. A comment may carry only the decorators
+ *     listed in ALLOWED_DECORATORS; any other `@decorator` is refused.
+ *   - `KEY=hq()` or `KEY=hq("NAME")` / `KEY=hq('NAME')`: an HQ secret.
+ *   - `KEY=literal`, optionally quoted, with no `(`, `)`, `$`, `{`, `}` or
+ *     backtick: a static value. An empty value is allowed.
+ * Everything else is refused with an error before any secret is fetched.
+ * Later files override earlier ones, as in the varlock path.
+ */
+import * as fs from 'node:fs';
+const KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SECRET_NAME = /^[A-Z][A-Z0-9_]*(\/[A-Z][A-Z0-9_]+)*$/;
+const HQ_CALL = /^hq\(\s*(?:(["'])([^"']*)\1)?\s*\)$/;
+const UNSAFE_LITERAL = /[()${}`]/;
+const ALLOWED_DECORATORS = new Set([
+    'hqCompany',
+    'required',
+    'optional',
+    'sensitive',
+    'public',
+    'defaultRequired',
+    'defaultSensitive',
+]);
+function refuse(file, lineNo, reason) {
+    throw new Error(`hq run --script reads ${file} in strict mode and refused line ${lineNo}: ${reason}. ` +
+        'With --script only KEY=hq(...), KEY=literal and the decorators ' +
+        `${[...ALLOWED_DECORATORS].map((d) => '@' + d).join(', ')} are allowed; resolvers such as exec() and @plugin/@import are not. ` +
+        'Remove them, or run without --script.');
+}
+function unquote(value) {
+    if (value.length >= 2) {
+        const q = value[0];
+        if ((q === '"' || q === "'") && value[value.length - 1] === q) {
+            const inner = value.slice(1, -1);
+            if (!inner.includes(q))
+                return inner;
+        }
+    }
+    return value;
+}
+export function parseStrictSchemaFiles(paths) {
+    const statics = {};
+    const secrets = new Map();
+    for (const file of paths) {
+        const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+        lines.forEach((raw, index) => {
+            const lineNo = index + 1;
+            const line = raw.trim();
+            if (line === '')
+                return;
+            if (line.startsWith('#')) {
+                for (const match of line.matchAll(/@([A-Za-z_][A-Za-z0-9_]*)/g)) {
+                    if (!ALLOWED_DECORATORS.has(match[1]))
+                        refuse(file, lineNo, `decorator @${match[1]} is not allowed`);
+                }
+                // An allowed decorator may take only a quoted literal argument.
+                const stripped = line.replace(/@hqCompany\(\s*"[^"()$`{}]*"\s*\)/g, '');
+                if (/[()]/.test(stripped) && /@/.test(stripped))
+                    refuse(file, lineNo, 'decorator arguments are not allowed');
+                return;
+            }
+            const eq = line.indexOf('=');
+            if (eq <= 0)
+                refuse(file, lineNo, 'expected KEY=value');
+            const key = line.slice(0, eq).trim().replace(/^export\s+/, '');
+            if (!KEY.test(key))
+                refuse(file, lineNo, 'invalid key');
+            const value = line.slice(eq + 1).trim();
+            const hq = HQ_CALL.exec(value);
+            if (hq) {
+                const name = hq[2] || key;
+                if (!SECRET_NAME.test(name))
+                    refuse(file, lineNo, `invalid secret name for ${key}`);
+                secrets.set(key, name);
+                delete statics[key];
+                return;
+            }
+            if (UNSAFE_LITERAL.test(value))
+                refuse(file, lineNo, `${key} is not a plain literal or hq() call`);
+            statics[key] = unquote(value);
+            secrets.delete(key);
+        });
+    }
+    return { statics, secrets };
+}
+//# sourceMappingURL=script-bound-schema.js.map

package/dist/secrets-env-action.d.ts

@@ -76,6 +76,8 @@ export declare function requestedApiKeyCompany(flagCompany: string | undefined):
 export declare function assertApiKeyCompany(token: string, requested: string, commandLabel: string): Promise<string>;
 export declare function loadRevealedSecrets(token: string, companyUid: string, keys: string[], usage?: SecretUsage, options?: {
     allowOfflineFallback?: boolean;
+    /** Filled with each returned row's scriptLock.mode (undefined when absent). */
+    lockModes?: Map<string, string | undefined>;
 }): Promise<Map<string, string>>;
 /**
  * Emit `hq secrets env` output and terminate deterministically.

package/dist/secrets-env-action.js

@@ -129,7 +129,7 @@ export function parseSecretNameList(input) {
 // refuse a key bound to a different company. Without it the fetch route reads
 // from the key's own company, which made `--company <other>` silently return
 // the key company's same-named secret (P0 triage, 2026-10-11).
-async function loadRevealedSecretsViaApiKey(token, keys, companyUid) {
+async function loadRevealedSecretsViaApiKey(token, keys, companyUid, lockModes) {
     const resolved = new Map();
     const requested = [...new Set(keys)];
     const cacheScope = "__api_key__";
@@ -170,6 +170,10 @@ async function loadRevealedSecretsViaApiKey(token, keys, companyUid) {
             throw new Error(`Failed to fetch secret '${name}': malformed fetch response`);
         }
         removeCacheEntry(cacheScope, name);
+        // The API-key fetch route returns the secret's scriptLock (the vault denies
+        // an enforced secret on this route, since it carries no script usage).
+        const mode = secret.scriptLock?.mode;
+        lockModes?.set(name, typeof mode === "string" ? mode : undefined);
         resolved.set(name, secret.value);
     }
     return resolved;
@@ -219,7 +223,7 @@ export async function assertApiKeyCompany(token, requested, commandLabel) {
 }
 export async function loadRevealedSecrets(token, companyUid, keys, usage, options = {}) {
     if (token.startsWith(HQ_API_KEY_PREFIX)) {
-        return loadRevealedSecretsViaApiKey(token, keys, companyUid);
+        return loadRevealedSecretsViaApiKey(token, keys, companyUid, options.lockModes);
     }
     const resolved = new Map();
     const requested = [...new Set(keys)];
@@ -284,6 +288,7 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage, option
                     throw new Error("Invalid secret load response from vault");
                 }
                 seenNames.add(s.name);
+                options.lockModes?.set(s.name, s.scriptLock?.mode);
                 if (s.revokedAt != null) {
                     errorsByName.set(s.name, {
                         code: "revoked",

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

@@ -19,11 +19,12 @@
  *   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 { hasPersonCachedSession, isMachineCredsFileEnvSet, wantsMachineCognitoTokens, type CognitoTokenSource } from "./machine-principal-state.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";
+export { hasPersonCachedSession, isMachineCredsFileEnvSet, wantsMachineCognitoTokens };
+export type { CognitoTokenSource };
 /** Actor kind derived from the active token / machine-creds signal. */
 export type CognitoActorKind = "human" | "agent" | "unknown";
 /**
@@ -97,13 +98,6 @@ export declare const DEFAULT_HQ_ROOT: string;
 export declare function machineTokenStateDir(home?: string, env?: NodeJS.ProcessEnv): string;
 /** Absolute path of the machine-token cache file (daemon state dir). */
 export declare function machineTokenCacheFile(home?: string, env?: NodeJS.ProcessEnv): string;
-/**
- * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
- * Explicit env remains the primary opt-in for daemon units. Fresh agent boxes
- * without the env still mint via {@link wantsMachineCognitoTokens}'s
- * default-file fallback when no usable person session exists.
- */
-export declare function isMachineCredsFileEnvSet(env?: NodeJS.ProcessEnv): boolean;
 /** Default machine-creds path hq-cloud also checks when the env is unset. */
 export declare function defaultMachineCredsFile(home?: string): string;
 export type EnsureCognitoTokenOptions = {
@@ -127,33 +121,12 @@ export type EnsureCognitoTokenOptions = {
 export declare const HQ_NO_BROWSER_LOGIN_ENV = "HQ_NO_BROWSER_LOGIN";
 /** An explicit `interactive` option wins; otherwise interactive unless the env switch is "1". */
 export declare function resolveInteractiveLogin(options: Pick<EnsureCognitoTokenOptions, "interactive">, env?: NodeJS.ProcessEnv): boolean;
-/**
- * True when a usable person Cognito cache file exists under the effective
- * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the
- * person path even when the default machine-creds file is also on disk
- * (no-flip guarantee).
- */
-export declare function hasPersonCachedSession(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Fresh-box / Outpost bootstrap: env unset, not forced to person, no person
  * cache, and the default machine-creds file is readable. Distinct from
  * explicit `HQ_MACHINE_CREDS_FILE` / `{ tokenSource: "machine" }` opt-in.
  */
 export declare function isDefaultMachineCredsFallback(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">, env?: NodeJS.ProcessEnv): boolean;
-/**
- * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
- *
- * Machine path when:
- *   - explicit `{ tokenSource: "machine" }` and creds are readable, or
- *   - `HQ_MACHINE_CREDS_FILE` is set and readable, or
- *   - fresh-box fallback: env unset, no person cache, default
- *     `~/.hq-agent/machine-creds.json` readable.
- *
- * Explicit `{ tokenSource: "person" }` never uses machine creds. A present
- * person cache keeps the person path even when the default creds file exists
- * (do not flip a human's commands onto machine tokens).
- */
-export declare function wantsMachineCognitoTokens(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">, env?: NodeJS.ProcessEnv): boolean;
 /**
  * Which Cognito token source this process will use for doctor / status / whoami.
  * Matches {@link wantsMachineCognitoTokens}: env opt-in, or default-file

package/dist/utils/cognito-session.js

@@ -26,6 +26,7 @@ import * as path from "path";
 import * as yaml from "js-yaml";
 import chalk from "chalk";
 import { isExpiring, refreshTokens, saveCachedTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
+import { hasPersonCachedSession, isMachineCredsFileEnvSet, probeMachineIdentity, wantsMachineCognitoTokens, } from "./machine-principal-state.js";
 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";
@@ -36,6 +37,7 @@ 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 };
+export { hasPersonCachedSession, isMachineCredsFileEnvSet, wantsMachineCognitoTokens };
 /**
  * Override for where machine-minted Cognito tokens are cached.
  * Default: the work-mesh daemon state dir (`~/.hq/work-mesh/daemon`), so a
@@ -253,16 +255,6 @@ export function machineTokenStateDir(home = os.homedir(), env = process.env) {
 export function machineTokenCacheFile(home = os.homedir(), env = process.env) {
     return path.join(machineTokenStateDir(home, env), "cognito-tokens.json");
 }
-/**
- * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
- * Explicit env remains the primary opt-in for daemon units. Fresh agent boxes
- * without the env still mint via {@link wantsMachineCognitoTokens}'s
- * default-file fallback when no usable person session exists.
- */
-export function isMachineCredsFileEnvSet(env = process.env) {
-    const raw = env.HQ_MACHINE_CREDS_FILE;
-    return typeof raw === "string" && raw.trim().length > 0;
-}
 /** Default machine-creds path hq-cloud also checks when the env is unset. */
 export function defaultMachineCredsFile(home = os.homedir()) {
     return path.join(home, ".hq-agent", "machine-creds.json");
@@ -279,69 +271,6 @@ export function resolveInteractiveLogin(options, env = process.env) {
         return options.interactive;
     return env[HQ_NO_BROWSER_LOGIN_ENV]?.trim() !== "1";
 }
-/**
- * Align `process.env.HQ_MACHINE_CREDS_FILE` with a (possibly synthetic) `env`
- * for the duration of `fn`, so hq-cloud's `isMachineIdentity()` sees the same
- * value doctor / tests intended.
- */
-function withAlignedMachineCredsEnv(env, fn) {
-    const prevCreds = process.env.HQ_MACHINE_CREDS_FILE;
-    const nextCreds = env.HQ_MACHINE_CREDS_FILE;
-    if (nextCreds !== prevCreds) {
-        if (nextCreds === undefined || String(nextCreds).trim() === "") {
-            delete process.env.HQ_MACHINE_CREDS_FILE;
-        }
-        else {
-            process.env.HQ_MACHINE_CREDS_FILE = nextCreds;
-        }
-    }
-    try {
-        return fn();
-    }
-    finally {
-        if (nextCreds !== prevCreds) {
-            if (prevCreds === undefined)
-                delete process.env.HQ_MACHINE_CREDS_FILE;
-            else
-                process.env.HQ_MACHINE_CREDS_FILE = prevCreds;
-        }
-    }
-}
-/**
- * True when a usable person Cognito cache file exists under the effective
- * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the
- * person path even when the default machine-creds file is also on disk
- * (no-flip guarantee).
- */
-export function hasPersonCachedSession(env = process.env) {
-    try {
-        const file = personTokenCacheFile(os.homedir(), env);
-        const raw = readPersonTokenFile(os.homedir(), env);
-        if (!raw ||
-            typeof raw.accessToken !== "string" ||
-            raw.accessToken.length === 0 ||
-            typeof raw.idToken !== "string" ||
-            raw.idToken.length === 0) {
-            return false;
-        }
-        // Definitive refresh rejection writes `${file}.invalid.<fingerprint>`;
-        // treat that as no usable person session so status/whoami report machine.
-        const marker = `${file}.invalid.${accessTokenFingerprint(raw.accessToken)}`;
-        if (fs.existsSync(marker))
-            return false;
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Whether hq-cloud currently sees readable machine creds (env override or
- * default `~/.hq-agent/machine-creds.json`), honoring a synthetic `env`.
- */
-function probeMachineIdentity(env) {
-    return withAlignedMachineCredsEnv(env, () => isMachineIdentity());
-}
 /**
  * Fresh-box / Outpost bootstrap: env unset, not forced to person, no person
  * cache, and the default machine-creds file is readable. Distinct from
@@ -361,33 +290,6 @@ export function isDefaultMachineCredsFallback(options = {}, env = process.env) {
 function logDefaultMachineCredsFallback() {
     console.error(chalk.dim("machine identity from default creds file"));
 }
-/**
- * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
- *
- * Machine path when:
- *   - explicit `{ tokenSource: "machine" }` and creds are readable, or
- *   - `HQ_MACHINE_CREDS_FILE` is set and readable, or
- *   - fresh-box fallback: env unset, no person cache, default
- *     `~/.hq-agent/machine-creds.json` readable.
- *
- * Explicit `{ tokenSource: "person" }` never uses machine creds. A present
- * person cache keeps the person path even when the default creds file exists
- * (do not flip a human's commands onto machine tokens).
- */
-export function wantsMachineCognitoTokens(options = {}, env = process.env) {
-    if (options.tokenSource === "person")
-        return false;
-    if (options.tokenSource === "machine") {
-        return probeMachineIdentity(env);
-    }
-    if (isMachineCredsFileEnvSet(env)) {
-        return probeMachineIdentity(env);
-    }
-    // Fresh-box fallback — default creds file only when no person session.
-    if (hasPersonCachedSession(env))
-        return false;
-    return probeMachineIdentity(env);
-}
 /**
  * Which Cognito token source this process will use for doctor / status / whoami.
  * Matches {@link wantsMachineCognitoTokens}: env opt-in, or default-file

package/dist/utils/machine-principal-state.d.ts

@@ -0,0 +1,38 @@
+/** Person browser/login cache vs machine-creds USER_PASSWORD_AUTH mint. */
+export type CognitoTokenSource = "person" | "machine";
+/**
+ * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
+ * Explicit env remains the primary opt-in for daemon units. Fresh agent boxes
+ * without the env still mint via {@link wantsMachineCognitoTokens}'s
+ * default-file fallback when no usable person session exists.
+ */
+export declare function isMachineCredsFileEnvSet(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * True when a usable person Cognito cache file exists under the effective
+ * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the
+ * person path even when the default machine-creds file is also on disk
+ * (no-flip guarantee).
+ */
+export declare function hasPersonCachedSession(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether hq-cloud currently sees readable machine creds (env override or
+ * default `~/.hq-agent/machine-creds.json`), honoring a synthetic `env`.
+ */
+export declare function probeMachineIdentity(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
+ *
+ * Machine path when:
+ *   - explicit `{ tokenSource: "machine" }` and creds are readable, or
+ *   - `HQ_MACHINE_CREDS_FILE` is set and readable, or
+ *   - fresh-box fallback: env unset, no person cache, default
+ *     `~/.hq-agent/machine-creds.json` readable.
+ *
+ * Explicit `{ tokenSource: "person" }` never uses machine creds. A present
+ * person cache keeps the person path even when the default creds file exists
+ * (do not flip a human's commands onto machine tokens).
+ */
+export declare function wantsMachineCognitoTokens(options?: {
+    tokenSource?: CognitoTokenSource;
+}, env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=machine-principal-state.d.ts.map