@indigoai-us/hq-cli 5.111.2 → 5.113.0

package/dist/lazy-commands.d.ts

@@ -1,55 +1,31 @@
-/**
- * Hot-command manifest for the entrypoint's lazy registration.
- *
- * main.ts used to import the entire ~60-module command graph at module scope,
- * so every invocation paid for every command. That is fine for a human typing
- * one command and ruinous for the calls automation makes in a loop: the
- * hq-sentry agent fleet on an outpost runs `hq secrets` about 39 times a minute
- * (each worker resolves credentials before every external command it executes),
- * and each of those processes spent ~0.75 CPU-seconds importing commands it
- * never ran — around half a core, continuously. Measured on Outpost 2
- * (i-09424eff61920a4ac) 2026-09-05; see register-all.ts for the numbers.
- *
- * A command listed here registers ITSELF and nothing else. Anything not listed
- * — `--help`, a bare `hq`, an unknown command, every other command — falls back
- * to `registerAllCommands`, the complete unchanged graph. That fallback is what
- * makes this safe to extend one command at a time: an entry is a performance
- * opt-in, never a behaviour change, and a command that is absent here is simply
- * as fast as it was before.
- *
- * This mirrors commands/scaffold-fast.ts, which does the same thing for the
- * relocated `hq core …` scripts, and carries the same anti-drift discipline: a
- * parity test registers each entry BOTH ways and asserts the resulting command
- * shape is identical, so a manifest entry cannot silently diverge from the real
- * registration.
- *
- * TO ADD A COMMAND: it must register exactly one top-level command, be
- * registered onto `program` (not onto a subcommand group), and have no other
- * module contributing subcommands to it. The parity test enforces the shape;
- * these three conditions are what make the entry correct in the first place.
- */
-import type { Command } from "commander";
+import { Command } from "commander";
 export type LazyCommand = {
-    /** The top-level token this matches — `hq <name> …`. */
+    /** Canonical top-level name; aliases resolve to this name. */
     name: string;
-    /** Registers this one command onto `program`, importing only its module. */
+    /** Registers every contributor for this root and no unrelated root. */
     register: (program: Command) => Promise<void>;
 };
 /**
- * The hot paths, in descending order of how often automation calls them.
- *
- * `secrets` and `run` are the two commands HQ's own tooling puts on the inner
- * loop: every fleet worker shells through one of them before each external
- * command, which is exactly the shape that makes eager import expensive.
+ * One entry for every root, including groups that are assembled by several
+ * registrar modules. The routing metadata itself is generated from the eager
+ * command graph and checked in tests and the build.
  */
 export declare const LAZY_COMMANDS: readonly LazyCommand[];
 /**
- * Resolve `process.argv` to a manifest entry, or null to use the full graph.
- *
- * argv is `[node, hq, <name>, ...rest]`. `hq` declares no program-level options
- * before the command name, so argv[2] is the command token when there is one;
- * `--help`, `--version`, and a bare `hq` all fail the lookup and take the
- * fallback, which is the intended behaviour — help must list every command.
+ * Keep the registration seam at register-all.js. Besides making one place own
+ * the graph, this lets the torn-install recovery wrap failures while an update
+ * replaces the installed tree between startup and command registration.
+ */
+export declare function registerCommandRoot(program: Command, root: string): Promise<boolean>;
+/**
+ * Register only generated root metadata. This is enough for root help and
+ * Commander suggestions, without evaluating an implementation module.
+ */
+export declare function registerCommandCatalog(program: Command): void;
+/**
+ * Resolve the root requested by Commander argv. Root help, a bare invocation,
+ * and unknown tokens deliberately return null so the lightweight catalog can
+ * preserve the complete help and unknown-command recovery surfaces.
  */
 export declare function findLazyCommand(argv: readonly string[]): LazyCommand | null;
 //# sourceMappingURL=lazy-commands.d.ts.map

package/dist/lazy-commands.js

