@ironbee-ai/cli 0.5.3 → 0.6.1

package/dist/lib/collector.js

@@ -2,12 +2,24 @@
 /**
  * IronBee CLI — Collector Client
  *
- * Sends events to the IronBee Collector service.
- * Non-blocking, fail-safe — never throws, never blocks CLI for more than 3s.
+ * Shared HTTP transport for pushing events to the IronBee Collector
+ * (`POST {url}/v1/events`). Two callers use it today:
  *
- * Requires collector.url and collector.apiKey in config.
+ *   - `sendToCollector(entry, …)`   — fire-and-forget single-event send used
+ *     by `appendAction` in the interactive path. Short timeout, resolves on
+ *     ANY response (status ignored for backward-compat), rejects only on
+ *     network / timeout errors.
+ *
+ *   - `postEventsBatch(events, cc)` — low-level primitive returning
+ *     `{ status, body }` so callers can classify the response. Used by the
+ *     queue `send_event` handler for HTTP-status → TransientError /
+ *     AuthError / BadRequestBatchError classification (spec §6).
+ *
+ * Both are no-ops when `IRONBEE_COLLECTOR=false` is set (jest harness).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.postEventsBatch = postEventsBatch;
+exports.getCollectorTarget = getCollectorTarget;
 exports.sendToCollector = sendToCollector;
 const https_1 = require("https");
 const http_1 = require("http");
@@ -15,59 +27,119 @@ const config_1 = require("./config");
 const logger_1 = require("./logger");
 const SEND_TIMEOUT_MS = 3000;
 const EVENTS_PATH = "/v1/events";
-function getCollectorConfig(projectDir) {
-    const config = (0, config_1.loadConfig)(projectDir);
-    if (config.collector && config.collector.url && config.collector.apiKey) {
-        return { url: config.collector.url, apiKey: config.collector.apiKey };
-    }
-    return null;
-}
-async function sendToCollector(entry, _sessionId, projectDir) {
-    if (process.env.IRONBEE_COLLECTOR === "false") {
-        return;
-    }
+/**
+ * Low-level transport: POST a JSON array of events to the collector and
+ * resolve with the HTTP status + response body. Rejects on network error,
+ * connect timeout, or socket timeout. Does NOT throw on non-2xx — callers
+ * decide what HTTP status means for their use case.
+ */
+async function postEventsBatch(events, target, opts) {
+    const timeoutMs = opts?.timeoutMs ?? SEND_TIMEOUT_MS;
     return new Promise((resolve, reject) => {
         try {
-            const collectorConfig = getCollectorConfig(projectDir);
-            if (!collectorConfig) {
-                resolve();
-                return;
-            }
-            // entry is already enriched with id/session_id/project_name/timestamp by appendAction.
-            const event = { ...entry };
-            const body = JSON.stringify([event]);
-            const url = new URL(EVENTS_PATH, collectorConfig.url);
+            const body = JSON.stringify(events);
+            const url = new URL(EVENTS_PATH, target.url);
             const isHttps = url.protocol === "https:";
             const doRequest = isHttps ? https_1.request : http_1.request;
-            const timeout = setTimeout(() => {
-                logger_1.logger.debug("collector: send timeout");
+            const timer = setTimeout(() => {
                 reject(new Error("collector: send timeout"));
-            }, SEND_TIMEOUT_MS);
+            }, timeoutMs);
             const req = doRequest({
                 hostname: url.hostname,
                 port: url.port || (isHttps ? 443 : 80),
-                path: url.pathname,
+                path: url.pathname + url.search,
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
                     "Content-Length": Buffer.byteLength(body),
-                    ...(collectorConfig.apiKey ? { "X-API-Key": collectorConfig.apiKey } : {}),
+                    ...(target.apiKey ? { "X-API-Key": target.apiKey } : {}),
                 },
-                timeout: SEND_TIMEOUT_MS,
+                timeout: timeoutMs,
             }, (res) => {
-                res.on("data", () => { });
-                res.on("end", () => { clearTimeout(timeout); resolve(); });
-                res.on("close", () => { clearTimeout(timeout); resolve(); });
+                let chunks = "";
+                res.setEncoding("utf-8");
+                res.on("data", (d) => { chunks += d; });
+                res.on("end", () => {
+                    clearTimeout(timer);
+                    resolve({ status: res.statusCode ?? 0, body: chunks });
+                });
+                res.on("close", () => {
+                    clearTimeout(timer);
+                    resolve({ status: res.statusCode ?? 0, body: chunks });
+                });
             });
-            req.on("error", (err) => { clearTimeout(timeout); reject(err); });
-            req.on("timeout", () => { clearTimeout(timeout); req.destroy(); reject(new Error("collector: request timeout")); });
+            req.on("error", (err) => { clearTimeout(timer); reject(err); });
+            req.on("timeout", () => { clearTimeout(timer); req.destroy(); reject(new Error("collector: request timeout")); });
             req.write(body);
             req.end();
         }
         catch (e) {
-            logger_1.logger.debug(`collector: sendToCollector failed: ${e}`);
             reject(e instanceof Error ? e : new Error(String(e)));
         }
     });
 }
