@indigoai-us/hq-cli 5.108.4 → 5.108.6

package/CHANGELOG.md

@@ -2,6 +2,132 @@
 
 ## [Unreleased]
 
+## [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
+
+- `hq meetings import <file>` imports normalized historical meeting transcripts
+  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
 
 ### Fixed

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/meetings.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
+import { readFile } from "node:fs/promises";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { vaultApiFetch, getCompanyUid, resolveCallerPersonUid, } from "../utils/vault-api.js";
 function formatDuration(seconds) {
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);
@@ -216,6 +217,59 @@ export function registerMeetingsCommand(program) {
         }
     });
     // ── hq meetings invite <meeting-url> ──────────────────────────────
+    meetings
+        .command("import <file>")
+        .description("Import a normalized historical transcript JSON file")
+        .action(async (file) => {
+        try {
+            const companySlug = meetings.opts().company;
+            if (!companySlug) {
+                throw new Error("--company <slug> is required for historical imports");
+            }
+            const bytes = await readFile(file);
+            if (bytes.byteLength > 5 * 1024 * 1024) {
+                throw new Error("Historical meeting import exceeds 5 MiB");
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(bytes.toString("utf8"));
+            }
+            catch {
+                throw new Error("Historical meeting import file must contain valid JSON");
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error("Historical meeting import file must contain a JSON object");
+            }
+            const token = await ensureCognitoToken();
+            const companyId = await getCompanyUid(token, companySlug);
+            const recorderPersonUid = await resolveCallerPersonUid(token);
+            const res = await vaultApiFetch({
+                token,
+                method: "POST",
+                path: "/v1/meetings/import",
+                body: {
+                    ...parsed,
+                    companyId,
+                    recorderPersonUid,
+                },
+            });
+            if (!res.ok)
+                await handleApiError(res, meetings.opts().json);
+            const result = (await res.json());
+            if (meetings.opts().json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(chalk.green(`\n✓ Historical meeting ${result.outcome}: ${result.meetingId}`));
+            if (result.state)
+                console.log(chalk.dim(`  State: ${result.state}`));
+            console.log();
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
     meetings
         .command("invite <meetingUrl>")
         .description("Invite the meeting bot to a Google Meet, Zoom, or Teams URL")

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/utils/client-health.js

@@ -345,7 +345,23 @@ export function buildCliHeartbeat(input) {
             syncState = "error";
             break;
         default:
-            syncState = lastSyncSuccessAt ? "idle" : "never_synced";
+            // An UNRESOLVED failure streak is a live error state, not idleness.
+            // Reporting `idle` here is what put "BROKEN — Runner failed" next to
+            // "Sync state: idle" on the support view: every later `hq` invocation
+            // overwrote the `error` state the failing sync had reported while
+            // leaving the streak that earned it untouched.
+            //
+            // Only this CLI's own `sync_success` clears the streak. The journal
+            // `lastSync` folded into `lastSyncSuccessAt` below deliberately does
+            // NOT: the engine stamps it per FILE update (hq-cloud journal.ts
+            // `updateEntry`), and a push stamps it before throwing its upload worker
+            // errors — so it means "some file moved", not "a run succeeded", and
+            // must never clear an alarm counter. That is why this branch keys off
+            // the streak rather than off the success timestamp.
+            if (input.state.consecutiveFailures > 0)
+                syncState = "error";
+            else
+                syncState = lastSyncSuccessAt ? "idle" : "never_synced";
             break;
     }
     const heartbeat = {

package/dist/utils/feedback-diagnostics.d.ts

@@ -1,4 +1,5 @@
 import { type VersionInfo } from "./feedback-versions.js";
+import type { FeedbackLogsBlob } from "./feedback-logs.js";
 export interface GitContext {
     branch: string | null;
     head: string | null;
@@ -23,6 +24,16 @@ export interface DiagnosticsBlob {
     cwd: string;
     git: GitContext;
     recentSentryBreadcrumbs: unknown[];
+    /**
+     * Redacted tails of the submitter's `~/.hq` log files.
+     *
+     * Attached by `submitFeedback`, NOT by `collectDiagnostics`, because the
+     * size budget can only be computed once the rest of the request body is
+     * known (the server caps the whole body at 64 KiB). Absent when the user
+     * opted out (`--no-logs` / `HQ_FEEDBACK_LOGS=0`), when no eligible log file
+     * exists, or when the body left no headroom.
+     */
+    logs?: FeedbackLogsBlob;
 }
 export declare function sanitizeArgv(argv: string[]): string[];
 export declare function collectDiagnostics(): DiagnosticsBlob;

package/dist/utils/feedback-log-bundle.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Full-history log bundle for `hq feedback` — the out-of-band companion to the
+ * inline `diagnostics.logs` blob in `feedback-logs.ts`.
+ *
+ * Inline logs are capped twice over: the feedback endpoint rejects a request
+ * body above 64 KiB, and `diagnostics` is written into a DynamoDB item, which
+ * caps at 400 KB. Neither can be tuned into carrying a real log history, so the
+ * inline blob is deliberately a ~40 KiB summary of 16 KiB tails. This module
+ * produces the other half: a gzipped bundle uploaded direct to S3, carrying the
+ * files whole rather than in tail-sized slivers.
+ *
+ * Three properties are load-bearing and none may be traded away:
+ *
+ *   1. SAME ALLOWLIST. Discovery reuses `feedback-logs.ts` verbatim —
+ *      `discoverLogFiles`, `discoverStateFiles`, `discoverFlatDirFiles`,
+ *      `walkJsonFiles`. 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 here — not
+ *      raising the size — is what would turn this into an exfiltration bug.
+ *
+ *   2. SAME REDACTION. Every line goes through `redactLogText` before it is
+ *      compressed. Shipping a raw archive would be far simpler and would
+ *      silently undo the entire security model of the inline path.
+ *
+ *   3. BOUNDED MEMORY. 50 MB compressed is roughly a gigabyte of raw log text
+ *      at the ratio these files compress at. Nothing is ever fully materialised:
+ *      files are read in slices, redacted a line at a time, and streamed into
+ *      gzip, with only the compressed output retained.
+ *
+ * Output format — gzipped NDJSON, one JSON record per line:
+ *   {"kind":"manifest","version":1,...}                    exactly one, first
+ *   {"kind":"file","name":"logs/hq-sync.log",...}          one per file
+ *   {"kind":"chunk","name":"logs/hq-sync.log","seq":0,...} many per file
+ *   {"kind":"summary","fileCount":12,...}                  exactly one, last
+ *
+ * NDJSON rather than tar so there is no archive dependency, so a truncated
+ * bundle is still parseable line-by-line up to the cut, and so the records
+ * carry the same redaction metadata the inline blob already reports.
+ */
+import { type LogCandidate } from "./feedback-logs.js";
+import { vaultApiFetch } from "./vault-api.js";
+/**
+ * Compressed ceiling. Mirrors `MAX_LOG_BUNDLE_BYTES` in the hq-pro handler
+ * `feedback-log-bundles.ts`, which refuses to presign above it — the two must
+ * stay in step or the CLI will build bundles the server will not accept.
+ */
+export declare const LOG_BUNDLE_MAX_BYTES: number;
+/**
+ * Headroom between the size we stop feeding at and the hard cap.
+ *
+ * gzip reports compressed bytes only as its internal buffer flushes, so the
+ * running total lags the bytes actually consumed. The lag is bounded by that
+ * buffer (tens of KiB); a 1 MiB margin covers it with three orders of magnitude
+ * to spare, and the final size is asserted against the real cap regardless.
+ */
+export declare const LOG_BUNDLE_SAFETY_MARGIN_BYTES: number;
+/**
+ * Per-file raw ceiling. The desktop logger rotates at 32 MiB (hq-desktop-core
+ * `logfile.rs`), so this admits a full generation with headroom while stopping
+ * one pathological file from consuming the whole bundle. Files above it are
+ * read from the TAIL — the end of a log is what explains a failure.
+ */
+export declare const LOG_BUNDLE_MAX_FILE_RAW_BYTES: number;
+export interface LogBundleResult {
+    /** The gzipped NDJSON bytes, ready to PUT. */
+    gzip: Buffer;
+    /** `gzip.byteLength` — what the presign request must declare. */
+    sizeBytes: number;
+    /** How many files contributed at least one chunk. */
+    fileCount: number;
+    /** True when the size cap stopped collection before every file was read. */
+    truncated: boolean;
+    /** Raw (pre-compression, post-redaction) bytes read into the bundle. */
+    rawBytes: number;
+    /** Total redacted spans across every file. Non-zero is expected and fine. */
+    redactions: number;
+}
+/**
+ * What a submission records about its uploaded bundle. Must stay in step with
+ * `LogBundleRef` in the hq-pro handler `feedback-log-bundles.ts`, which
+ * re-validates every field before persisting it.
+ */
+export interface LogBundleRef {
+    key: string;
+    sizeBytes: number;
+    fileCount: number;
+    truncated: boolean;
+}
+export interface BuildLogBundleOptions {
+    /** Compressed ceiling. Clamped to {@link LOG_BUNDLE_MAX_BYTES}. */
+    maxBytes?: number;
+    /** Override `~/.hq` (tests). */
+    hqDir?: string;
+    /** Override the home directory used to derive `~/.hq` (tests). */
+    homeDir?: string;
+    /** Override the per-file raw ceiling (tests). */
+    maxFileRawBytes?: number;
+}
+/**
+ * Order candidates so that, when the cap truncates collection, what survives is
+ * what a triager reads first.
+ *
+ * State documents lead: they are tiny and answer questions a log cannot (which
+ * operation is claimed, what the sync cursor is). Log files follow, newest
+ * first. Reversing this would let one large old log crowd out every status
+ * file — the same class of ordering defect that let ordinary lock entries
+ * crowd out a stale claim in the inline collector.
+ */
+export declare function orderBundleCandidates(hqDir: string): LogCandidate[];
+/**
+ * Read `absPath` in slices, redacting whole lines, invoking `onChunk` with
+ * roughly {@link CHUNK_TEXT_BYTES} of redacted text at a time.
+ *
+ * Reads from the tail when the file exceeds `maxRawBytes`, and drops the first
+ * partial line after seeking so a chunk never begins mid-record. `onChunk`
+ * returns false to stop early (the cap was hit).
+ */
+export declare function streamRedactedFile(absPath: string, sizeBytes: number, maxRawBytes: number, chunkBytes: number, onChunk: (text: string, redactions: number) => Promise<boolean>): Promise<{
+    fromTail: boolean;
+    stopped: boolean;
+}>;
+/**
+ * Build a gzipped NDJSON bundle of the submitter's redacted `~/.hq` logs.
+ *
+ * Returns `undefined` when nothing eligible exists, so the caller can skip the
+ * upload entirely. Never throws: a bug report must not fail over its own
+ * diagnostics, so any unexpected error yields `undefined` and the submission
+ * proceeds with inline logs alone.
+ */
+export declare function buildLogBundle(opts?: BuildLogBundleOptions): Promise<LogBundleResult | undefined>;
+/**
+ * Build, presign, and upload a log bundle; return the reference the submission
+ * should carry, or `undefined` if anything at all did not work out.
+ *
+ * Every failure path is silent and non-fatal by design. The bundle is an
+ * enrichment on top of the inline logs that already ship in the request body,
+ * so a missing endpoint, a disabled bucket, a refused presign, or a failed PUT
+ * must all degrade to "submit without it" rather than cost the user their bug
+ * report. In particular a 404 is expected and unremarkable while a CLI that
+ * knows about bundles is running against a server that does not yet.
+ */
+export declare function uploadLogBundle(opts: {
+    token: string;
+    enabled: boolean;
+    fetchImpl?: typeof fetch;
+    build?: typeof buildLogBundle;
+    apiFetch?: typeof vaultApiFetch;
+}): Promise<LogBundleRef | undefined>;
+//# sourceMappingURL=feedback-log-bundle.d.ts.map