@ironbee-ai/cli 0.5.2 → 0.6.0

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

package/dist/queue/dead-letter.js.map

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

package/dist/queue/drain.d.ts

@@ -0,0 +1,36 @@
+/**
+ * IronBee CLI — Queue drain()
+ *
+ * See docs/job-queue.md §5.4. Synchronous per-session final-flush.
+ * Cleanup touches ONLY the queue/ subdir — never the parent session dir,
+ * which is owned by the consumer (actions.jsonl, verdict.json, …).
+ */
+import { HandlerRegistry } from "./registry";
+export interface DrainOptions {
+    registry?: HandlerRegistry;
+    /**
+     * Skip snapshot files whose mtime is within the last `skipRecentMs`
+     * milliseconds. Used by `flushSynchronously` at SessionEnd to avoid
+     * racing with a detached worker that was just spawned by a Stop-class
+     * hook (§7.3). Operator-facing `ironbee queue drain` leaves this at 0
+     * so it catches every snapshot, including those from a just-crashed
+     * worker. Default 0.
+     */
+    skipRecentMs?: number;
+}
+export interface DrainResult {
+    snapshotsProcessed: number;
+    snapshotsRemaining: number;
+    cleanedQueueDir: boolean;
+    /** Snapshots that were skipped because they are too recent (see DrainOptions.skipRecentMs). */
+    snapshotsSkippedRecent: number;
+}
+/**
+ * Drain one session synchronously:
+ *   1. Roll the live file (if any) into a snapshot.
+ *   2. Process every snapshot in sorted order.
+ *   3. Best-effort cleanup of the queue/ dir if fully empty of undelivered
+ *      work and triage records.
+ */
+export declare function drain(projectDir: string, sessionId: string, opts?: DrainOptions): Promise<DrainResult>;
+//# sourceMappingURL=drain.d.ts.map

package/dist/queue/drain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../../src/queue/drain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,OAAO,CAAC;IACzB,+FAA+F;IAC/F,sBAAsB,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA2C5G"}