+/**
+ * Resolve the collector target from config, or `null` if disabled.
+ *
+ * Disabled when ANY of:
+ *   - `IRONBEE_COLLECTOR=false` env (jest harness escape hatch)
+ *   - no `collector` config section
+ *   - `collector.enable: false` explicitly set
+ *   - `collector.url` missing or empty
+ *
+ * Otherwise the section is treated as enabled (presence is the opt-in,
+ * symmetric with `jobQueue`). `apiKey` is optional — when absent, the
+ * `X-API-Key` header is simply omitted, allowing use against an
+ * auth-disabled collector.
+ */
+function getCollectorTarget(projectDir) {
+    if (process.env.IRONBEE_COLLECTOR === "false") {
+        return null;
+    }
+    const config = (0, config_1.loadConfig)(projectDir);
+    const section = config.collector;
+    if (!section) {
+        return null;
+    }
+    // explicit kill switch — keeps url/apiKey/batchSize in config so the user
+    // can flip back on without re-typing them
+    if (section.enable === false) {
+        return null;
+    }
+    if (typeof section.url !== "string" || section.url.length === 0) {
+        return null;
+    }
+    return {
+        url: section.url,
+        apiKey: section.apiKey,
+        batchSize: typeof section.batchSize === "number" ? section.batchSize : undefined,
+    };
+}
+/**
+ * Fire-and-forget single-event send. Resolves on any HTTP response (status is
+ * intentionally ignored so a 5xx from the collector does not propagate back
+ * into a hook that's writing to `actions.jsonl`). Rejects only on network
+ * / timeout errors.
+ *
+ * Emits a debug-level trace line per attempt to `session.log` (level filter
+ * does not gate file writes — see logger.ts) so operators can audit which
+ * lifecycle events made it to the collector. The line carries the event id
+ * and type to make grep'ing trivial; it does not include payload content.
+ */
+async function sendToCollector(entry, _sessionId, projectDir) {
+    const target = getCollectorTarget(projectDir);
+    if (!target) {
+        return;
+    }
+    const startedAt = Date.now();
+    try {
+        // entry is already enriched with id/session_id/project_name/timestamp by appendAction.
+        await postEventsBatch([entry], target, { timeoutMs: SEND_TIMEOUT_MS });
+        logger_1.logger.debug(`collector: posted type=${entry.type} id=${entry.id ?? "?"} in ${Date.now() - startedAt}ms`);
+    }
+    catch (e) {
+        logger_1.logger.debug(`collector: sendToCollector failed type=${entry.type} id=${entry.id ?? "?"}: ${e}`);
+        throw e instanceof Error ? e : new Error(String(e));
+    }
+}
 //# sourceMappingURL=collector.js.map

package/dist/lib/collector.js.map

@@ -1 +1 @@
-{"version":3,"file":"collector.js","sourceRoot":"","sources":["../../src/lib/collector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../../src/lib/collector.ts"],"names":[],"mappings":"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"}

package/dist/lib/config.d.ts