@@ -1,68 +1,67 @@
+import { Command } from "commander";
+import { COMMAND_CATALOG } from "./command-catalog.generated.js";
+const commandCatalog = COMMAND_CATALOG;
 /**
- * Hot-command manifest for the entrypoint's lazy registration.
- *
- * main.ts used to import the entire ~60-module command graph at module scope,
- * so every invocation paid for every command. That is fine for a human typing
- * one command and ruinous for the calls automation makes in a loop: the
- * hq-sentry agent fleet on an outpost runs `hq secrets` about 39 times a minute
- * (each worker resolves credentials before every external command it executes),
- * and each of those processes spent ~0.75 CPU-seconds importing commands it
- * never ran — around half a core, continuously. Measured on Outpost 2
- * (i-09424eff61920a4ac) 2026-09-05; see register-all.ts for the numbers.
- *
- * A command listed here registers ITSELF and nothing else. Anything not listed
- * — `--help`, a bare `hq`, an unknown command, every other command — falls back
- * to `registerAllCommands`, the complete unchanged graph. That fallback is what
- * makes this safe to extend one command at a time: an entry is a performance
- * opt-in, never a behaviour change, and a command that is absent here is simply
- * as fast as it was before.
- *
- * This mirrors commands/scaffold-fast.ts, which does the same thing for the
- * relocated `hq core …` scripts, and carries the same anti-drift discipline: a
- * parity test registers each entry BOTH ways and asserts the resulting command
- * shape is identical, so a manifest entry cannot silently diverge from the real
- * registration.
- *
- * TO ADD A COMMAND: it must register exactly one top-level command, be
- * registered onto `program` (not onto a subcommand group), and have no other
- * module contributing subcommands to it. The parity test enforces the shape;
- * these three conditions are what make the entry correct in the first place.
+ * One entry for every root, including groups that are assembled by several
+ * registrar modules. The routing metadata itself is generated from the eager
+ * command graph and checked in tests and the build.
  */
+export const LAZY_COMMANDS = commandCatalog.map((command) => ({
+    name: command.name,
+    register: async (program) => {
+        const registered = await registerCommandRoot(program, command.name);
+        if (!registered)
+            throw new Error(`No registration plan for '${command.name}'`);
+    },
+}));
 /**
- * The hot paths, in descending order of how often automation calls them.
- *
- * `secrets` and `run` are the two commands HQ's own tooling puts on the inner
- * loop: every fleet worker shells through one of them before each external
- * command, which is exactly the shape that makes eager import expensive.
+ * Keep the registration seam at register-all.js. Besides making one place own
+ * the graph, this lets the torn-install recovery wrap failures while an update
+ * replaces the installed tree between startup and command registration.
  */
-export const LAZY_COMMANDS = [
-    {
-        name: "secrets",
-        register: async (program) => {
-            const { registerSecretsCommand } = await import("./commands/secrets.js");
-            registerSecretsCommand(program);
-        },
-    },
-    {
-        name: "run",
-        register: async (program) => {
-            const { registerRunCommand } = await import("./commands/run.js");
-            registerRunCommand(program);
-        },
-    },
-];
+export async function registerCommandRoot(program, root) {
+    const registration = await import("./register-all.js");
+    return registration.registerCommandRoot(program, root);
+}
+function commandDefinition(command) {
+    const stub = new Command(command.name)
+        .description(command.description);
+    for (const alias of command.aliases)
+        stub.alias(alias);
+    for (const argument of command.arguments) {
+        const name = `${argument.name}${argument.variadic ? "..." : ""}`;
+        stub.argument(argument.required ? `<${name}>` : `[${name}]`);
+    }
+    for (const option of command.options)
+        stub.option(option.flags, option.description);
+    if (command.hidden)
+        stub._hidden = true;
+    return stub;
+}
 /**
- * Resolve `process.argv` to a manifest entry, or null to use the full graph.
- *
- * argv is `[node, hq, <name>, ...rest]`. `hq` declares no program-level options
- * before the command name, so argv[2] is the command token when there is one;
- * `--help`, `--version`, and a bare `hq` all fail the lookup and take the
- * fallback, which is the intended behaviour — help must list every command.
+ * Register only generated root metadata. This is enough for root help and
+ * Commander suggestions, without evaluating an implementation module.
+ */
+export function registerCommandCatalog(program) {
+    for (const command of commandCatalog)
+        program.addCommand(commandDefinition(command));
+}
+function commandForToken(token) {
+    return commandCatalog.find((candidate) => candidate.name === token || candidate.aliases.includes(token));
+}
+/**
+ * Resolve the root requested by Commander argv. Root help, a bare invocation,
+ * and unknown tokens deliberately return null so the lightweight catalog can
+ * preserve the complete help and unknown-command recovery surfaces.
  */
 export function findLazyCommand(argv) {
-    const name = argv[2];
-    if (typeof name !== "string")
+    const first = argv[2];
+    const token = first === "help" ? argv[3] : first;
+    if (typeof token !== "string" || token.startsWith("-"))
+        return null;
+    const command = commandForToken(token);
+    if (!command)
         return null;
-    return LAZY_COMMANDS.find((candidate) => candidate.name === name) ?? null;
+    return LAZY_COMMANDS.find((candidate) => candidate.name === command.name) ?? null;
 }
 //# sourceMappingURL=lazy-commands.js.map

