@indigoai-us/hq-cli 5.108.5 → 5.108.6

package/dist/utils/feedback-logs.js

@@ -0,0 +1,669 @@
+/**
+ * Debug-log and state capture for `hq feedback` submissions.
+ *
+ * A bug report is far cheaper to triage when the submitter's recent log output
+ * travels with it. This module collects two bounded, redacted classes of
+ * evidence from the user's `~/.hq` directory and hands them to the feedback
+ * command, which attaches them to the `diagnostics` blob on the submission:
+ *
+ *   - LOG TAILS (`files`) — the end of each rolling log. One file covers more
+ *     than its name suggests: `logs/hq-sync.log` is the shared diagnostic log
+ *     for BOTH the hq-cloud sync engine and the desktop sync app, which write
+ *     to it through the same path, and its ROTATED generations
+ *     (`hq-sync.log.1`, `.2`, `.3`) are eligible too — just after a rotation
+ *     the active file is nearly empty and the history lives in `.1`.
+ *     `logs/mcp-registry.log` is the CLI's own append-only MCP audit trail.
+ *     Any future `*.log`/`*.jsonl` dropped into `~/.hq/logs/` is picked up
+ *     automatically.
+ *
+ *   - STATE SNAPSHOTS (`state`) — small JSON files that describe where sync
+ *     and client health currently stand: the in-flight sync phase and conflict
+ *     count, the client-health failure streak, the per-company sync journal
+ *     locators. These are tiny and answer the questions a log tail usually
+ *     cannot ("was it mid-pull?", "how many conflicts?", "how long since the
+ *     last successful sync?"), so they are collected FIRST and the log budget
+ *     takes what remains.
+ *
+ * Contrast with `local-files-overview.ts`, which deliberately sends only
+ * metadata (existence, size, age, error-line counts) and NEVER a line of log
+ * text. That module feeds the BACKGROUND client-health heartbeat, where the
+ * user has not asked for anything and content would be surveillance. This
+ * module runs only on an EXPLICIT, user-initiated `hq feedback` invocation,
+ * where the user is asking us to look at their problem, so content is both
+ * expected and useful. The two must not be merged.
+ *
+ * Three hard safety properties, each with a regression test:
+ *
+ *   1. ALLOWLIST, NOT A SCAN. `~/.hq` also holds `cognito-tokens.json`,
+ *      `deploy-passwords.json`, and `secrets-cache/`. Only `*.log` files
+ *      directly inside `~/.hq/logs/` plus the two known root-level boot logs
+ *      are ever eligible. A recursive walk over `~/.hq` is a credential leak
+ *      and must never be introduced here.
+ *
+ *   2. NO SYMLINKS. Eligibility is decided with `lstat`, and a candidate must
+ *      be a REGULAR file. Without this, a symlink named `anything.log` inside
+ *      `~/.hq/logs/` pointing at `~/.hq/cognito-tokens.json` would satisfy the
+ *      allowlist and exfiltrate the user's tokens. `stat` would follow the link
+ *      and report a regular file — `lstat` is the whole guard.
+ *
+ *   3. REDACTION IS APPLIED BEFORE BUDGETING. Every tail passes through
+ *      `redactLogText` before it is measured or returned, so no code path can
+ *      emit an unredacted span. Redaction is defence in depth, not the primary
+ *      control — properties 1 and 2 are what keep secrets out.
+ *
+ * Every filesystem operation is independently best-effort: a missing file, a
+ * permission error, or a file that disappears mid-read degrades that one entry
+ * and never throws. Collecting diagnostics must never break a bug report.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/**
+ * Ceiling on the total redacted log text attached to one submission.
+ *
+ * The server caps the WHOLE feedback request body at 64 KiB, so this is only
+ * an upper bound — the caller passes a smaller `budgetBytes` computed from the
+ * headroom actually left after the title, body, and the rest of diagnostics.
+ * See `submitFeedback` in `../commands/feedback.ts`.
+ */
+export const FEEDBACK_LOGS_MAX_TOTAL_BYTES = 40 * 1024;
+/** Per-file ceiling, so one noisy log cannot consume the entire budget. */
+export const FEEDBACK_LOGS_MAX_FILE_TAIL_BYTES = 16 * 1024;
+/**
+ * Below this much remaining budget a tail is too short to be worth reading,
+ * so the file is recorded as skipped rather than truncated into noise.
+ */
+export const FEEDBACK_LOGS_MIN_USEFUL_BYTES = 1024;
+/**
+ * Ceiling on how many skipped entries are recorded.
+ *
+ * `skipped` is metadata, not payload, so it was originally left outside the
+ * byte budget — which made it unbounded. An installation with hundreds of log
+ * files produced hundreds of `{name, reason}` objects and a blob several times
+ * the requested budget; `attachDebugLogs` then dropped the whole thing to stay
+ * under the request cap, so the user with the MOST log history got the LEAST
+ * evidence. The overflow count preserves the signal without the bytes.
+ */
+export const FEEDBACK_MAX_SKIPPED_ENTRIES = 25;
+/** Subdirectory of `~/.hq` whose log files are eligible. Not recursive. */
+export const FEEDBACK_LOGS_DIRNAME = "logs";
+/**
+ * Eligible extensions inside `~/.hq/logs/`. `.jsonl` is included because the
+ * CLI's MCP registry audit trail is JSON-lines, not plain text.
+ */
+export const FEEDBACK_LOG_EXTENSIONS = [".log", ".jsonl"];
+/**
+ * True for a log filename, including a ROTATED generation.
+ *
+ * The desktop/sync logger keeps 32 MiB x 3 generations named `hq-sync.log.1`,
+ * `.2`, `.3` (see hq-desktop-core `logfile.rs`). A plain "ends with .log"
+ * test misses every one of them — and they matter most in the worst case: just
+ * after a rotation the active log is nearly empty and all the history a
+ * triager needs sits in `.1`.
+ */
+export function isEligibleLogName(name) {
+    const lower = name.toLowerCase();
+    if (FEEDBACK_LOG_EXTENSIONS.some((ext) => lower.endsWith(ext)))
+        return true;
+    const rotated = /^(.+)\.(\d+)$/.exec(lower);
+    if (!rotated)
+        return false;
+    const base = rotated[1];
+    return FEEDBACK_LOG_EXTENSIONS.some((ext) => base.endsWith(ext));
+}
+/** Per-state-file ceiling. These are status documents, not streams. */
+export const FEEDBACK_STATE_MAX_FILE_BYTES = 4 * 1024;
+/**
+ * Ceiling on all state snapshots combined. Deliberately a small slice of the
+ * overall budget: state is dense but finite, and the rest belongs to logs.
+ */
+export const FEEDBACK_STATE_MAX_TOTAL_BYTES = 12 * 1024;
+/**
+ * State files at the `~/.hq` ROOT that are eligible, by EXACT name.
+ *
+ * The root is where `cognito-tokens.json`, `deploy-passwords.json`, and
+ * `secrets-cache/` live, so it is never globbed. Adding a name here is a
+ * deliberate act: confirm the file carries no credential before listing it.
+ */
+export const FEEDBACK_STATE_FILENAMES = [
+    // In-flight sync: phase, file counts, conflict count, current file.
+    "sync-progress.json",
+    // Sync contract version the installation last wrote.
+    "sync-version.json",
+    // Client-health heartbeat: installation id and consecutive failure streak.
+    "cli-client-health.json",
+    // Last observed sync/heartbeat timestamps.
+    "cli-client-health.observation.json",
+    // Outpost session liveness — the answer to "is my Outpost still alive".
+    "outpost-session-heartbeat.json",
+    // Cached latest release + fetch time — the answer to "why won't it update".
+    "version-check.json",
+    // Plan-limit nag state.
+    "plan-limit-nag.json",
+];
+/**
+ * Per-company sync journal LOCATORS (`sync-journal.<slug>.json`) are also
+ * eligible. Matched by an exact prefix AND a `.json` suffix, which is what
+ * excludes the multi-hundred-megabyte `…json.last-good` snapshots sitting
+ * beside them. No credential file at the root carries this prefix.
+ */
+export const FEEDBACK_STATE_JOURNAL_PREFIX = "sync-journal.";
+/**
+ * `~/.hq/locks/` — held operation locks and background-work claims.
+ *
+ * The highest-signal thing in the whole collection, and 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. That is
+ * the answer to "sync/reindex is stuck", which is otherwise invisible in a log
+ * tail because a hung process writes nothing. Contents are tiny (tens to a
+ * couple hundred bytes) and included too.
+ */
+export const FEEDBACK_LOCKS_DIRNAME = "locks";
+/**
+ * `~/.hq/jobs/` — scheduled-job status, reconcile results, and probe attempts.
+ * Nested one or two levels (`jobs/probes/<job>/last-attempt.json`), so this is
+ * the only source needing a directory walk. See {@link walkJsonFiles} for the
+ * bounds that walk carries.
+ */
+export const FEEDBACK_JOBS_DIRNAME = "jobs";
+/** Per-entry ceiling for a lock file. Their value is the name plus a little context. */
+export const FEEDBACK_LOCK_MAX_FILE_BYTES = 512;
+/**
+ * Bounds on the `jobs/` walk. Depth 3 reaches
+ * `jobs/probes/<job>/last-attempt.json`; the file cap stops a pathological
+ * tree from crowding out logs.
+ */
+export const FEEDBACK_JOBS_MAX_DEPTH = 3;
+export const FEEDBACK_JOBS_MAX_FILES = 20;
+/** Ceiling on how many lock entries are collected. */
+export const FEEDBACK_LOCKS_MAX_FILES = 20;
+/**
+ * Log files that live at the root of `~/.hq` rather than under `logs/`.
+ * Listed explicitly — the root directory holds credentials and must never be
+ * enumerated by pattern.
+ */
+export const FEEDBACK_ROOT_LOG_FILENAMES = [
+    "boot-sync.log",
+    "boot-capture.log",
+];
+/**
+ * Redaction patterns, applied in order. Structured secrets (whole PEM blocks)
+ * come first so a later, narrower pattern cannot chop one into fragments that
+ * then escape.
+ */
+const REDACTION_PATTERNS = [
+    // Whole PEM private-key blocks.
+    {
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+        replace: () => "[redacted private key]",
+    },
+    // JSON Web Tokens (Cognito access/id/refresh tokens land in logs this way).
+    {
+        pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+/g,
+        replace: () => "[redacted jwt]",
+    },
+    // AWS access key identifiers.
+    {
+        pattern: /\b(?:AKIA|ASIA|AIDA|AROA|AGPA|AIPA|ANPA|ANVA)[0-9A-Z]{16}\b/g,
+        replace: () => "[redacted aws key id]",
+    },
+    // GitHub personal access / OAuth / refresh tokens.
+    {
+        pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+        replace: () => "[redacted github token]",
+    },
+    // Slack bot/user/app tokens.
+    {
+        pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}\b/g,
+        replace: () => "[redacted slack token]",
+    },
+    // SigV4 presigned-URL material. Keeps the URL readable, drops what signs it.
+    {
+        pattern: /([?&](?:X-Amz-Signature|X-Amz-Credential|X-Amz-Security-Token)=)[^&\s"']+/gi,
+        replace: (_m, prefix) => `${prefix}[redacted]`,
+    },
+    // `Authorization: Bearer <token>` in any casing.
+    {
+        pattern: /\b([Bb]earer\s+)[A-Za-z0-9._~+/=-]{12,}/g,
+        replace: (_m, prefix) => `${prefix}[redacted]`,
+    },
+    // Generic `key: value` / `key=value` for names that denote a secret. Runs
+    // last so the specific patterns above produce the more informative label.
+    {
+        pattern: /("?\b(?:token|secret|password|passwd|api[_-]?key|access[_-]?key|secret[_-]?key|auth[_-]?token|authorization|credential|session[_-]?token)"?\s*[:=]\s*"?)([^\s",;&}]{6,})/gi,
+        replace: (_m, prefix) => `${prefix}[redacted]`,
+    },
+];
+/**
+ * Replace every secret-shaped span in `text`. Returns the redacted text and a
+ * count of replacements, so triage can tell "no secrets present" from
+ * "redaction never ran".
+ */
+export function redactLogText(text) {
+    let out = text;
+    let redactions = 0;
+    for (const { pattern, replace } of REDACTION_PATTERNS) {
+        out = out.replace(pattern, (match, ...rest) => {
+            redactions++;
+            // String.replace passes (match, ...groups, offset, string). Keep only
+            // the capture groups — the trailing offset/string are not groups.
+            const groups = rest.slice(0, Math.max(0, rest.length - 2));
+            return replace(match, ...groups);
+        });
+    }
+    return { text: out, redactions };
+}
+/**
+ * `true` unless the user disabled log capture via `HQ_FEEDBACK_LOGS`.
+ *
+ * Uses `?.trim() ||` rather than `??` on purpose: an env var that is SET BUT
+ * EMPTY must fall back to the default, and `??` would pass `""` through as a
+ * deliberate choice.
+ */
+export function feedbackLogsEnabled(env = process.env) {
+    const raw = env.HQ_FEEDBACK_LOGS?.trim().toLowerCase() || "";
+    if (raw === "")
+        return true;
+    return !(raw === "0" || raw === "false" || raw === "no" || raw === "off");
+}
+/** Best-effort `lstat`. Returns null on any error. */
+function lstatOrNull(absPath) {
+    try {
+        return fs.lstatSync(absPath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Enumerate eligible log files under `hqDir`.
+ *
+ * Eligibility is the allowlist described in the module header: `*.log` files
+ * directly inside `hqDir/logs/`, plus {@link FEEDBACK_ROOT_LOG_FILENAMES} at
+ * the root. Every candidate must be a REGULAR file by `lstat` — directories
+ * and, critically, symlinks are rejected. Returned newest-modified first so
+ * the most relevant log is offered the budget before older ones.
+ */
+export function discoverLogFiles(hqDir) {
+    const candidates = [];
+    const consider = (relName) => {
+        const absPath = path.join(hqDir, relName);
+        const st = lstatOrNull(absPath);
+        // isFile() is false for both directories and symlinks under lstat. A
+        // symlink here would be the credential-exfiltration path (see header).
+        if (!st || !st.isFile())
+            return;
+        candidates.push({
+            name: relName,
+            absPath,
+            sizeBytes: st.size,
+            modifiedMs: st.mtimeMs,
+        });
+    };
+    let entries;
+    try {
+        entries = fs.readdirSync(path.join(hqDir, FEEDBACK_LOGS_DIRNAME));
+    }
+    catch {
+        // No logs directory on this installation — root logs may still exist.
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (!isEligibleLogName(entry))
+            continue;
+        consider(`${FEEDBACK_LOGS_DIRNAME}/${entry}`);
+    }
+    for (const filename of FEEDBACK_ROOT_LOG_FILENAMES) {
+        consider(filename);
+    }
+    candidates.sort((a, b) => b.modifiedMs - a.modifiedMs);
+    return candidates;
+}
+/**
+ * Read the last `maxBytes` of a file.
+ *
+ * When the file is larger than the window, the first (partial) line is dropped
+ * so the tail always starts at a line boundary. Returns null if the file
+ * cannot be read.
+ */
+export function readLogTail(absPath, maxBytes) {
+    let fd = null;
+    try {
+        fd = fs.openSync(absPath, "r");
+        const size = fs.fstatSync(fd).size;
+        const readBytes = Math.min(size, maxBytes);
+        if (readBytes <= 0)
+            return { text: "", truncated: false };
+        const buf = Buffer.allocUnsafe(readBytes);
+        const got = fs.readSync(fd, buf, 0, readBytes, size - readBytes);
+        let text = buf.subarray(0, got).toString("utf8");
+        const truncated = size > readBytes;
+        if (truncated) {
+            const nl = text.indexOf("\n");
+            // Drop the leading partial line. If the window holds no newline at all
+            // the whole tail is one giant line; keep it rather than returning "".
+            if (nl >= 0 && nl + 1 < text.length)
+                text = text.slice(nl + 1);
+        }
+        return { text, truncated };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // Best effort — a failed close must not fail the submission.
+            }
+        }
+    }
+}
+/**
+ * Enumerate eligible state files at the `~/.hq` root.
+ *
+ * Two ways in, both narrow: an exact name in {@link FEEDBACK_STATE_FILENAMES},
+ * or the `sync-journal.<slug>.json` shape. As with logs, every candidate must
+ * be a REGULAR file by `lstat`, so a symlink cannot be used to reach a
+ * credential file through an eligible-looking name.
+ */
+export function discoverStateFiles(hqDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(hqDir);
+    }
+    catch {
+        return [];
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        const eligible = FEEDBACK_STATE_FILENAMES.includes(entry) ||
+            (entry.startsWith(FEEDBACK_STATE_JOURNAL_PREFIX) && entry.endsWith(".json"));
+        if (!eligible)
+            continue;
+        const absPath = path.join(hqDir, entry);
+        const st = lstatOrNull(absPath);
+        if (!st || !st.isFile())
+            continue;
+        candidates.push({
+            name: entry,
+            absPath,
+            sizeBytes: st.size,
+            modifiedMs: st.mtimeMs,
+        });
+    }
+    candidates.sort((a, b) => a.name.localeCompare(b.name));
+    return candidates;
+}
+/**
+ * Enumerate flat, non-recursive entries of a `~/.hq` subdirectory.
+ *
+ * Used for `locks/`, where every entry is eligible regardless of extension —
+ * the filename itself carries the diagnosis. As everywhere else in this module,
+ * `lstat` decides eligibility, so a symlink dropped into the directory is
+ * skipped rather than followed.
+ *
+ * Results are sorted NEWEST-FIRST and only then truncated to `maxFiles`, which
+ * is load-bearing rather than cosmetic. Sorting by name and cutting at the cap
+ * silently drops the most diagnostic entry: ordinary `operation-*.lock` files
+ * sort ahead of a `qmd-reindex-bg.claim…stale-claim…`, so an installation with
+ * more than `maxFiles` locks would have excluded exactly the entry this source
+ * exists to capture. Recency is the right proxy for relevance here, and it
+ * matches how log files are prioritised.
+ */
+export function discoverFlatDirFiles(hqDir, dirName, maxFiles) {
+    let entries;
+    try {
+        entries = fs.readdirSync(path.join(hqDir, dirName));
+    }
+    catch {
+        return [];
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        const absPath = path.join(hqDir, dirName, entry);
+        const st = lstatOrNull(absPath);
+        if (!st || !st.isFile())
+            continue;
+        candidates.push({
+            name: `${dirName}/${entry}`,
+            absPath,
+            sizeBytes: st.size,
+            modifiedMs: st.mtimeMs,
+        });
+    }
+    // Sort BEFORE truncating, so the cap drops the least recent rather than
+    // whatever happened to sort last by name.
+    candidates.sort((a, b) => b.modifiedMs - a.modifiedMs || a.name.localeCompare(b.name));
+    return candidates.slice(0, maxFiles);
+}
+/**
+ * Walk a `~/.hq` subdirectory for `.json` files, bounded in BOTH depth and
+ * count.
+ *
+ * This is the module's only recursive traversal, so it is deliberately the
+ * most constrained. Three bounds, each load-bearing:
+ *
+ *   - `lstat` per entry, and recursion only into a REAL directory. A symlinked
+ *     directory is never followed, so a link at `jobs/x -> /home/user` cannot
+ *     turn a two-level walk into a scan of the home directory — where, as it
+ *     happens, `~/.codex/auth.json` and `~/.hq-agent/machine-creds.json` live.
+ *     This is the same guard the flat enumerations use, applied to directories
+ *     rather than files, and it is what keeps "walk a subtree" from being a
+ *     categorically riskier operation than the allowlists around it.
+ *   - `maxDepth`, so a deep tree cannot cost unbounded stat calls.
+ *   - `maxFiles`, so a wide tree cannot crowd the log budget.
+ *
+ * Entries are returned sorted by name for a stable, reviewable order.
+ */
+export function walkJsonFiles(hqDir, dirName, maxDepth, maxFiles) {
+    const candidates = [];
+    const walk = (relDir, depth) => {
+        if (depth > maxDepth || candidates.length >= maxFiles)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(hqDir, relDir));
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries.sort()) {
+            if (candidates.length >= maxFiles)
+                return;
+            const rel = `${relDir}/${entry}`;
+            const absPath = path.join(hqDir, rel);
+            const st = lstatOrNull(absPath);
+            if (!st)
+                continue;
+            // Recurse ONLY into a real directory: isDirectory() is false under lstat
+            // for a symlink, so links are never traversed.
+            if (st.isDirectory()) {
+                walk(rel, depth + 1);
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!entry.toLowerCase().endsWith(".json"))
+                continue;
+            candidates.push({
+                name: rel,
+                absPath,
+                sizeBytes: st.size,
+                modifiedMs: st.mtimeMs,
+            });
+        }
+    };
+    walk(dirName, 1);
+    return candidates;
+}
+/**
+ * Read up to `maxBytes` from the START of a file. State documents are JSON,
+ * whose meaningful keys sit at the top, so a head is more useful than a tail.
+ * Returns null if the file cannot be read.
+ */
+export function readFileHead(absPath, maxBytes) {
+    let fd = null;
+    try {
+        fd = fs.openSync(absPath, "r");
+        const size = fs.fstatSync(fd).size;
+        const readBytes = Math.min(size, maxBytes);
+        if (readBytes <= 0)
+            return { text: "", truncated: false };
+        const buf = Buffer.allocUnsafe(readBytes);
+        const got = fs.readSync(fd, buf, 0, readBytes, 0);
+        return { text: buf.subarray(0, got).toString("utf8"), truncated: size > readBytes };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // Best effort — a failed close must not fail the submission.
+            }
+        }
+    }
+}
+/**
+ * Collect redacted `~/.hq` evidence within `budgetBytes`.
+ *
+ * State snapshots are taken first, capped by
+ * {@link FEEDBACK_STATE_MAX_TOTAL_BYTES}, because they are small and answer
+ * questions a log tail cannot. Log tails then take whatever budget remains.
+ *
+ * Returns `undefined` when nothing eligible exists at all, so the caller can
+ * omit the field entirely rather than attach an empty object. Never throws.
+ */
+export function collectFeedbackLogs(opts = {}) {
+    const budgetBytes = Math.max(0, Math.min(opts.budgetBytes ?? FEEDBACK_LOGS_MAX_TOTAL_BYTES, FEEDBACK_LOGS_MAX_TOTAL_BYTES));
+    const hqDir = opts.hqDir ?? path.join(opts.homeDir ?? os.homedir(), ".hq");
+    let logCandidates;
+    let stateCandidates;
+    try {
+        logCandidates = discoverLogFiles(hqDir);
+        // Order matters: root status documents first, then the lock/claim files
+        // (highest signal for a hang), then scheduled-job status. Under a tight
+        // budget the earlier ones win, and that is the intended priority.
+        stateCandidates = [
+            ...discoverStateFiles(hqDir),
+            ...discoverFlatDirFiles(hqDir, FEEDBACK_LOCKS_DIRNAME, FEEDBACK_LOCKS_MAX_FILES),
+            ...walkJsonFiles(hqDir, FEEDBACK_JOBS_DIRNAME, FEEDBACK_JOBS_MAX_DEPTH, FEEDBACK_JOBS_MAX_FILES),
+        ];
+    }
+    catch {
+        return undefined;
+    }
+    if (logCandidates.length === 0 && stateCandidates.length === 0)
+        return undefined;
+    const files = [];
+    const state = [];
+    const skipped = [];
+    let skippedOverflow = 0;
+    const recordSkip = (name, reason) => {
+        if (skipped.length < FEEDBACK_MAX_SKIPPED_ENTRIES) {
+            skipped.push({ name, reason });
+        }
+        else {
+            skippedOverflow++;
+        }
+    };
+    let remaining = budgetBytes;
+    // State first: dense, bounded, and the part a triager reads before the logs.
+    let stateRemaining = Math.min(remaining, FEEDBACK_STATE_MAX_TOTAL_BYTES);
+    for (const candidate of stateCandidates) {
+        // A lock file is the one case where an EMPTY file is still evidence: the
+        // filename carries the operation, the owning pid, and whether the claim
+        // went stale, and many lock implementations write no body at all. Skipping
+        // it for emptiness would discard the single highest-signal artifact for a
+        // hang, so locks are kept with empty content and only their metadata.
+        const isLock = candidate.name.startsWith(`${FEEDBACK_LOCKS_DIRNAME}/`);
+        if (candidate.sizeBytes === 0 && !isLock) {
+            recordSkip(candidate.name, "empty");
+            continue;
+        }
+        if (stateRemaining <= 0) {
+            recordSkip(candidate.name, "budget");
+            continue;
+        }
+        const perFileMax = candidate.name.startsWith(`${FEEDBACK_LOCKS_DIRNAME}/`)
+            ? FEEDBACK_LOCK_MAX_FILE_BYTES
+            : FEEDBACK_STATE_MAX_FILE_BYTES;
+        const window = Math.min(stateRemaining, perFileMax);
+        const raw = readFileHead(candidate.absPath, window);
+        if (raw === null) {
+            recordSkip(candidate.name, "unreadable");
+            continue;
+        }
+        const { text, redactions } = redactLogText(raw.text);
+        if (text.trim().length === 0 && !isLock) {
+            recordSkip(candidate.name, "empty");
+            continue;
+        }
+        const includedBytes = Buffer.byteLength(text, "utf8");
+        state.push({
+            name: candidate.name,
+            sizeBytes: candidate.sizeBytes,
+            modifiedIso: Number.isFinite(candidate.modifiedMs)
+                ? new Date(candidate.modifiedMs).toISOString()
+                : null,
+            includedBytes,
+            truncated: raw.truncated,
+            redactions,
+            content: text,
+        });
+        stateRemaining -= includedBytes;
+        remaining -= includedBytes;
+    }
+    for (const candidate of logCandidates) {
+        if (candidate.sizeBytes === 0) {
+            recordSkip(candidate.name, "empty");
+            continue;
+        }
+        if (remaining < FEEDBACK_LOGS_MIN_USEFUL_BYTES) {
+            recordSkip(candidate.name, "budget");
+            continue;
+        }
+        const window = Math.min(remaining, FEEDBACK_LOGS_MAX_FILE_TAIL_BYTES);
+        const raw = readLogTail(candidate.absPath, window);
+        if (raw === null) {
+            recordSkip(candidate.name, "unreadable");
+            continue;
+        }
+        // Redact BEFORE measuring, so the budget is spent on what actually ships
+        // and no unredacted span can reach the return value.
+        const { text, redactions } = redactLogText(raw.text);
+        if (text.trim().length === 0) {
+            recordSkip(candidate.name, "empty");
+            continue;
+        }
+        const includedBytes = Buffer.byteLength(text, "utf8");
+        files.push({
+            name: candidate.name,
+            sizeBytes: candidate.sizeBytes,
+            modifiedIso: Number.isFinite(candidate.modifiedMs)
+                ? new Date(candidate.modifiedMs).toISOString()
+                : null,
+            includedBytes,
+            // Truncated if we only read a window, OR if redaction happened to be a
+            // no-op but the read itself was partial.
+            truncated: raw.truncated,
+            redactions,
+            tail: text,
+        });
+        remaining -= includedBytes;
+    }
+    return {
+        budgetBytes,
+        files,
+        state,
+        skipped,
+        ...(skippedOverflow > 0 ? { skippedOverflow } : {}),
+    };
+}
+//# sourceMappingURL=feedback-logs.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.108.5",
+  "version": "5.108.6",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -31,7 +31,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.6",
+    "@indigoai-us/hq-cloud": "~6.16.11",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",