@indigoai-us/hq-cli 5.108.5 → 5.108.7

package/CHANGELOG.md

@@ -2,6 +2,97 @@
 
 ## [Unreleased]
 
+## [5.108.7] — 2026-09-05
+
+### Fixed
+
+- Fresh agent boxes and Outposts no longer fail `hq auth refresh` with "No
+  valid session: no cached session" when `HQ_MACHINE_CREDS_FILE` is unset.
+  Regression since 5.108.2: machine-token minting required that env (or an
+  explicit `{ tokenSource: "machine" }`), but hq-pro cloud-init never exports
+  it, so bootstrap aborted after sixty refresh failures. When the env is
+  unset, there is no usable person session at `~/.hq/cognito-tokens.json`, and
+  the default `~/.hq-agent/machine-creds.json` is readable, the CLI now mints
+  from that file (same daemon-state-dir cache as the env opt-in) and logs
+  `machine identity from default creds file`. A present person session still
+  wins so a human login is never flipped onto machine tokens; explicit
+  `tokenSource: "person"` never uses machine creds. `hq auth status` and
+  `hq whoami` report the resolved token source.
+
+## [5.108.6] — 2026-09-05
+
+### Added
+
+- `hq feedback bug|feature` now uploads a full log bundle alongside the report,
+  so a bug report carries the submitter's whole recent log history rather than a
+  16 KiB sliver of it. Measured against a real `~/.hq`: 21 MB of logs across 21
+  files, compressed to 1.3 MB — roughly 500x what the inline path can hold.
+
+  The inline `diagnostics.logs` summary is unchanged and still ships in the
+  request body. It cannot be grown: the server rejects a request over 64 KiB and
+  stores `diagnostics` in a DynamoDB item, which caps at 400 KB. So the bundle
+  goes out of band — gzipped and uploaded direct to S3 through a presigned URL,
+  the same path screenshots already use — and the report carries only a
+  reference to it.
+
+  Three properties are load-bearing and are covered by tests that fail if any is
+  removed:
+
+  - **Same allowlist.** Discovery is reused from the inline collector verbatim.
+    The bundle carries more OF the same files, never more files. Credential
+    material lives outside `~/.hq` (`~/.codex/auth.json`,
+    `~/.hq-agent/machine-creds.json`), so widening discovery — not raising the
+    size — is what would turn this into an exfiltration bug.
+  - **Same redaction.** Every chunk passes through the existing redactor before
+    compression. A chunk boundary is held open rather than cut through a PEM
+    block, and an over-long line is cut on whitespace, so a split can never
+    bisect a token and let the halves escape a pattern that would have matched
+    the whole.
+  - **Bounded memory.** 50 MB compressed is roughly a gigabyte of raw text.
+    Nothing is fully materialised: files are read in slices, redacted, and
+    streamed into gzip, retaining only the compressed output.
+
+  Ordering is the truncation policy — status documents first, then logs newest
+  first, so a capped run keeps what a triager reads first. Oversized files are
+  read from the tail, because the end of a log is what explains a failure.
+
+  `--no-logs` and `HQ_FEEDBACK_LOGS=0` disable the bundle and the inline logs
+  together. Every failure is silent and non-fatal: a missing endpoint, a
+  disabled bucket, a refused presign, or a failed upload all degrade to
+  submitting without the bundle rather than costing the user their bug report.
+
+### Added
+
+- `hq feedback` debug capture now also collects three more `~/.hq` sources, all
+  small and all high-signal for the failures they describe:
+
+  - **`locks/`** — held operation locks and background-work claims. This is the
+    one place where the FILENAME is the diagnosis: a `…stale-claim…` entry names
+    the operation, the process that abandoned it, and the fact that the claim
+    went stale, which is the answer to "sync/reindex is stuck". A hung process
+    writes nothing to a log, so this is otherwise invisible. Zero-byte lock
+    files are kept for their names rather than skipped as empty.
+  - **`jobs/`** — scheduled-job status, last reconcile, and probe attempts,
+    answering "my scheduled job never ran". Nested, so this is the collector's
+    only directory walk; it is bounded in depth (3) and file count (20), and
+    refuses to traverse a symlinked directory so it cannot escape `~/.hq`.
+  - Three more root status documents: `outpost-session-heartbeat.json` (Outpost
+    liveness), `version-check.json` (why an update is not offered), and
+    `plan-limit-nag.json`.
+
+  Deliberately still excluded: the two multi-megabyte telemetry cursors, the
+  `sync-state-v3/` internals, `backups/`, and everything outside `~/.hq` —
+  notably Claude Code session transcripts, which are conversation content and
+  do not belong on a bug report.
+
+### Changed
+
+- Runtime bumped to `@indigoai-us/hq-cloud` ~6.16.11: personal-vault sync no
+  longer downloads `workspace/.session-logs/` from other machines (push-only),
+  and `hq reindex` now prunes local session-log copies 7 days after the vault
+  confirms them (`HQ_SESSION_LOG_LOCAL_RETENTION_DAYS`, `off` to disable).
+
+
 ## [5.108.5] — 2026-09-04
 
 ### Added