package/dist/lib/core-utils/qmd-reindex-after-sync.d.ts

@@ -10,6 +10,7 @@ export type QmdReindexOptions = UtilityIo & {
         bin: string;
         cwd: string;
     }) => unknown;
+    sizeLimit?: (hqRoot: string) => unknown;
 };
 export declare function qmdReindexAfterSync(args?: string[], options?: QmdReindexOptions): number;
 //# sourceMappingURL=qmd-reindex-after-sync.d.ts.map

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -12,6 +12,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { reconcileCollections, resolveQmdBin, runQmd } from "../search-index/index.js";
+import { applyIndexSizeLimit } from "../search-index/max-doc-bytes.js";
 export function qmdReindexAfterSync(args = [], options = {}) {
     let hqRoot = "";
     let embed = false;
@@ -36,6 +37,7 @@ export function qmdReindexAfterSync(args = [], options = {}) {
         return 0;
     const reconcile = options.reconcile ?? ((root, opts) => reconcileCollections(root, opts));
     const run = options.run ?? ((argv, opts) => runQmd(argv, opts));
+    const sizeLimit = options.sizeLimit ?? ((root) => applyIndexSizeLimit(root));
     // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
     try {
         reconcile(hqRoot, { bin });
@@ -43,6 +45,16 @@ export function qmdReindexAfterSync(args = [], options = {}) {
     catch {
         /* registration is advisory; an update still helps */
     }
+    // The cap has to land before the update, not after: qmd decides what to read
+    // at glob time, so an ignore entry written afterwards saves nothing on this
+    // pass. This is the post-sync entry point, which reaches `qmd update` without
+    // going through `hq index sync` at all.
+    try {
+        sizeLimit(hqRoot);
+    }
+    catch {
+        /* an uncapped index is worse than none, but still better than a failed sync */
+    }
     try {
         run(["update"], { bin, cwd: hqRoot });
     }

package/dist/lib/core-utils/sentry-report.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `hq core sentry report` — constrained diagnostic transport for HQ hooks.
+ *
+ * The stdin event schema is deliberately closed. Hook payloads can contain
+ * commands, prompts, source content, transcript locations, and credentials, so
+ * this module accepts only a small set of scalar diagnostics and never reads a
+ * hook payload or the process environment. The owner-approved `hook_path`
+ * diagnostic is the narrow exception: it names the slow hook script and may
+ * include its company directory, but never carries the hook payload itself.
+ *
+ * Invalid top-level input and structurally rich metadata are rejected rather
+ * than truncated. Unknown scalar metadata is dropped instead: the allowlist,
+ * not a caller version match, determines what may leave the machine.
+ */
+import type { CaptureContext, SeverityLevel } from "@sentry/node";
+export declare const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
+export declare const MAX_SENTRY_REPORT_TIMEOUT_MS = 5000;
+export declare const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2048;
+export declare const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
+/**
+ * The only hook diagnostics that can be attached as metadata. The list omits
+ * command text, prompts, payloads, company names, and repositories. `hook_path`
+ * is owner-approved telemetry for the exact hook script and may include a
+ * company directory; it is never a substitute for hook input or a transcript.
+ */
+export declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["hook_name", "hook_path", "hook_event", "tool_name", "session_id", "declared_timeout_ms", "elapsed_ms", "remaining_ms", "watchdog_timeout_ms", "hook_timeout_ms", "hq_version", "platform", "load_average"];
+export declare const MAX_SENTRY_REPORT_METADATA_KEYS: number;
+export type SentryReportMetadata = Record<string, string | number | boolean>;
+export type SentryReportEvent = {
+    type: string;
+    message: string;
+    fingerprint: string;
+    level: SeverityLevel;
+    metadata: SentryReportMetadata;
+};
+export type SentryReportOptions = {
+    dryRun?: boolean;
+    /** Total time reserved for the report flush after validation. */
+    timeoutMs?: number;
+};
+export type SentryReportDependencies = {
+    sentry: {
+        captureMessage: (message: string, context?: CaptureContext | SeverityLevel) => string;
+        flush: (timeout?: number) => PromiseLike<boolean>;
+    };
+    stdout: Pick<NodeJS.WriteStream, "write">;
+    stderr: Pick<NodeJS.WriteStream, "write">;
+};
+export type SentryReportResult = {
+    code: 0 | 1;
+    event?: SentryReportEvent;
+    droppedMetadataKeys?: number;
+};
+/**
+ * Read no more than the accepted event size. Returning early keeps a malformed
+ * pipe from making a watchdog retain an unbounded hook payload in memory.
+ */
+export declare function readSentryReportStdin(stdin: AsyncIterable<Buffer | string>): Promise<string | null>;
+/** Unknown metadata is ignored before this cap is evaluated. */
+export declare function exceedsSentryReportMetadataKeyCap(keys: Iterable<string>): boolean;
+/**
+ * Parse and validate the closed report schema without touching Sentry. The
+ * function intentionally returns an ordinary result instead of throwing so a
+ * hook can ignore the CLI exit code without creating an unhandled rejection.
+ */
+export declare function parseSentryReportEvent(stdin: string): SentryReportResult;
+/**
+ * Capture one validated Sentry message and wait only for the supplied bounded
+ * flush budget. A zero result means the event entered the local transport and
+ * its queue drained in time, not that ingest accepted it. Normal reports are
+ * silent on stdout; dry-runs print the same scrubbed event projection used by
+ * the live path. All failures use a generic stderr line so malformed input and
+ * transport errors cannot echo event data back to a hook.
+ */
+export declare function reportSentryEvent(stdin: string, options?: SentryReportOptions, dependencies?: SentryReportDependencies): Promise<SentryReportResult>;
+//# sourceMappingURL=sentry-report.d.ts.map

package/dist/lib/core-utils/sentry-report.js

@@ -0,0 +1,255 @@
+/**
+ * `hq core sentry report` — constrained diagnostic transport for HQ hooks.
+ *
+ * The stdin event schema is deliberately closed. Hook payloads can contain
+ * commands, prompts, source content, transcript locations, and credentials, so
+ * this module accepts only a small set of scalar diagnostics and never reads a
+ * hook payload or the process environment. The owner-approved `hook_path`
+ * diagnostic is the narrow exception: it names the slow hook script and may
+ * include its company directory, but never carries the hook payload itself.
+ *
+ * Invalid top-level input and structurally rich metadata are rejected rather
+ * than truncated. Unknown scalar metadata is dropped instead: the allowlist,
+ * not a caller version match, determines what may leave the machine.
+ */
+import * as Sentry from "@sentry/node";
+import { beforeSend } from "../../sentry-before-send.js";
+export const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
+export const MAX_SENTRY_REPORT_TIMEOUT_MS = 5_000;
+export const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2_048;
+export const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
+const MAX_SENTRY_REPORT_TYPE_BYTES = 64;
+const MAX_SENTRY_REPORT_MESSAGE_BYTES = 1_024;
+const MAX_SENTRY_REPORT_FINGERPRINT_BYTES = 128;
+const SENTRY_REPORT_LEVELS = new Set([
+    "fatal",
+    "error",
+    "warning",
+    "log",
+    "info",
+    "debug",
+]);
+/**
+ * The only hook diagnostics that can be attached as metadata. The list omits
+ * command text, prompts, payloads, company names, and repositories. `hook_path`
+ * is owner-approved telemetry for the exact hook script and may include a
+ * company directory; it is never a substitute for hook input or a transcript.
+ */
+export const ALLOWED_SENTRY_REPORT_METADATA_KEYS = [
+    "hook_name",
+    "hook_path",
+    "hook_event",
+    "tool_name",
+    "session_id",
+    "declared_timeout_ms",
+    "elapsed_ms",
+    "remaining_ms",
+    "watchdog_timeout_ms",
+    "hook_timeout_ms",
+    "hq_version",
+    "platform",
+    "load_average",
+];
+const ALLOWED_METADATA_KEYS = new Set(ALLOWED_SENTRY_REPORT_METADATA_KEYS);
+const SENTRY_REPORT_METADATA_KEY_HEADROOM = 2;
+// This tracks the schema rather than a separately-maintained literal. A caller
+// can send every recognised key with room for two later recognised fields,
+// while unknown keys are deliberately dropped.
+export const MAX_SENTRY_REPORT_METADATA_KEYS = ALLOWED_SENTRY_REPORT_METADATA_KEYS.length + SENTRY_REPORT_METADATA_KEY_HEADROOM;
+const defaultDependencies = {
+    sentry: Sentry,
+    stdout: process.stdout,
+    stderr: process.stderr,
+};
+/**
+ * Read no more than the accepted event size. Returning early keeps a malformed
+ * pipe from making a watchdog retain an unbounded hook payload in memory.
+ */
+export async function readSentryReportStdin(stdin) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+        totalBytes += bytes.length;
+        if (totalBytes > MAX_SENTRY_REPORT_PAYLOAD_BYTES)
+            return null;
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function isBoundedString(value, maxBytes) {
+    return typeof value === "string" && value.length > 0 && byteLength(value) <= maxBytes;
+}
+function isScalarMetadataValue(value) {
+    if (typeof value === "string")
+        return byteLength(value) <= MAX_SENTRY_REPORT_METADATA_VALUE_BYTES;
+    if (typeof value === "boolean")
+        return true;
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isAllowedMetadataValue(key, value) {
+    if (!isScalarMetadataValue(value))
+        return false;
+    if (key === "tool_name" || key === "session_id" || key === "hook_path") {
+        return typeof value === "string";
+    }
+    return true;
+}
+/** Unknown metadata is ignored before this cap is evaluated. */
+export function exceedsSentryReportMetadataKeyCap(keys) {
+    let recognisedKeys = 0;
+    for (const key of keys) {
+        if (!ALLOWED_METADATA_KEYS.has(key))
+            continue;
+        recognisedKeys++;
+        if (recognisedKeys > MAX_SENTRY_REPORT_METADATA_KEYS)
+            return true;
+    }
+    return false;
+}
+function invalidInput() {
+    return { code: 1 };
+}
+/**
+ * Parse and validate the closed report schema without touching Sentry. The
+ * function intentionally returns an ordinary result instead of throwing so a
+ * hook can ignore the CLI exit code without creating an unhandled rejection.
+ */
+export function parseSentryReportEvent(stdin) {
+    if (byteLength(stdin) > MAX_SENTRY_REPORT_PAYLOAD_BYTES)
+        return invalidInput();
+    let parsed;
+    try {
+        parsed = JSON.parse(stdin);
+    }
+    catch {
+        return invalidInput();
+    }
+    if (!isRecord(parsed))
+        return invalidInput();
+    const allowedTopLevel = new Set(["type", "message", "fingerprint", "level", "metadata"]);
+    if (Object.keys(parsed).some((key) => !allowedTopLevel.has(key)))
+        return invalidInput();
+    if (!isBoundedString(parsed.type, MAX_SENTRY_REPORT_TYPE_BYTES))
+        return invalidInput();
+    if (!isBoundedString(parsed.message, MAX_SENTRY_REPORT_MESSAGE_BYTES))
+        return invalidInput();
+    if (!isBoundedString(parsed.fingerprint, MAX_SENTRY_REPORT_FINGERPRINT_BYTES))
+        return invalidInput();
+    if (typeof parsed.level !== "string" || !SENTRY_REPORT_LEVELS.has(parsed.level)) {
+        return invalidInput();
+    }
+    const rawMetadata = "metadata" in parsed ? parsed.metadata : {};
+    if (!isRecord(rawMetadata))
+        return invalidInput();
+    const metadataKeys = Object.keys(rawMetadata);
+    if (exceedsSentryReportMetadataKeyCap(metadataKeys))
+        return invalidInput();
+    const metadata = {};
+    let droppedMetadataKeys = 0;
+    for (const key of metadataKeys) {
+        if (!isScalarMetadataValue(rawMetadata[key]))
+            return invalidInput();
+        if (!ALLOWED_METADATA_KEYS.has(key)) {
+            droppedMetadataKeys++;
+            continue;
+        }
+        if (!isAllowedMetadataValue(key, rawMetadata[key]))
+            return invalidInput();
+        metadata[key] = rawMetadata[key];
+    }
+    return {
+        code: 0,
+        event: {
+            type: parsed.type,
+            message: parsed.message,
+            fingerprint: parsed.fingerprint,
+            level: parsed.level,
+            metadata,
+        },
+        droppedMetadataKeys,
+    };
+}
+function resolveTimeout(timeoutMs) {
+    const timeout = timeoutMs ?? DEFAULT_SENTRY_REPORT_TIMEOUT_MS;
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > MAX_SENTRY_REPORT_TIMEOUT_MS)
+        return null;
+    return timeout;
+}
+function sentryEnvelope(event) {
+    return {
+        level: event.level,
+        fingerprint: [event.fingerprint],
+        tags: { sentry_event_type: event.type },
+        extra: event.metadata,
+    };
+}
+/** Build the same scrubbed event projection that the live SDK path uses. */
+function scrubbedSentryEnvelope(event) {
+    return beforeSend({
+        message: event.message,
+        ...sentryEnvelope(event),
+    }, {});
+}
+/**
+ * Resolve true only when the local transport queue drains within the budget.
+ * This does not confirm that the ingest service accepted the event.
+ */
+async function flushWithin(sentry, timeoutMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), timeoutMs);
+        void Promise.resolve()
+            .then(() => sentry.flush(timeoutMs))
+            .then((flushed) => {
+            clearTimeout(timer);
+            resolve(flushed === true);
+        }, () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+/**
+ * Capture one validated Sentry message and wait only for the supplied bounded
+ * flush budget. A zero result means the event entered the local transport and
+ * its queue drained in time, not that ingest accepted it. Normal reports are
+ * silent on stdout; dry-runs print the same scrubbed event projection used by
+ * the live path. All failures use a generic stderr line so malformed input and
+ * transport errors cannot echo event data back to a hook.
+ */
+export async function reportSentryEvent(stdin, options = {}, dependencies = defaultDependencies) {
+    const timeoutMs = resolveTimeout(options.timeoutMs);
+    const result = parseSentryReportEvent(stdin);
+    if (timeoutMs === null || result.code !== 0 || !result.event) {
+        dependencies.stderr.write("Invalid Sentry report input.\n");
+        return invalidInput();
+    }
+    if (result.droppedMetadataKeys) {
+        const noun = result.droppedMetadataKeys === 1 ? "key" : "keys";
+        dependencies.stderr.write(`Dropped ${result.droppedMetadataKeys} unsupported Sentry report metadata ${noun}.\n`);
+    }
+    const envelope = sentryEnvelope(result.event);
+    if (options.dryRun) {
+        const scrubbed = scrubbedSentryEnvelope(result.event);
+        if (scrubbed)
+            dependencies.stdout.write(`${JSON.stringify(scrubbed)}\n`);
+        return result;
+    }
+    try {
+        dependencies.sentry.captureMessage(result.event.message, envelope);
+        if (await flushWithin(dependencies.sentry, timeoutMs))
+            return result;
+    }
+    catch {
+        // Report failure below without exposing event fields or transport details.
+    }
+    dependencies.stderr.write("Sentry report failed.\n");
+    return invalidInput();
+}
+//# sourceMappingURL=sentry-report.js.map

package/dist/lib/search-index/background.d.ts

@@ -15,6 +15,8 @@ export type BackgroundDependencies = {
     isProcessAlive: (pid: number) => boolean;
     resolveQmdBin: () => string;
     reconcileCollections: (hqRoot: string) => unknown;
+    /** Apply the per-document size cap to qmd's config before the update reads anything. */
+    applyIndexSizeLimit: (hqRoot: string) => unknown;
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
     spawnWorker: (options: {
         logPath: string;

package/dist/lib/search-index/background.js

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { Sentry } from '../../sentry.js';
 import { reconcileCollections as defaultReconcileCollections, resolveQmdBin as defaultResolveQmdBin, runQmd as defaultRunQmd, } from './index.js';
+import { applyIndexSizeLimit as defaultApplyIndexSizeLimit } from './max-doc-bytes.js';
 const LOCK_NAME = 'qmd-reindex-bg.lock';
 const COMPLETE_NAME = 'qmd-reindex-bg.completed';
 function errnoInfo(error) {
@@ -119,6 +120,7 @@ export function defaultBackgroundDependencies(hqRoot) {
         isProcessAlive: alive,
         resolveQmdBin: defaultResolveQmdBin,
         reconcileCollections: defaultReconcileCollections,
+        applyIndexSizeLimit: defaultApplyIndexSizeLimit,
         runQmd: defaultRunQmd,
         spawnWorker: defaultSpawnWorker,
     };
@@ -420,6 +422,21 @@ function capWorkerLog(logPath, env) {
 function stepOutput(result) {
     return `${result.stdout ?? ''}${result.stderr ?? ''}`;
 }
+/**
+ * One worker-log line summarising the size cap, so an operator reading the log
+ * can see WHY a file stopped being indexed. Shaped defensively because the
+ * dependency is typed `unknown` at the seam.
+ */
+function sizeLimitOutput(result) {
+    const r = result;
+    if (typeof r?.maxBytes !== 'number')
+        return '';
+    if (r.maxBytes === 0)
+        return '[qmd-reindex-bg] size cap disabled\n';
+    const collections = r.collections ?? [];
+    const files = collections.reduce((total, collection) => total + collection.ignored.length, 0);
+    return `[qmd-reindex-bg] size cap ${r.maxBytes}B — ${files} file(s) skipped across ${collections.length} collection(s)\n`;
+}
 function errorOutput(error) {
     const e = error;
     return `${e.stdout ?? ''}${e.stderr ?? ''}` || (e.message ?? '');
@@ -500,6 +517,17 @@ export async function runBackgroundWorker(dependencies) {
             // The shell worker has no collection-registration step. Keep this #306
             // integration best-effort so it cannot suppress a later index update.
         }
+        // The size cap rewrites qmd's ignore lists, so it MUST land before the
+        // update below — an oversized file is skipped at glob time or not at all.
+        // Best-effort for the same reason as reconciliation: a capping failure must
+        // not suppress an otherwise healthy index update.
+        try {
+            const capped = dependencies.applyIndexSizeLimit(dependencies.hqRoot);
+            appendWorkerLog(logPath, sizeLimitOutput(capped));
+        }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error));
+        }
         if (await signalWindow())
             return { state: 'terminated' };
         try {