@@ -28,24 +28,68 @@ export interface IronBeeConfig {
     /** Maximum retry attempts before allowing completion despite failures. */
     maxRetries?: number;
     /**
-     * IronBee Collector configuration for remote event ingestion.
-     * When set, events are sent to the collector in addition to local storage.
+     * IronBee Collector configuration for remote event ingestion. When the
+     * section is present and `enable` is not explicitly `false`, events are
+     * sent to the collector in addition to local storage.
      */
     collector?: {
-        /** Collector base URL (e.g. "https://service.ironbee.dev") */
-        url: string;
+        /**
+         * Master switch. Defaults to `true` whenever this section is present,
+         * mirroring `jobQueue.enable`. Set explicitly to `false` to suspend
+         * the collector without removing `url` / `apiKey` / `batchSize` —
+         * useful for temporarily working offline while keeping the rest of
+         * the collector config around.
+         */
+        enable?: boolean;
+        /**
+         * Collector base URL (e.g. "https://service.ironbee.dev"). Required
+         * for `enable !== false`; the collector is treated as disabled when
+         * `url` is missing or empty.
+         */
+        url?: string;
         /** API key for authentication (X-API-Key header). Optional if auth is disabled on collector. */
         apiKey?: string;
+        /**
+         * Max events per POST in the queue's `send_event` handler. Jobs
+         * accumulated in a snapshot are chunked into batches of this size so
+         * the collector doesn't reject oversize bodies. Default 100.
+         * Set to a higher value if your collector tolerates big bodies.
+         */
+        batchSize?: number;
     };
     /**
-     * Recording configuration.
-     * When enabled, each verification cycle requires a browser recording
-     * (start-recording before browser tools, stop-recording before verdict).
+     * Recording enforcement configuration. When enabled, each verification
+     * cycle requires a browser recording (start-recording before browser
+     * tools, stop-recording before verdict).
+     *
+     * The presence of this section IS the opt-in signal — `"recording": {}`
+     * (or any sub-key) turns enforcement on. Set `enable: false` explicitly
+     * to disable while keeping the section around. Section absent → off.
+     * Symmetric with `jobQueue` and `collector`.
      */
     recording?: {
-        /** Enable recording enforcement. Default: false. */
         enable?: boolean;
     };
+    /**
+     * Job queue tuning. The presence of this section IS the opt-in signal —
+     * adding `"jobQueue": {}` (or any sub-key) enables the queue. To opt out
+     * after the section exists, set `enable: false` explicitly.
+     *
+     * `enable`: master switch. Defaults to `true` when this section is
+     * present, `false` when absent. Set explicitly to `false` to disable
+     * without removing the rest of the config (e.g. keep your custom
+     * `autoFlushSizeBytes` around for later).
+     *
+     * `autoFlushSizeBytes`: when the live `jobs.jsonl` size meets or exceeds
+     * this threshold after a submit, a detached worker is spawned in the
+     * background to snapshot and process it — providing mid-session flush
+     * without waiting for Stop / SessionEnd. Set to `0` (or a negative value)
+     * to disable size-based auto-flush. Default 32768 (32 KB).
+     */
+    jobQueue?: {
+        enable?: boolean;
+        autoFlushSizeBytes?: number;
+    };
     /** Allow additional config fields. */
     [key: string]: unknown;
 }