package/dist/queue/drain.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * IronBee CLI — Queue drain()
+ *
+ * See docs/job-queue.md §5.4. Synchronous per-session final-flush.
+ * Cleanup touches ONLY the queue/ subdir — never the parent session dir,
+ * which is owned by the consumer (actions.jsonl, verdict.json, …).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.drain = drain;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const snapshot_1 = require("./snapshot");
+const process_file_1 = require("./process-file");
+const paths_1 = require("./paths");
+/**
+ * Drain one session synchronously:
+ *   1. Roll the live file (if any) into a snapshot.
+ *   2. Process every snapshot in sorted order.
+ *   3. Best-effort cleanup of the queue/ dir if fully empty of undelivered
+ *      work and triage records.
+ */
+async function drain(projectDir, sessionId, opts) {
+    (0, paths_1.validateSessionId)(sessionId);
+    const dir = (0, paths_1.queueDir)(projectDir, sessionId);
+    const result = {
+        snapshotsProcessed: 0,
+        snapshotsRemaining: 0,
+        cleanedQueueDir: false,
+        snapshotsSkippedRecent: 0,
+    };
+    if (!(0, fs_1.existsSync)(dir)) {
+        return result;
+    }
+    const skipRecentMs = opts?.skipRecentMs ?? 0;
+    // Step 3 of §5.4: roll live file into a snapshot if it exists. This
+    // freshly-renamed snapshot has a brand-new mtime, so skipRecentMs would
+    // exclude it. Remember its path (if any) and force-process it below.
+    let justRolled = null;
+    try {
+        justRolled = (0, snapshot_1.snapshot)(projectDir, sessionId);
+    }
+    catch {
+        // snapshot() already returns null on ENOENT; any other failure bubbles
+        // into the glob below which will skip it. Keep drain() fault-tolerant.
+    }
+    // Step 4: process every snapshot.
+    const { eligible, skipped } = listSnapshots(dir, skipRecentMs, justRolled);
+    result.snapshotsSkippedRecent = skipped;
+    for (const snap of eligible) {
+        try {
+            await (0, process_file_1.processFile)(snap, { registry: opts?.registry });
+            result.snapshotsProcessed++;
+        }
+        catch {
+            // processFile never throws in normal paths, but be defensive
+        }
+    }
+    // Step 5: cleanup — strictly queue/ only; never the session dir.
+    result.snapshotsRemaining = listSnapshots(dir, 0, null).eligible.length;
+    result.cleanedQueueDir = tryCleanupQueueDir(projectDir, sessionId);
+    return result;
+}
+/**
+ * Enumerate snapshot files under `dir`, filtering out those touched within
+ * `skipRecentMs` unless they match `forceInclude` (the path we just rolled
+ * this drain cycle — it always needs processing even if its mtime is fresh).
+ */
+function listSnapshots(dir, skipRecentMs, forceInclude) {
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(dir);
+    }
+    catch {
+        return { eligible: [], skipped: 0 };
+    }
+    const now = Date.now();
+    const eligible = [];
+    let skipped = 0;
+    for (const name of entries) {
+        if (!paths_1.SNAPSHOT_FILENAME_REGEX.test(name)) {
+            continue;
+        }
+        const full = (0, path_1.join)(dir, name);
+        if (forceInclude !== null && full === forceInclude) {
+            eligible.push(full);
+            continue;
+        }
+        if (skipRecentMs > 0) {
+            try {
+                const mtime = (0, fs_1.statSync)(full).mtimeMs;
+                if (now - mtime < skipRecentMs) {
+                    skipped++;
+                    continue;
+                }
+            }
+            catch {
+                // stat failed — include and let processFile handle it
+            }
+        }
+        eligible.push(full);
+    }
+    eligible.sort();
+    return { eligible, skipped };
+}
+/**
+ * Remove worker.log and empty dead-letter.jsonl, then rmdir queue/ — but
+ * only if no undelivered work or non-empty triage record remains.
+ * The session directory itself is owned by the consumer; never touched.
+ */
+function tryCleanupQueueDir(projectDir, sessionId) {
+    const dir = (0, paths_1.queueDir)(projectDir, sessionId);
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(dir);
+    }
+    catch {
+        return false;
+    }
+    // Any undelivered snapshot, any live file, or any non-empty dead-letter
+    // content blocks cleanup.
+    for (const name of entries) {
+        if (name === "jobs.jsonl") {
+            if (fileSize((0, path_1.join)(dir, name)) > 0) {
+                return false;
+            }
+        }
+        if (paths_1.SNAPSHOT_FILENAME_REGEX.test(name)) {
+            return false;
+        }
+        if (name === "dead-letter.jsonl" || paths_1.DEAD_LETTER_ROTATED_REGEX.test(name)) {
+            if (fileSize((0, path_1.join)(dir, name)) > 0) {
+                return false;
+            }
+        }
+    }
+    // Safe to cleanup. Remove discardable files first.
+    for (const name of entries) {
+        if (name === "jobs.jsonl"
+            || name === "dead-letter.jsonl"
+            || paths_1.DEAD_LETTER_ROTATED_REGEX.test(name)
+            || name === "worker.log"
+            || paths_1.WORKER_LOG_ROTATED_REGEX.test(name)) {
+            try {
+                (0, fs_1.unlinkSync)((0, path_1.join)(dir, name));
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    // Attempt rmdir queue/ — fails silently if other (unknown) files remain,
+    // which is the safe thing to do.
+    try {
+        (0, fs_1.rmdirSync)(dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function fileSize(path) {
+    try {
+        return (0, fs_1.statSync)(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=drain.js.map

package/dist/queue/drain.js.map

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

package/dist/queue/flush.d.ts

@@ -0,0 +1,64 @@
+/**
+ * IronBee CLI — Queue flush helpers
+ *
+ * Per-session flush triggers for consumer hooks. Two modes, to be chosen per
+ * §5.6 of docs/job-queue.md:
+ *
+ *   - flushInBackground()  — used by Stop-class hooks (active session).
+ *                            snapshot() the live file and fire-and-forget a
+ *                            detached worker on it. Returns in <10 ms.
+ *
+ *   - flushSynchronously() — used by SessionEnd-class hooks (consumer is
+ *                            about to exit). Synchronously drain() every
+ *                            snapshot. May block for milliseconds to low
+ *                            seconds.
+ *
+ * Both helpers are fail-safe: any thrown error is swallowed and debug-logged
+ * so a queue fault cannot break the hook.
+ */
+import { DrainOptions, DrainResult } from "./drain";
+/** Default threshold for `maybeAutoFlush` when unset in config (32 KB). */
+export declare const DEFAULT_AUTO_FLUSH_SIZE_BYTES: number;
+/**
+ * Stop-class hooks use this: snapshot the live queue and launch a detached
+ * worker. The caller's process may exit immediately after — the worker's
+ * `child.unref()` detaches it from the parent's event loop and process group
+ * to the extent the platform allows.
+ *
+ * Behaviour when queue has no work: snapshot() returns null (no live file),
+ * no worker spawned. No-op when the queue module has no producer yet.
+ */
+export declare function flushInBackground(projectDir: string, sessionId: string): void;
+/**
+ * Producer-side auto-flush trigger. Called from `submit()` after a successful
+ * append. If the live `jobs.jsonl` has grown to at least the configured
+ * threshold (`jobQueue.autoFlushSizeBytes`, default 32 KB), snapshot it and
+ * spawn a detached worker in the background — same mechanism as a Stop hook,
+ * just triggered mid-session by queue growth instead of by a lifecycle event.
+ *
+ * Complements Stop / SessionEnd flushes: provides checkpointing for turns
+ * that emit many tool_call events (so collector sees them sooner) and caps
+ * worst-case live file size on abandoned sessions.
+ *
+ * Fail-safe: config read errors, stat failures, and flushInBackground
+ * exceptions are all swallowed so a queue fault can never break submit().
+ *
+ * Threshold <= 0 disables the feature (only lifecycle flushes remain).
+ */
+export declare function maybeAutoFlush(projectDir: string, sessionId: string): void;
+/** Default recent-skip window used by `flushSynchronously` (see §7.3). */
+export declare const SESSION_END_SKIP_RECENT_MS: number;
+/**
+ * SessionEnd-class hooks use this: synchronously drain every snapshot for the
+ * session, then (if possible) clean up the queue/ subdir. Consumer owns the
+ * session dir itself — drain never touches anything outside queue/.
+ *
+ * By default skips snapshot files modified in the last 2 seconds — this is
+ * the "in-flight detached worker" window opened by a Stop hook firing right
+ * before SessionEnd (§7.3). Override with `opts.skipRecentMs = 0` if you
+ * want to treat recent snapshots as orphans (e.g. from tests). Skipped
+ * snapshots remain on disk and are drained by the next `ironbee queue drain`
+ * invocation.
+ */
+export declare function flushSynchronously(projectDir: string, sessionId: string, opts?: DrainOptions): Promise<DrainResult>;
+//# sourceMappingURL=flush.d.ts.map

package/dist/queue/flush.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/queue/flush.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAS,MAAM,SAAS,CAAC;AAK3D,2EAA2E;AAC3E,eAAO,MAAM,6BAA6B,EAAE,MAAkB,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAU7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAkB1E;AAED,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,EAAE,MAAa,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,WAAW,CAAC,CAYtB"}

package/dist/queue/flush.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * IronBee CLI — Queue flush helpers
+ *
+ * Per-session flush triggers for consumer hooks. Two modes, to be chosen per
+ * §5.6 of docs/job-queue.md:
+ *
+ *   - flushInBackground()  — used by Stop-class hooks (active session).
+ *                            snapshot() the live file and fire-and-forget a
+ *                            detached worker on it. Returns in <10 ms.
+ *
+ *   - flushSynchronously() — used by SessionEnd-class hooks (consumer is
+ *                            about to exit). Synchronously drain() every
+ *                            snapshot. May block for milliseconds to low
+ *                            seconds.
+ *
+ * Both helpers are fail-safe: any thrown error is swallowed and debug-logged
+ * so a queue fault cannot break the hook.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_END_SKIP_RECENT_MS = exports.DEFAULT_AUTO_FLUSH_SIZE_BYTES = void 0;
+exports.flushInBackground = flushInBackground;
+exports.maybeAutoFlush = maybeAutoFlush;
+exports.flushSynchronously = flushSynchronously;
+const fs_1 = require("fs");
+const config_1 = require("../lib/config");
+const logger_1 = require("../lib/logger");
+const drain_1 = require("./drain");
+const paths_1 = require("./paths");
+const snapshot_1 = require("./snapshot");
+const spawn_1 = require("./spawn");
+/** Default threshold for `maybeAutoFlush` when unset in config (32 KB). */
+exports.DEFAULT_AUTO_FLUSH_SIZE_BYTES = 32 * 1024;
+/**
+ * Stop-class hooks use this: snapshot the live queue and launch a detached
+ * worker. The caller's process may exit immediately after — the worker's
+ * `child.unref()` detaches it from the parent's event loop and process group
+ * to the extent the platform allows.
+ *
+ * Behaviour when queue has no work: snapshot() returns null (no live file),
+ * no worker spawned. No-op when the queue module has no producer yet.
+ */
+function flushInBackground(projectDir, sessionId) {
+    try {
+        (0, paths_1.validateSessionId)(sessionId);
+        const snap = (0, snapshot_1.snapshot)(projectDir, sessionId);
+        if (snap !== null) {
+            (0, spawn_1.spawnDetachedWorker)(snap);
+        }
+    }
+    catch (e) {
+        logger_1.logger.debug(`queue flushInBackground failed: ${e instanceof Error ? e.message : e}`);
+    }
+}
+/**
+ * Producer-side auto-flush trigger. Called from `submit()` after a successful
+ * append. If the live `jobs.jsonl` has grown to at least the configured
+ * threshold (`jobQueue.autoFlushSizeBytes`, default 32 KB), snapshot it and
+ * spawn a detached worker in the background — same mechanism as a Stop hook,
+ * just triggered mid-session by queue growth instead of by a lifecycle event.
+ *
+ * Complements Stop / SessionEnd flushes: provides checkpointing for turns
+ * that emit many tool_call events (so collector sees them sooner) and caps
+ * worst-case live file size on abandoned sessions.
+ *
+ * Fail-safe: config read errors, stat failures, and flushInBackground
+ * exceptions are all swallowed so a queue fault can never break submit().
+ *
+ * Threshold <= 0 disables the feature (only lifecycle flushes remain).
+ */
+function maybeAutoFlush(projectDir, sessionId) {
+    try {
+        const config = (0, config_1.loadConfig)(projectDir);
+        const raw = config.jobQueue?.autoFlushSizeBytes;
+        const threshold = typeof raw === "number" ? raw : exports.DEFAULT_AUTO_FLUSH_SIZE_BYTES;
+        if (threshold <= 0) {
+            return;
+        }
+        const livePath = (0, paths_1.liveQueueFile)(projectDir, sessionId);
+        const size = (0, fs_1.statSync)(livePath).size;
+        if (size >= threshold) {
+            flushInBackground(projectDir, sessionId);
+        }
+    }
+    catch (e) {
+        // ENOENT on stat (file rolled between submit and stat) or any other
+        // fault must not propagate — submit() already persisted the line.
+        logger_1.logger.debug(`queue maybeAutoFlush skipped: ${e instanceof Error ? e.message : e}`);
+    }
+}
+/** Default recent-skip window used by `flushSynchronously` (see §7.3). */
+exports.SESSION_END_SKIP_RECENT_MS = 2000;
+/**
+ * SessionEnd-class hooks use this: synchronously drain every snapshot for the
+ * session, then (if possible) clean up the queue/ subdir. Consumer owns the
+ * session dir itself — drain never touches anything outside queue/.
+ *
+ * By default skips snapshot files modified in the last 2 seconds — this is
+ * the "in-flight detached worker" window opened by a Stop hook firing right
+ * before SessionEnd (§7.3). Override with `opts.skipRecentMs = 0` if you
+ * want to treat recent snapshots as orphans (e.g. from tests). Skipped
+ * snapshots remain on disk and are drained by the next `ironbee queue drain`
+ * invocation.
+ */
+async function flushSynchronously(projectDir, sessionId, opts) {
+    try {
+        (0, paths_1.validateSessionId)(sessionId);
+        const merged = {
+            ...opts,
+            skipRecentMs: opts?.skipRecentMs ?? exports.SESSION_END_SKIP_RECENT_MS,
+        };
+        return await (0, drain_1.drain)(projectDir, sessionId, merged);
+    }
+    catch (e) {
+        logger_1.logger.debug(`queue flushSynchronously failed: ${e instanceof Error ? e.message : e}`);
+        return { snapshotsProcessed: 0, snapshotsRemaining: 0, cleanedQueueDir: false, snapshotsSkippedRecent: 0 };
+    }
+}
+//# sourceMappingURL=flush.js.map

package/dist/queue/flush.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush.js","sourceRoot":"","sources":["../../src/queue/flush.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAsBH,8CAUC;AAkBD,wCAkBC;AAiBD,gDAgBC;AAnGD,2BAA8B;AAC9B,0CAA0D;AAC1D,0CAAuC;AACvC,mCAA2D;AAC3D,mCAA2D;AAC3D,yCAAsC;AACtC,mCAA8C;AAE9C,2EAA2E;AAC9D,QAAA,6BAA6B,GAAW,EAAE,GAAG,IAAI,CAAC;AAE/D;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAAC,UAAkB,EAAE,SAAiB;IACnE,IAAI,CAAC;QACD,IAAA,yBAAiB,EAAC,SAAS,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAkB,IAAA,mBAAQ,EAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAC5D,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAChB,IAAA,2BAAmB,EAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACL,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,eAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1F,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,cAAc,CAAC,UAAkB,EAAE,SAAiB;IAChE,IAAI,CAAC;QACD,MAAM,MAAM,GAAkB,IAAA,mBAAU,EAAC,UAAU,CAAC,CAAC;QACrD,MAAM,GAAG,GAAuB,MAAM,CAAC,QAAQ,EAAE,kBAAkB,CAAC;QACpE,MAAM,SAAS,GAAW,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,qCAA6B,CAAC;QACxF,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YACjB,OAAO;QACX,CAAC;QACD,MAAM,QAAQ,GAAW,IAAA,qBAAa,EAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAW,IAAA,aAAQ,EAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;QAC7C,IAAI,IAAI,IAAI,SAAS,EAAE,CAAC;YACpB,iBAAiB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAC7C,CAAC;IACL,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,oEAAoE;QACpE,kEAAkE;QAClE,eAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC;AACL,CAAC;AAED,0EAA0E;AAC7D,QAAA,0BAA0B,GAAW,IAAI,CAAC;AAEvD;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,kBAAkB,CACpC,UAAkB,EAClB,SAAiB,EACjB,IAAmB;IAEnB,IAAI,CAAC;QACD,IAAA,yBAAiB,EAAC,SAAS,CAAC,CAAC;QAC7B,MAAM,MAAM,GAAiB;YACzB,GAAG,IAAI;YACP,YAAY,EAAE,IAAI,EAAE,YAAY,IAAI,kCAA0B;SACjE,CAAC;QACF,OAAO,MAAM,IAAA,aAAK,EAAC,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,eAAM,CAAC,KAAK,CAAC,oCAAoC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvF,OAAO,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC,EAAE,CAAC;IAC/G,CAAC;AACL,CAAC"}