@@ -10,6 +101,49 @@
   through HQ's managed source pipeline, with immutable idempotent replay and
   explicit conflict detection when an external source ID is reused with
   different content.
+- `hq feedback bug|feature` now attaches bounded, redacted debug evidence from
+  the submitter's `~/.hq` directory to the submission's `diagnostics`, so a bug
+  report carries the context a triager would otherwise have to ask for. Two
+  classes are collected:
+
+  - **Log tails** — `*.log` and `*.jsonl` directly inside `~/.hq/logs/`,
+    including rotated generations (`hq-sync.log.1`, `.2`, `.3`), plus
+    `boot-sync.log` and `boot-capture.log` at the `~/.hq` root. This covers the
+    hq-cloud sync engine and the desktop sync app (which share
+    `logs/hq-sync.log`) and the CLI's MCP registry audit trail
+    (`logs/mcp-registry.log`). Rotated generations matter most right after a
+    rotation, when the active file is nearly empty and the history a triager
+    needs sits in `.1`. Any future log dropped into `~/.hq/logs/` is picked up
+    automatically.
+  - **State snapshots** — the small JSON status documents that say where sync
+    and client health stand: `sync-progress.json` (phase, file counts, conflict
+    count), `sync-version.json`, `cli-client-health.json` (failure streak),
+    `cli-client-health.observation.json`, and the per-company
+    `sync-journal.<slug>.json` locators. These are collected first, since they
+    answer questions a log tail cannot, and the log budget takes what remains.
+
+  Eligibility is an explicit allowlist in both classes. The rest of `~/.hq`
+  (`cognito-tokens.json`, `deploy-passwords.json`, `secrets-cache/`) is never
+  read, the enormous `sync-journal.*.json.last-good` snapshots are excluded by
+  suffix, and eligibility is decided with `lstat` so a symlink wearing an
+  eligible name cannot be used to reach a credential file.
+
+  Every tail is redacted before it is measured or sent (JWTs, AWS key ids,
+  GitHub and Slack tokens, `Bearer` values, SigV4 presign signatures, PEM
+  private-key blocks, and `key=value` pairs for secret-shaped names). The total
+  is budgeted against the headroom left under the server's 64 KiB request-body
+  cap and re-measured against the real serialized envelope after attaching, so
+  a large report can never be turned into a 413 by its own diagnostics.
+
+  Opt out per invocation with `--no-logs`, or globally with
+  `HQ_FEEDBACK_LOGS=0`.
+
+### Fixed
+
+- `hq` self-update no longer loops. After the CLI updates to `@latest` and a
+  re-run produces no effective version change, the version check records that
+  outcome and converges instead of re-triggering the updater, so 5.105.x (and
+  later) installs stop repeatedly self-updating (#494).
 
 ## [5.108.4] — 2026-09-04
 

package/dist/commands/auth.js

@@ -14,8 +14,8 @@
  * by the deploy + sync skills.
  */
 import chalk from "chalk";
-import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
-import { DEFAULT_COGNITO, refreshCachedSession, } from "../utils/cognito-session.js";
+import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
+import { DEFAULT_COGNITO, refreshCachedSession, resolveCognitoTokenSource, } from "../utils/cognito-session.js";
 import { cognitoConfigForLoginProvider } from "../utils/login-provider.js";
 import { callbackPortBusyGuidance, DEFAULT_CALLBACK_PORT, isCallbackPortBusy, } from "../utils/callback-port-busy.js";
 /**
@@ -56,7 +56,7 @@ export function registerAuthCommands(program) {
         .description("Sign in to HQ — opens the Cognito Hosted UI and caches tokens locally")
         .option("--provider <provider>", "OAuth provider to use: google, microsoft, or picker")
         .action(async (options) => {
-        if (isMachineIdentity()) {
+        if (resolveCognitoTokenSource() === "machine") {
             console.log(chalk.green(`Running as ${machineIdentityLabel()} — sessions mint automatically; no browser login needed.`));
             return;
         }
@@ -119,16 +119,22 @@ export function registerAuthCommands(program) {
         .command("status")
         .description("Show whether a valid HQ session is cached")
         .action(() => {
-        const machine = isMachineIdentity();
+        // Effective source: env opt-in, fresh-box default-creds when no usable
+        // person session, or after a definitive person-refresh rejection marked
+        // the person cache rejected (transient refresh errors still report person).
+        const tokenSource = resolveCognitoTokenSource();
+        const machine = tokenSource === "machine";
         const cached = loadCachedTokens();
         if (!cached) {
             if (machine) {
                 // No cached session yet, but machine creds mint one on demand —
                 // report ready, not signed-out.
                 console.log(chalk.green(`${machineIdentityLabel()} — no cached session yet (mints automatically on first use)`));
+                console.log(chalk.dim(`token source: ${tokenSource}`));
                 return;
             }
             console.log(chalk.yellow("No cached HQ session — run `hq auth login`"));
+            console.log(chalk.dim(`token source: ${tokenSource}`));
             process.exit(1);
         }
         const claims = peekIdToken(cached.idToken);
@@ -140,6 +146,7 @@ export function registerAuthCommands(program) {
         console.log(expiring
             ? chalk.yellow(`${label}HQ session cached but expiring (expiresAt=${cached.expiresAt})`)
             : chalk.green(`${label}HQ session valid (expiresAt=${cached.expiresAt})`));
+        console.log(chalk.dim(`token source: ${tokenSource}`));
     });
 }
 //# sourceMappingURL=auth.js.map

package/dist/commands/feedback.d.ts

@@ -1,5 +1,17 @@
 import { Command } from "commander";
+import { type DiagnosticsBlob } from "../utils/feedback-diagnostics.js";
+import { collectFeedbackLogs, feedbackLogsEnabled } from "../utils/feedback-logs.js";
+import { type LogBundleRef } from "../utils/feedback-log-bundle.js";
 export declare const BODY_MAX_BYTES: number;
+/**
+ * Mirror of the server's `MAX_BODY_BYTES` in hq-pro
+ * `src/vault-service/handlers/feedback.ts`, which rejects the WHOLE request
+ * body over this size with a 413. Note this is the same number as
+ * `BODY_MAX_BYTES` above but a different measurement: that one bounds the
+ * markdown body alone, this one bounds the serialized JSON envelope. Debug
+ * logs are budgeted against whatever headroom is left between them.
+ */
+export declare const REQUEST_MAX_BYTES: number;
 export interface FeedbackResult {
     id: string;
 }
@@ -11,8 +23,34 @@ export interface FeedbackSubmitOptions {
     token: string;
     /** S3 object keys of already-uploaded screenshots (see uploadScreenshots). */
     screenshots?: string[];
+    /**
+     * Attach redacted tails of the submitter's `~/.hq` logs. Defaults to true;
+     * `false` (from `--no-logs`) skips collection entirely. Even when true, the
+     * user's `HQ_FEEDBACK_LOGS` env override still applies.
+     */
+    includeLogs?: boolean;
+    /**
+     * Reference to an already-uploaded log bundle (see uploadLogBundle). Carries
+     * the full log history that the inline `diagnostics.logs` blob cannot — the
+     * inline blob is bounded by the request cap and DynamoDB's item limit, so it
+     * stays a summary and this carries the rest.
+     */
+    logBundle?: LogBundleRef;
 }
 export declare function readBodyFile(bodyFile: string, stdin?: NodeJS.ReadableStream): Promise<string>;
+/**
+ * Attach redacted `~/.hq` log tails to `diagnostics` if, and only if, they fit
+ * inside the server's request-body cap.
+ *
+ * Mutates `diagnostics` in place (it is already referenced by `requestBody`,
+ * so the measurement below sees the attached logs). Best-effort throughout: a
+ * collection failure leaves the submission untouched rather than failing a bug
+ * report over its own diagnostics.
+ */
+export declare function attachDebugLogs(requestBody: Record<string, unknown>, diagnostics: DiagnosticsBlob, enabled: boolean, deps?: {
+    collect?: typeof collectFeedbackLogs;
+    envEnabled?: typeof feedbackLogsEnabled;
+}): void;
 export declare function submitFeedback(opts: FeedbackSubmitOptions): Promise<FeedbackResult>;
 export declare function registerFeedbackCommand(program: Command): void;
 //# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -4,7 +4,24 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { collectDiagnostics } from "../utils/feedback-diagnostics.js";
 import { MAX_SCREENSHOTS, uploadScreenshots } from "../utils/feedback-screenshots.js";
+import { FEEDBACK_LOGS_MAX_TOTAL_BYTES, FEEDBACK_LOGS_MIN_USEFUL_BYTES, collectFeedbackLogs, feedbackLogsEnabled, } from "../utils/feedback-logs.js";
+import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 export const BODY_MAX_BYTES = 64 * 1024;
+/**
+ * Mirror of the server's `MAX_BODY_BYTES` in hq-pro
+ * `src/vault-service/handlers/feedback.ts`, which rejects the WHOLE request
+ * body over this size with a 413. Note this is the same number as
+ * `BODY_MAX_BYTES` above but a different measurement: that one bounds the
+ * markdown body alone, this one bounds the serialized JSON envelope. Debug
+ * logs are budgeted against whatever headroom is left between them.
+ */
+export const REQUEST_MAX_BYTES = 64 * 1024;
+/**
+ * Headroom held back for the `"logs":{...}` JSON envelope itself — its keys,
+ * braces, and the escaping of the tail text. The final size is re-measured
+ * after attaching, so this reserve only needs to be roughly right.
+ */
+const LOGS_ENVELOPE_RESERVE_BYTES = 1024;
 export async function readBodyFile(bodyFile, stdin) {
     if (bodyFile === "-") {
         const stream = stdin ?? process.stdin;
@@ -23,6 +40,44 @@ export async function readBodyFile(bodyFile, stdin) {
     }
     return fs.promises.readFile(bodyFile, "utf-8");
 }
+/**
+ * Attach redacted `~/.hq` log tails to `diagnostics` if, and only if, they fit
+ * inside the server's request-body cap.
+ *
+ * Mutates `diagnostics` in place (it is already referenced by `requestBody`,
+ * so the measurement below sees the attached logs). Best-effort throughout: a
+ * collection failure leaves the submission untouched rather than failing a bug
+ * report over its own diagnostics.
+ */
+export function attachDebugLogs(requestBody, diagnostics, enabled, deps = {}) {
+    const collect = deps.collect ?? collectFeedbackLogs;
+    const envEnabled = deps.envEnabled ?? feedbackLogsEnabled;
+    if (!enabled || !envEnabled())
+        return;
+    try {
+        const baseBytes = Buffer.byteLength(JSON.stringify(requestBody), "utf8");
+        const available = REQUEST_MAX_BYTES - baseBytes - LOGS_ENVELOPE_RESERVE_BYTES;
+        if (available < FEEDBACK_LOGS_MIN_USEFUL_BYTES)
+            return;
+        const logs = collect({
+            budgetBytes: Math.min(available, FEEDBACK_LOGS_MAX_TOTAL_BYTES),
+        });
+        if (!logs)
+            return;
+        diagnostics.logs = logs;
+        // Final authority: re-measure the ACTUAL envelope. JSON escaping of the
+        // tail text (quotes, newlines, control chars) can expand it well past the
+        // raw byte count the budget counted, so the estimate above is necessary
+        // but not sufficient. If we overshot, drop the logs rather than 413.
+        if (Buffer.byteLength(JSON.stringify(requestBody), "utf8") > REQUEST_MAX_BYTES) {
+            delete diagnostics.logs;
+        }
+    }
+    catch {
+        // Never let diagnostics collection break the submission.
+        delete diagnostics.logs;
+    }
+}
 export async function submitFeedback(opts) {
     // Validate the title locally, symmetric with the body check below. Commander's
     // `requiredOption("--title")` only requires the flag to be PRESENT — an empty
@@ -54,6 +109,18 @@ export async function submitFeedback(opts) {
     if (opts.screenshots && opts.screenshots.length > 0) {
         requestBody.screenshots = opts.screenshots;
     }
+    // The bundle reference is four small fields, so unlike the inline logs below
+    // it needs no budgeting — but it is added BEFORE attachDebugLogs so those
+    // bytes are counted against the inline budget rather than overrunning it.
+    if (opts.logBundle) {
+        requestBody.logBundle = opts.logBundle;
+    }
+    // Debug logs are attached LAST and sized against the headroom the rest of
+    // the request left behind. The server 413s the whole body over 64 KiB, so a
+    // fixed log budget would turn a previously-working large-body submission
+    // into a hard failure. Measuring the real serialized envelope — the exact
+    // bytes vaultApiFetch will send — is what makes that impossible.
+    attachDebugLogs(requestBody, diagnostics, opts.includeLogs !== false);
     const res = await vaultApiFetch({
         token: opts.token,
         path: "/v1/feedback",
@@ -81,6 +148,9 @@ function registerSubcommand(feedbackCmd, type) {
         .requiredOption("--body-file <path>", "Path to a markdown file with the body; use - to read from stdin")
         .option("--company <slug>", "Company slug to associate with the report")
         .option("--screenshot <path>", `Attach a screenshot (repeatable, up to ${MAX_SCREENSHOTS}; .png/.jpg/.jpeg/.webp/.gif)`, (value, prev) => [...prev, value], [])
+        // Commander turns `--no-logs` into a boolean `logs` that defaults to true,
+        // so the default is "attach logs" and the flag is the opt-out.
+        .option("--no-logs", "Do not attach redacted tails of your ~/.hq log files (also: HQ_FEEDBACK_LOGS=0)")
         .action(async (opts) => {
         try {
             const token = await ensureCognitoToken({ interactive: false });
@@ -91,6 +161,14 @@ function registerSubcommand(feedbackCmd, type) {
                 paths: opts.screenshot ?? [],
                 token,
             });
+            // Full-history logs go direct to S3 before the submission that
+            // references them. Best-effort throughout: if the endpoint is absent
+            // (older server), the bucket is unconfigured, or the upload fails,
+            // this resolves undefined and the report still carries inline logs.
+            const logBundle = await uploadLogBundle({
+                token,
+                enabled: opts.logs !== false && feedbackLogsEnabled(),
+            });
             const result = await submitFeedback({
                 type,
                 title: opts.title,
@@ -98,6 +176,8 @@ function registerSubcommand(feedbackCmd, type) {
                 company: opts.company,
                 token,
                 screenshots,
+                includeLogs: opts.logs !== false,
+                logBundle,
             });
             console.log(`Submitted: ${result.id}`);
         }

package/dist/commands/signals.js

@@ -101,6 +101,12 @@ async function runList(options) {
     const format = options.format ?? defaultListFormat();
     const accessToken = await resolveAccessToken();
     const vaultConfig = buildVaultConfig(accessToken);
+    // HQ-59: every company (cmp_) read below rides the presign VaultClient
+    // (`usePresign` keys on the vault client + cmp_ prefix), so tell entity
+    // resolution to skip the company `POST /sts/vend` — the vended creds were
+    // never consumed here, but each call re-entered the packed FILE_ACL fit
+    // ladder (policyTruncated noise). Personal vaults still vend-self.
+    vaultConfig.companyVaultUsesPresign = true;
     const entity = await resolveEntity({ slug, vaultConfig });
     const result = await listSignals({
         entity,
@@ -134,6 +140,12 @@ async function runGet(options) {
     const format = options.format ?? defaultGetFormat();
     const accessToken = await resolveAccessToken();
     const vaultConfig = buildVaultConfig(accessToken);
+    // HQ-59: every company (cmp_) read below rides the presign VaultClient
+    // (`usePresign` keys on the vault client + cmp_ prefix), so tell entity
+    // resolution to skip the company `POST /sts/vend` — the vended creds were
+    // never consumed here, but each call re-entered the packed FILE_ACL fit
+    // ladder (policyTruncated noise). Personal vaults still vend-self.
+    vaultConfig.companyVaultUsesPresign = true;
     const entity = await resolveEntity({ slug, vaultConfig });
     const doc = await getSignal({
         entity,

package/dist/commands/sources.js

@@ -109,6 +109,12 @@ async function runList(options) {
     const format = options.format ?? defaultListFormat();
     const accessToken = await resolveAccessToken();
     const vaultConfig = buildVaultConfig(accessToken);
+    // HQ-59: every company (cmp_) read below rides the presign VaultClient
+    // (`usePresign` keys on the vault client + cmp_ prefix), so tell entity
+    // resolution to skip the company `POST /sts/vend` — the vended creds were
+    // never consumed here, but each call re-entered the packed FILE_ACL fit
+    // ladder (policyTruncated noise). Personal vaults still vend-self.
+    vaultConfig.companyVaultUsesPresign = true;
     const entity = await resolveEntity({ slug, vaultConfig });
     const result = await listSources({
         entity,
@@ -142,6 +148,12 @@ async function runGet(options) {
     const format = options.format ?? defaultGetFormat();
     const accessToken = await resolveAccessToken();
     const vaultConfig = buildVaultConfig(accessToken);
+    // HQ-59: every company (cmp_) read below rides the presign VaultClient
+    // (`usePresign` keys on the vault client + cmp_ prefix), so tell entity
+    // resolution to skip the company `POST /sts/vend` — the vended creds were
+    // never consumed here, but each call re-entered the packed FILE_ACL fit
+    // ladder (policyTruncated noise). Personal vaults still vend-self.
+    vaultConfig.companyVaultUsesPresign = true;
     const entity = await resolveEntity({ slug, vaultConfig });
     const doc = await getSource({
         entity,

package/dist/commands/whoami.js

@@ -2,8 +2,9 @@
  * hq whoami — displays current user or 'not logged in'
  */
 import chalk from 'chalk';
-import { loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, } from '@indigoai-us/hq-cloud';
+import { loadCachedTokens, isExpiring, loadMachineCreds, } from '@indigoai-us/hq-cloud';
 import { peekIdToken as decodeIdToken } from "../utils/id-token.js";
+import { resolveCognitoTokenSource } from "../utils/cognito-session.js";
 function peekIdToken(idToken) {
     const decoded = decodeIdToken(idToken);
     return {
@@ -23,7 +24,10 @@ export function registerWhoamiCommand(program) {
         .description('Show the currently authenticated user')
         .action(async () => {
         try {
-            const machine = isMachineIdentity();
+            // Effective source (same as auth status / ensureCognitoToken): env
+            // opt-in, fresh-box default-creds when no usable person session, or
+            // after a definitive person-refresh rejection marked the session rejected.
+            const machine = resolveCognitoTokenSource() === "machine";
             const cached = loadCachedTokens();
             if (machine) {
                 // Machine identities (company agents) mint sessions on demand from
@@ -34,6 +38,7 @@ export function registerWhoamiCommand(program) {
                     ? peekIdToken(cached.idToken).entityUid
                     : undefined;
                 console.log(`Machine identity ${username}${entityUid ? ` (agent ${entityUid})` : ''} — sessions mint automatically`);
+                console.log(`token source: machine`);
                 return;
             }
             if (!cached) {

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

@@ -93,31 +93,64 @@ export declare function machineTokenStateDir(home?: string, env?: NodeJS.Process
 export declare function machineTokenCacheFile(home?: string, env?: NodeJS.ProcessEnv): string;
 /**
  * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
- * The mere presence of `~/.hq-agent/machine-creds.json` is NOT enough — minting
- * and doctor "machine" reporting are opt-in via this env (systemd unit) or an
- * explicit `{ tokenSource: "machine" }` caller option.
+ * 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 = {
     interactive?: boolean;
     /**
      * Force machine-credential minting (`"machine"`) or the person login cache
-     * (`"person"`). When omitted, machine minting is used only if
-     * `HQ_MACHINE_CREDS_FILE` is explicitly set and readable.
+     * (`"person"`). When omitted, machine minting is used if
+     * `HQ_MACHINE_CREDS_FILE` is set, or (fresh-box fallback) the default
+     * `~/.hq-agent/machine-creds.json` is readable and no person session is
+     * cached. Explicit `"person"` never uses machine creds.
      */
     tokenSource?: CognitoTokenSource;
 };
+/**
+ * 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
+ * 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).
- * Opt-in only: explicit `{ tokenSource: "machine" }`, or `HQ_MACHINE_CREDS_FILE`
- * set in the environment. Default-path `~/.hq-agent/machine-creds.json` alone
- * never flips other CLI commands onto the machine path.
+ *
+ * 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 / reporting:
- * machine only when `HQ_MACHINE_CREDS_FILE` is explicitly set and readable;
- * otherwise the person login cache. Default-path machine-creds alone → person.
+ * Which Cognito token source this process will use for doctor / status / whoami.
+ * Matches {@link wantsMachineCognitoTokens}: env opt-in, or default-file
+ * fallback when no usable person session is cached (absent, or marked rejected
+ * after a definitive Cognito refresh refusal). Transient refresh failures do
+ * not flip this to machine.
  */
 export declare function resolveCognitoTokenSource(env?: NodeJS.ProcessEnv): CognitoTokenSource;
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
@@ -143,19 +176,28 @@ export declare function describeCognitoTokenSource(opts?: {
  * Run `fn` with `HQ_STATE_DIR` pointed at the machine/daemon token cache so
  * hq-cloud's mint writes never touch the person login file.
  *
- * When `HQ_STATE_DIR` is already set (tests / explicit callers), leave it alone
- * so a pre-seeded machine session is still found — only redirect when unset.
+ * Always redirects — even when the caller already set `HQ_STATE_DIR` (person
+ * cache / tests). Override the machine cache location with
+ * `HQ_MACHINE_TOKEN_STATE_DIR` instead. Restores the prior env afterwards.
  */
 export declare function withMachineTokenStateDir<T>(fn: () => Promise<T>, opts?: {
     home?: string;
     env?: NodeJS.ProcessEnv;
 }): Promise<T>;
+/**
+ * True when a person-token refresh failed with a definitive Cognito auth
+ * rejection (refresh token invalid/revoked). Transient network/5xx/timeouts
+ * must NOT trigger machine-identity fallback.
+ */
+export declare function isDefinitivePersonAuthRejection(err: unknown): boolean;
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
  * as needed. Person cache lives at ~/.hq/cognito-tokens.json. Machine minting
- * is opt-in: `HQ_MACHINE_CREDS_FILE` explicitly set, or
- * `{ tokenSource: "machine" }` — then USER_PASSWORD_AUTH and (when
- * `HQ_STATE_DIR` is unset) a cache under the daemon state dir.
+ * uses `HQ_MACHINE_CREDS_FILE` / `{ tokenSource: "machine" }`, or the fresh-box
+ * fallback when the default creds file is readable and no person session
+ * exists (or person refresh fails with a definitive auth rejection).
+ * Machine tokens always cache under the dedicated machine/daemon state dir
+ * (never the caller's `HQ_STATE_DIR` person cache).
  *
  * Pass `interactive: false` from automated contexts (e.g. the `hq-auth-refresh`
  * bin invoked by the deploy skill) where failing fast is better than opening