@@ -78,4 +122,24 @@ export interface BrowserDevToolsMCPConfig {
  */
 export declare function getMcpServerEntry(projectDir?: string): BrowserDevToolsMCPConfig;
 export declare function getMaxRetries(config: IronBeeConfig): number;
+/**
+ * Returns true when the job queue layer is enabled for this project.
+ *
+ * Rule:
+ *   - No `jobQueue` section in config → disabled (default-off).
+ *   - `jobQueue` section present → enabled, unless `enable: false` is set
+ *     explicitly. Adding any sub-key (e.g. `autoFlushSizeBytes`) implicitly
+ *     opts in.
+ *
+ * Used as both a producer-side gate (track-action skips wire construction
+ * when off) and a defense-in-depth guard inside `submit()` itself.
+ */
+export declare function isJobQueueEnabled(projectDir?: string): boolean;
+/**
+ * Returns true when recording enforcement is enabled for this project.
+ * Same presence-as-opt-in semantics as `isJobQueueEnabled`: the `recording`
+ * section being present in config.json turns enforcement on; set
+ * `enable: false` explicitly to suspend without removing the section.
+ */
+export declare function isRecordingEnabled(projectDir?: string): boolean;
 //# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE;QACR,8DAA8D;QAC9D,GAAG,EAAE,MAAM,CAAC;QACZ,gGAAgG;QAChG,MAAM,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IAEF;;;;OAIG;IACH,SAAS,CAAC,EAAE;QACR,oDAAoD;QACpD,MAAM,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IAEF,sCAAsC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AA6CD,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAiB7D;AAyCD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAarF;AAED,MAAM,WAAW,wBAAwB;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,wBAAwB,CAuC/E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAI3D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE;QACR;;;;;;WAMG;QACH,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB;;;;WAIG;QACH,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,gGAAgG;QAChG,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;;;;WAKG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IAEF;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;IAEF,sCAAsC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AA6CD,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAiB7D;AAyCD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAarF;AAED,MAAM,WAAW,wBAAwB;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,wBAAwB,CAuC/E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAI3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAG/D"}

package/dist/lib/config.js

@@ -13,6 +13,8 @@ exports.loadConfig = loadConfig;
 exports.requiresVerification = requiresVerification;
 exports.getMcpServerEntry = getMcpServerEntry;
 exports.getMaxRetries = getMaxRetries;
+exports.isJobQueueEnabled = isJobQueueEnabled;
+exports.isRecordingEnabled = isRecordingEnabled;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
@@ -191,4 +193,42 @@ function getMaxRetries(config) {
         ? config.maxRetries
         : DEFAULT_MAX_RETRIES;
 }
+/**
+ * Returns true when the job queue layer is enabled for this project.
+ *
+ * Rule:
+ *   - No `jobQueue` section in config → disabled (default-off).
+ *   - `jobQueue` section present → enabled, unless `enable: false` is set
+ *     explicitly. Adding any sub-key (e.g. `autoFlushSizeBytes`) implicitly
+ *     opts in.
+ *
+ * Used as both a producer-side gate (track-action skips wire construction
+ * when off) and a defense-in-depth guard inside `submit()` itself.
+ */
+function isJobQueueEnabled(projectDir) {
+    const config = loadConfig(projectDir);
+    return isPresenceEnabled(config.jobQueue);
+}
+/**
+ * Returns true when recording enforcement is enabled for this project.
+ * Same presence-as-opt-in semantics as `isJobQueueEnabled`: the `recording`
+ * section being present in config.json turns enforcement on; set
+ * `enable: false` explicitly to suspend without removing the section.
+ */
+function isRecordingEnabled(projectDir) {
+    const config = loadConfig(projectDir);
+    return isPresenceEnabled(config.recording);
+}
+/**
+ * Shared "section present + not explicitly disabled" check used by the
+ * three master-switch helpers (`jobQueue`, `recording`, and inline by
+ * `getCollectorTarget`). Defensive against malformed config values
+ * (null / non-object / array) — those are treated as disabled.
+ */
+function isPresenceEnabled(section) {
+    if (section === undefined || section === null || typeof section !== "object" || Array.isArray(section)) {
+        return false;
+    }
+    return section.enable !== false;
+}
 //# sourceMappingURL=config.js.map

package/dist/lib/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}

package/dist/queue/dead-letter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * IronBee CLI — Dead Letter Writer + Rotation
+ *
+ * See docs/job-queue.md §6.1 (entry shape), §6.2 (rotation + retention).
+ */
+import { DeadLetterEntry, Job } from "./types";
+export interface DeadLetterInput {
+    projectDir: string;
+    sessionId: string;
+    sourceFile: string;
+}
+/**
+ * Append a parsed-job dead-letter entry. Enforces the 4 KB line ceiling via a
+ * cascade of three truncation fallbacks. The last fallback always fits — it
+ * replaces the entire entry with a minimal overflow marker — so the atomic
+ * append invariant (§6.1) always holds.
+ */
+export declare function deadLetterParsed(input: DeadLetterInput, job: Job, category: string): void;
+/**
+ * Append a parse-error dead-letter entry. The raw line is truncated to 512
+ * chars and ASCII control chars are escaped.
+ */
+export declare function deadLetterParseError(input: DeadLetterInput, raw: string, category: string): void;
+/** Exposed for tests and CLI tooling. */
+export declare function readDeadLetterEntries(projectDir: string, sessionId: string): DeadLetterEntry[];
+//# sourceMappingURL=dead-letter.d.ts.map

package/dist/queue/dead-letter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter.d.ts","sourceRoot":"","sources":["../../src/queue/dead-letter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,OAAO,EAIH,eAAe,EAGf,GAAG,EAEN,MAAM,SAAS,CAAC;AAGjB,MAAM,WAAW,eAAe;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CA4DzF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYhG;AAyHD,yCAAyC;AACzC,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAoB9F"}

package/dist/queue/dead-letter.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * IronBee CLI — Dead Letter Writer + Rotation
+ *
+ * See docs/job-queue.md §6.1 (entry shape), §6.2 (rotation + retention).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deadLetterParsed = deadLetterParsed;
+exports.deadLetterParseError = deadLetterParseError;
+exports.readDeadLetterEntries = readDeadLetterEntries;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const logger_1 = require("../lib/logger");
+const types_1 = require("./types");
+const paths_1 = require("./paths");
+/**
+ * Append a parsed-job dead-letter entry. Enforces the 4 KB line ceiling via a
+ * cascade of three truncation fallbacks. The last fallback always fits — it
+ * replaces the entire entry with a minimal overflow marker — so the atomic
+ * append invariant (§6.1) always holds.
+ */
+function deadLetterParsed(input, job, category) {
+    const filename = (0, path_1.basename)(input.sourceFile);
+    const receivedAt = new Date().toISOString();
+    const entryId = (0, crypto_1.randomUUID)();
+    // Fallback 0: the happy case — full entry.
+    let entry = {
+        id: entryId,
+        received_at: receivedAt,
+        source_file: filename,
+        category,
+        original: job,
+    };
+    let line = JSON.stringify(entry) + "\n";
+    if (Buffer.byteLength(line, "utf-8") > types_1.MAX_LINE_BYTES) {
+        // Fallback 1: drop `original.data`.
+        entry = {
+            ...entry,
+            original: {
+                id: job.id,
+                type: job.type,
+                created_at: job.created_at,
+                data: { __truncated__: true },
+            },
+        };
+        line = JSON.stringify(entry) + "\n";
+    }
+    if (Buffer.byteLength(line, "utf-8") > types_1.MAX_LINE_BYTES) {
+        // Fallback 2: also truncate the category string.
+        entry = {
+            ...entry,
+            category: truncateString(category, 256),
+        };
+        line = JSON.stringify(entry) + "\n";
+    }
+    if (Buffer.byteLength(line, "utf-8") > types_1.MAX_LINE_BYTES) {
+        // Fallback 3: minimal overflow marker. Preserves identity + triage
+        // pointer (job id, source_file) but drops everything else.
+        const minimal = {
+            id: entryId,
+            received_at: receivedAt,
+            source_file: truncateString(filename, 128),
+            category: "overflow",
+            original: { id: job.id, type: truncateString(job.type, 64) },
+            __truncated__: true,
+        };
+        line = JSON.stringify(minimal) + "\n";
+        // Absolute last resort — if even this exceeds 4 KB (which would
+        // require a pathologically long source_file name the OS likely
+        // rejected anyway), hard-truncate the byte array and append a "\n".
+        if (Buffer.byteLength(line, "utf-8") > types_1.MAX_LINE_BYTES) {
+            const raw = Buffer.from(line, "utf-8").subarray(0, types_1.MAX_LINE_BYTES - 1);
+            line = raw.toString("utf-8") + "\n";
+        }
+    }
+    writeDeadLetterLine(input.projectDir, input.sessionId, line);
+}
+/**
+ * Append a parse-error dead-letter entry. The raw line is truncated to 512
+ * chars and ASCII control chars are escaped.
+ */
+function deadLetterParseError(input, raw, category) {
+    const filename = (0, path_1.basename)(input.sourceFile);
+    const sanitized = escapeControls(raw).slice(0, types_1.DEAD_LETTER_RAW_MAX);
+    const entry = {
+        id: (0, crypto_1.randomUUID)(),
+        received_at: new Date().toISOString(),
+        source_file: filename,
+        category,
+        raw: sanitized,
+    };
+    const line = JSON.stringify(entry) + "\n";
+    writeDeadLetterLine(input.projectDir, input.sessionId, line);
+}
+function writeDeadLetterLine(projectDir, sessionId, line) {
+    const dir = (0, paths_1.queueDir)(projectDir, sessionId);
+    (0, fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    const path = (0, paths_1.deadLetterFile)(projectDir, sessionId);
+    const flags = fs_1.constants.O_CREAT
+        | fs_1.constants.O_WRONLY
+        | fs_1.constants.O_APPEND
+        | (typeof fs_1.constants.O_NOFOLLOW === "number" ? fs_1.constants.O_NOFOLLOW : 0);
+    const fd = (0, fs_1.openSync)(path, flags, 0o600);
+    try {
+        const bytes = Buffer.from(line, "utf-8");
+        (0, fs_1.writeSync)(fd, bytes, 0, bytes.length);
+    }
+    finally {
+        try {
+            (0, fs_1.closeSync)(fd);
+        }
+        catch {
+            // ignore
+        }
+    }
+    rotateIfNeeded(projectDir, sessionId);
+}
+function rotateIfNeeded(projectDir, sessionId) {
+    // Size-only rotation — `stat()` is O(1), appends stay sub-ms even with a
+    // near-threshold file. A line-count check would require reading the whole
+    // file on every append, which defeats the purpose of append-only writes.
+    // Practical dead-letter entries are 400–1500 bytes, so 10 MB naturally
+    // bounds line count to ~7k–25k.
+    const path = (0, paths_1.deadLetterFile)(projectDir, sessionId);
+    let size;
+    try {
+        size = (0, fs_1.statSync)(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= types_1.DEAD_LETTER_ROTATE_BYTES) {
+        return;
+    }
+    const dir = (0, paths_1.queueDir)(projectDir, sessionId);
+    const rotated = (0, path_1.join)(dir, `dead-letter-${(0, crypto_1.randomUUID)()}.jsonl`);
+    try {
+        (0, fs_1.renameSync)(path, rotated);
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT") {
+            // another worker already rotated; nothing to do
+            return;
+        }
+        // Keep the writer robust — non-ENOENT failure (EACCES, EIO, EXDEV, …)
+        // means the dead-letter file keeps growing past the 10 MB target
+        // until the cause is fixed. Surface via debug so the operator has a
+        // trace to follow instead of a silent slow-grow.
+        logger_1.logger.debug(`dead-letter rotation failed on ${path}: ${err.code ?? err.message}`);
+        return;
+    }
+    enforceRetention(projectDir, sessionId);
+}
+function enforceRetention(projectDir, sessionId) {
+    const dir = (0, paths_1.queueDir)(projectDir, sessionId);
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(dir);
+    }
+    catch {
+        return;
+    }
+    const rotated = [];
+    for (const name of entries) {
+        if (!paths_1.DEAD_LETTER_ROTATED_REGEX.test(name)) {
+            continue;
+        }
+        const full = (0, path_1.join)(dir, name);
+        try {
+            const st = (0, fs_1.statSync)(full);
+            rotated.push({ path: full, mtimeMs: st.mtimeMs });
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (rotated.length <= types_1.DEAD_LETTER_RETAIN_COUNT) {
+        return;
+    }
+    // sort newest first; unlink anything past the keep count
+    rotated.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (let i = types_1.DEAD_LETTER_RETAIN_COUNT; i < rotated.length; i++) {
+        try {
+            (0, fs_1.unlinkSync)(rotated[i].path);
+        }
+        catch {
+            // ignore — best-effort
+        }
+    }
+}
+function escapeControls(s) {
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f) {
+            out += `\\x${code.toString(16).padStart(2, "0")}`;
+        }
+        else {
+            out += s[i];
+        }
+    }
+    return out;
+}
+function truncateString(s, max) {
+    return s.length <= max ? s : s.slice(0, max) + "…";
+}
+/** Exposed for tests and CLI tooling. */
+function readDeadLetterEntries(projectDir, sessionId) {
+    const path = (0, paths_1.deadLetterFile)(projectDir, sessionId);
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(path, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of content.split("\n")) {
+        if (line.length === 0) {
+            continue;
+        }
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // skip unparseable dead-letter lines — shouldn't happen in practice
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=dead-letter.js.map