ima2-gen 3.13.1 → 3.14.0

package/lib/grokVideoDownload.js

@@ -14,47 +14,150 @@ function withTimeoutSignal(signal, timeoutMs) {
 export function isMp4Container(buffer) {
     return buffer.length >= 12 && buffer.subarray(4, 8).toString("ascii") === "ftyp";
 }
-export async function downloadVideo(ctx, url, signal) {
-    const { combinedSignal, timer } = withTimeoutSignal(signal, downloadTimeoutMs(ctx));
+function videoDownloadFailure(message) {
+    return grokError(message, 502, "GROK_VIDEO_DOWNLOAD_FAILED");
+}
+function assertVideoDownloadUrl(url) {
+    const parsed = new URL(url);
+    const isLoopback = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLoopback)) {
+        throw videoDownloadFailure("Grok video download URL must be HTTPS");
+    }
+}
+function assertDeclaredVideoLength(res, maxBytes) {
+    const contentLength = Number(res.headers.get("content-length") || "0");
+    if (contentLength > maxBytes) {
+        throw videoDownloadFailure("Grok video download exceeds the 100MB limit");
+    }
+}
+function videoDownloadContentType(res) {
+    if (!res.ok)
+        throw videoDownloadFailure(`Grok video download failed: HTTP ${res.status}`);
+    assertDeclaredVideoLength(res, MAX_VIDEO_DOWNLOAD_BYTES);
+    const contentType = res.headers.get("content-type") || "video/mp4";
+    if (!/^video\/mp4\b/i.test(contentType) && !/^application\/octet-stream\b/i.test(contentType)) {
+        throw videoDownloadFailure("Grok video download returned a non-video response");
+    }
+    return contentType;
+}
+function cancelVideoBodyBestEffort(target) {
     try {
-        const parsed = new URL(url);
-        const isLoopback = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
-        if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLoopback)) {
-            throw grokError("Grok video download URL must be HTTPS", 502, "GROK_VIDEO_DOWNLOAD_FAILED");
-        }
-        // Safe to replay: downloading a finished artifact creates nothing upstream.
-        const res = await grokFetchWithRetry(() => fetch(url, { signal: combinedSignal }), { signal: combinedSignal, label: "video-download" });
-        if (!res.ok)
-            throw grokError(`Grok video download failed: HTTP ${res.status}`, 502, "GROK_VIDEO_DOWNLOAD_FAILED");
-        const contentLength = Number(res.headers.get("content-length") || "0");
-        if (contentLength > MAX_VIDEO_DOWNLOAD_BYTES) {
-            throw grokError("Grok video download exceeds the 100MB limit", 502, "GROK_VIDEO_DOWNLOAD_FAILED");
+        const cancellation = target?.cancel("video download rejected");
+        if (cancellation)
+            void cancellation.catch(() => { });
+    }
+    catch {
+        // Cleanup must neither replace the original failure nor delay settlement.
+    }
+}
+async function readVideoChunk(reader, signal) {
+    signal.throwIfAborted();
+    let onAbort = () => { };
+    try {
+        const aborted = new Promise((_resolve, reject) => {
+            onAbort = () => reject(signal.reason);
+            signal.addEventListener("abort", onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
+        });
+        return await Promise.race([reader.read(), aborted]);
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+    }
+}
+/** Internal byte-limit seam; public download callers always use the fixed cap. */
+export async function readVideoDownloadBody(res, signal, maxBytes = MAX_VIDEO_DOWNLOAD_BYTES) {
+    let reader;
+    const chunks = [];
+    const prefix = Buffer.alloc(12);
+    let total = 0;
+    let complete = false;
+    try {
+        signal.throwIfAborted();
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_VIDEO_DOWNLOAD_BYTES) {
+            throw new RangeError("Invalid internal video byte limit");
         }
-        const contentType = res.headers.get("content-type") || "video/mp4";
-        if (!/^video\/mp4\b/i.test(contentType) && !/^application\/octet-stream\b/i.test(contentType)) {
-            throw grokError("Grok video download returned a non-video response", 502, "GROK_VIDEO_DOWNLOAD_FAILED");
+        assertDeclaredVideoLength(res, maxBytes);
+        if (!res.body)
+            throw videoDownloadFailure("Grok video download was empty");
+        reader = res.body.getReader();
+        while (true) {
+            const { done, value } = await readVideoChunk(reader, signal);
+            signal.throwIfAborted();
+            if (done)
+                break;
+            if (value.byteLength > maxBytes - total) {
+                throw videoDownloadFailure("Grok video download exceeds the 100MB limit");
+            }
+            if (value.byteLength === 0)
+                continue;
+            const chunk = Buffer.from(value);
+            if (total < 12)
+                chunk.copy(prefix, total, 0, Math.min(chunk.length, 12 - total));
+            total += chunk.byteLength;
+            chunks.push(chunk);
         }
-        const buffer = Buffer.from(await res.arrayBuffer());
-        clearTimeout(timer);
-        if (buffer.length === 0)
-            throw grokError("Grok video download was empty", 502, "GROK_VIDEO_DOWNLOAD_FAILED");
-        if (buffer.length > MAX_VIDEO_DOWNLOAD_BYTES) {
-            throw grokError("Grok video download exceeds the 100MB limit", 502, "GROK_VIDEO_DOWNLOAD_FAILED");
+        if (total === 0)
+            throw videoDownloadFailure("Grok video download was empty");
+        if (!isMp4Container(prefix.subarray(0, Math.min(total, 12)))) {
+            throw videoDownloadFailure("Grok video download returned an invalid MP4 container");
         }
-        if (!isMp4Container(buffer)) {
-            throw grokError("Grok video download returned an invalid MP4 container", 502, "GROK_VIDEO_DOWNLOAD_FAILED");
+        signal.throwIfAborted();
+        const buffer = Buffer.concat(chunks, total);
+        complete = true;
+        return buffer;
+    }
+    finally {
+        chunks.length = 0;
+        if (!complete)
+            cancelVideoBodyBestEffort(reader ?? res.body);
+        try {
+            reader?.releaseLock();
         }
+        catch { /* Preserve the original result. */ }
+    }
+}
+function mapVideoDownloadError(error, caller, combined) {
+    if (caller?.aborted)
+        return grokError("Generation canceled", 499, "GENERATION_CANCELED");
+    if (combined.aborted)
+        return grokError("Grok video download timed out", 504, "GROK_VIDEO_TIMEOUT");
+    const fields = error !== null && (typeof error === "object" || typeof error === "function")
+        ? error : undefined;
+    if (fields?.name === "AbortError") {
+        return grokError("Grok video download timed out", 504, "GROK_VIDEO_TIMEOUT");
+    }
+    if (fields?.code && fields.status)
+        return error;
+    if (fields?.name === "TimeoutError") {
+        return grokError("Grok video download timed out", 504, "GROK_VIDEO_TIMEOUT");
+    }
+    const detail = error instanceof Error && typeof error.message === "string" ? error.message : "Unknown error";
+    return videoDownloadFailure(`Grok video download request failed: ${detail}`);
+}
+export async function downloadVideo(ctx, url, signal) {
+    const { combinedSignal, timer } = withTimeoutSignal(signal, downloadTimeoutMs(ctx));
+    let response;
+    let readerOwnsBody = false;
+    try {
+        combinedSignal.throwIfAborted();
+        assertVideoDownloadUrl(url);
+        // Safe to replay: downloading a finished artifact creates nothing upstream.
+        response = await grokFetchWithRetry(() => fetch(url, { signal: combinedSignal }), { signal: combinedSignal, label: "video-download" });
+        combinedSignal.throwIfAborted();
+        const contentType = videoDownloadContentType(response);
+        readerOwnsBody = true;
+        const buffer = await readVideoDownloadBody(response, combinedSignal);
+        combinedSignal.throwIfAborted();
         return { buffer, contentType };
     }
-    catch (e) {
+    catch (error) {
+        throw mapVideoDownloadError(error, signal, combinedSignal);
+    }
+    finally {
         clearTimeout(timer);
-        if (e.name === "AbortError") {
-            if (signal?.aborted)
-                throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
-            throw grokError("Grok video download timed out", 504, "GROK_VIDEO_TIMEOUT");
-        }
-        if (e.code && e.status)
-            throw e;
-        throw grokError(`Grok video download request failed: ${e.message}`, 502, "GROK_VIDEO_DOWNLOAD_FAILED");
+        if (!readerOwnsBody)
+            cancelVideoBodyBestEffort(response?.body);
     }
 }

package/lib/inflight.js

@@ -2,6 +2,7 @@ import { config } from "../config.js";
 import { getDb } from "./db.js";
 import { publish } from "./eventBus.js";
 import { buildEnvelope } from "./jobs/envelope.js";
+import { deleteExpiredTerminalJobs, deleteTerminalJob, readTerminalJob, readTerminalJobs, writeTerminalJob } from "./jobs/terminalStore.js";
 import { logError, logEvent } from "./logger.js";
 const terminalJobs = new Map(); // requestId -> terminal snapshot, active-only API stays default
 /**
@@ -18,25 +19,9 @@ function ensureTerminalJobsRestored() {
     terminalJobsRestored = true;
     try {
         const cutoff = Date.now() - config.inflight.terminalTtlMs;
-        const rows = getDb()
-            .prepare("SELECT * FROM terminal_jobs WHERE finished_at > ?")
-            .all(cutoff);
-        for (const row of rows) {
-            if (terminalJobs.has(row.request_id))
-                continue;
-            terminalJobs.set(row.request_id, {
-                requestId: row.request_id,
-                kind: row.kind,
-                status: row.status,
-                startedAt: Number(row.started_at),
-                finishedAt: Number(row.finished_at),
-                durationMs: Number(row.finished_at) - Number(row.started_at),
-                phase: row.phase || "unknown",
-                phaseAt: Number(row.phase_at || row.finished_at),
-                httpStatus: row.http_status ?? undefined,
-                errorCode: row.error_code ?? undefined,
-                meta: parseMeta(row.meta),
-            });
+        for (const job of readTerminalJobs(cutoff)) {
+            if (!terminalJobs.has(job.requestId))
+                terminalJobs.set(job.requestId, job);
         }
     }
     catch (err) {
@@ -47,13 +32,7 @@ function ensureTerminalJobsRestored() {
 }
 function persistTerminalJob(job) {
     try {
-        getDb()
-            .prepare(`
-        INSERT OR REPLACE INTO terminal_jobs (
-          request_id, kind, status, started_at, finished_at, phase, phase_at, http_status, error_code, meta
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `)
-            .run(job.requestId, job.kind, job.status, job.startedAt, job.finishedAt, job.phase, job.phaseAt, job.httpStatus ?? null, job.errorCode ?? null, JSON.stringify(job.meta ?? {}));
+        writeTerminalJob(job);
     }
     catch (err) {
         logError("inflight", "terminal_persist:error", err);
@@ -73,13 +52,11 @@ export function startJob({ requestId, kind, prompt, meta = {}, respectCanceledTo
     if (!requestId)
         return;
     purgeStaleJobs();
+    ensureTerminalJobsRestored();
     if (getJob(requestId)) {
         return { ok: false, code: "REQUEST_ID_IN_USE" };
     }
-    // Opt-in tombstone respect (extend audit B2 round 3): a DELETE that raced
-    // ahead of admission must still win. Without this, startJob deleted the
-    // tombstone and ran a job the user already canceled. Off by default — the
-    // agent queue's retry path reuses requestIds after cancel legitimately.
+    // Extend respects a cancel that preceded admission; queue retry may reuse IDs.
     if (respectCanceledTombstone && terminalJobs.get(requestId)?.status === "canceled") {
         return { ok: false, code: "GENERATION_CANCELED" };
     }
@@ -90,23 +67,8 @@ export function startJob({ requestId, kind, prompt, meta = {}, respectCanceledTo
     const normalizedPrompt = typeof prompt === "string" ? prompt.slice(0, 500) : "";
     const normalizedMeta = normalizeMeta(meta);
     try {
-        getDb()
-            .prepare(`
-        INSERT INTO inflight (
-          request_id,
-          kind,
-          prompt,
-          meta,
-          session_id,
-          parent_node_id,
-          client_node_id,
-          started_at,
-          phase,
-          phase_at
-        )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `)
-            .run(requestId, kind, normalizedPrompt, JSON.stringify(normalizedMeta), stringOrNull(normalizedMeta.sessionId), stringOrNull(normalizedMeta.parentNodeId), stringOrNull(normalizedMeta.clientNodeId), startedAt, "queued", startedAt);
+        insertJob({ requestId, kind, prompt: normalizedPrompt, meta: normalizedMeta,
+            startedAt, phase: "queued", phaseAt: startedAt });
     }
     catch (err) {
         const code = err?.code;
@@ -131,55 +93,58 @@ export function startJob({ requestId, kind, prompt, meta = {}, respectCanceledTo
 export function registerJobAbortController(requestId, controller) {
     if (!requestId)
         return;
+    if (isJobCanceled(requestId) || isJobTrackingExpired(requestId)) {
+        controller.abort();
+        return;
+    }
     abortControllers.set(requestId, controller);
     controllerRegisteredAt.set(requestId, Date.now());
 }
 export function abortJob(requestId) {
     if (!requestId)
         return { requestId: "", active: false, aborted: false };
+    const alreadyTerminal = isJobCanceled(requestId) || isJobTrackingExpired(requestId);
     const controller = abortControllers.get(requestId);
     const active = Boolean(getJob(requestId));
-    let aborted = false;
-    if (controller && !controller.signal.aborted) {
-        controller.abort();
-        aborted = true;
+    const aborted = Boolean(controller && !controller.signal.aborted);
+    const inflightPhase = getJobPhase(requestId);
+    let failed;
+    try {
+        finishJob(requestId, { canceled: true, httpStatus: 499, errorCode: "GENERATION_CANCELED" });
     }
-    if (active || aborted) {
-        // #151 stage 2: the cancel path is a terminal event, so it carries the
-        // canonical envelope. Assembled inline rather than via ssePublish because
-        // ssePublish imports this module (cycle), and abortJob already knows the
-        // inflight phase locally.
-        const data = {
-            error: "Generation canceled",
-            code: "GENERATION_CANCELED",
-            status: 499,
-            requestId,
-        };
-        const inflightPhase = getJobPhase(requestId);
-        publish(requestId, "error", data, {
-            buildEnvelope: (sequence) => buildEnvelope({
-                jobId: requestId,
-                requestId,
-                sequence,
-                event: "error",
-                data,
-                inflightPhase,
-            }),
-        });
+    catch (error) {
+        failed = { error };
     }
-    finishJob(requestId, {
-        canceled: true,
-        httpStatus: 499,
-        errorCode: "GENERATION_CANCELED",
-    });
+    // Establish terminal dominance before synchronous AbortSignal listeners run.
+    if (aborted)
+        controller.abort();
+    if (!alreadyTerminal && (active || aborted)) {
+        publishTerminalError(requestId, inflightPhase, "GENERATION_CANCELED", 499, "Generation canceled");
+    }
+    if (failed)
+        throw failed.error;
     return { requestId, active, aborted };
 }
+function publishTerminalError(requestId, inflightPhase, code, status, error) {
+    const data = { requestId, code, status, error };
+    // The registry cannot use ssePublish, which imports it. Keep this cycle-free.
+    publish(requestId, "error", data, {
+        buildEnvelope: (sequence) => buildEnvelope({ jobId: requestId, requestId,
+            sequence, event: "error", data, inflightPhase }),
+    });
+}
 export function isJobCanceled(requestId) {
     if (!requestId)
         return false;
     ensureTerminalJobsRestored();
     return terminalJobs.get(requestId)?.status === "canceled";
 }
+export function isJobTrackingExpired(requestId) {
+    if (!requestId)
+        return false;
+    ensureTerminalJobsRestored();
+    return terminalJobs.get(requestId)?.errorCode === "JOB_TRACKING_TIMEOUT";
+}
 /**
  * Current raw phase for a job, or null when it is not active.
  *
@@ -227,39 +192,28 @@ export function updateJobAdmission(requestId, { prompt, meta }) {
         logError("inflight", "update_admission:error", err);
     }
 }
+function recordFinishedJob(job, options, finishedAt) {
+    const status = options.canceled ? "canceled" : options.status || "completed";
+    const snapshot = {
+        requestId: job.requestId, kind: job.kind, status, startedAt: job.startedAt,
+        finishedAt, durationMs: finishedAt - job.startedAt, phase: job.phase, phaseAt: job.phaseAt,
+        httpStatus: options.httpStatus, errorCode: options.errorCode,
+        meta: { ...job.meta, ...(options.meta || {}) },
+    };
+    terminalJobs.set(job.requestId, snapshot);
+    persistTerminalJob(snapshot);
+    logEvent("inflight", "finish", { requestId: job.requestId, kind: job.kind, status,
+        durationMs: snapshot.durationMs, httpStatus: options.httpStatus, errorCode: options.errorCode });
+}
 export function finishJob(requestId, options = {}) {
     if (!requestId)
         return;
+    ensureTerminalJobsRestored();
     const j = getJob(requestId);
     const finishedAt = Date.now();
-    if (j) {
-        const status = options.canceled ? "canceled" : options.status || "completed";
-        const snapshot = {
-            requestId,
-            kind: j.kind,
-            status,
-            startedAt: j.startedAt,
-            finishedAt,
-            durationMs: finishedAt - j.startedAt,
-            phase: j.phase,
-            phaseAt: j.phaseAt,
-            httpStatus: options.httpStatus,
-            errorCode: options.errorCode,
-            meta: {
-                ...j.meta,
-                ...(options.meta || {}),
-            },
-        };
-        terminalJobs.set(requestId, snapshot);
-        persistTerminalJob(snapshot);
-        logEvent("inflight", "finish", {
-            requestId,
-            kind: j.kind,
-            status,
-            durationMs: finishedAt - j.startedAt,
-            httpStatus: options.httpStatus,
-            errorCode: options.errorCode,
-        });
+    const forcedTerminal = isJobCanceled(requestId) || isJobTrackingExpired(requestId);
+    if (j && !forcedTerminal) {
+        recordFinishedJob(j, options, finishedAt);
     }
     else if (options.canceled && !terminalJobs.has(requestId)) {
         const tombstone = {
@@ -289,9 +243,7 @@ export function reapTerminalJobs(now = Date.now()) {
             terminalJobs.delete(id);
     }
     try {
-        getDb()
-            .prepare("DELETE FROM terminal_jobs WHERE finished_at <= ?")
-            .run(now - config.inflight.terminalTtlMs);
+        deleteExpiredTerminalJobs(now - config.inflight.terminalTtlMs);
     }
     catch (err) {
         logError("inflight", "terminal_reap:error", err);
@@ -346,9 +298,57 @@ export function _resetForTests() {
     controllerRegisteredAt.clear();
 }
 export function purgeStaleJobs(now = Date.now()) {
-    getDb()
-        .prepare("DELETE FROM inflight WHERE started_at < ?")
-        .run(now - config.inflight.ttlMs);
+    ensureTerminalJobsRestored();
+    let outcomes;
+    try {
+        outcomes = getDb().transaction(() => expireStaleRows(now))();
+    }
+    catch (error) {
+        logError("inflight", "expire:error", error);
+        return;
+    }
+    // Commit every memory outcome before any reentrant abort listener can publish.
+    for (const { terminal } of outcomes)
+        terminalJobs.set(terminal.requestId, terminal);
+    for (const { terminal, expired } of outcomes) {
+        const controller = abortControllers.get(terminal.requestId);
+        abortControllers.delete(terminal.requestId);
+        controllerRegisteredAt.delete(terminal.requestId);
+        if (terminal.status === "canceled" || terminal.errorCode === "JOB_TRACKING_TIMEOUT")
+            controller?.abort();
+        if (expired)
+            publishTerminalError(terminal.requestId, terminal.phase, "JOB_TRACKING_TIMEOUT", 504, "Job tracking expired; upstream completion is unknown. Inspect history before retrying.");
+    }
+}
+function expireStaleRows(now) {
+    const rows = getDb().prepare(`SELECT request_id, kind, prompt, meta, session_id,
+    parent_node_id, client_node_id, started_at, phase, phase_at FROM inflight WHERE started_at < ?`)
+        .all(now - config.inflight.ttlMs);
+    const cutoff = now - config.inflight.terminalTtlMs;
+    return rows.map(row => {
+        const memory = terminalJobs.get(row.request_id);
+        const disk = readTerminalJob(row.request_id, cutoff);
+        const retained = memory && memory.finishedAt > cutoff ? memory : disk;
+        const terminal = retained ?? expiredSnapshot(rowToJob(row), now);
+        // Also repairs a prior best-effort persistence failure without changing time/status.
+        if (!retained || JSON.stringify(terminal) !== JSON.stringify(disk))
+            writeTerminalJob(terminal);
+        getDb().prepare("DELETE FROM inflight WHERE request_id = ?").run(row.request_id);
+        return { terminal, expired: !retained };
+    });
+}
+function expiredSnapshot(job, now) {
+    return { requestId: job.requestId, kind: job.kind, status: "error", startedAt: job.startedAt,
+        finishedAt: now, durationMs: now - job.startedAt, phase: job.phase, phaseAt: job.phaseAt,
+        httpStatus: 504, errorCode: "JOB_TRACKING_TIMEOUT", meta: job.meta };
+}
+function insertJob(job) {
+    getDb().transaction(() => {
+        getDb().prepare(`INSERT INTO inflight (request_id, kind, prompt, meta, session_id,
+      parent_node_id, client_node_id, started_at, phase, phase_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(job.requestId, job.kind, job.prompt, JSON.stringify(job.meta), stringOrNull(job.meta.sessionId), stringOrNull(job.meta.parentNodeId), stringOrNull(job.meta.clientNodeId), job.startedAt, job.phase, job.phaseAt);
+        deleteTerminalJob(job.requestId);
+    })();
 }
 function countActiveJobs() {
     const row = getDb()

package/lib/jobs/terminalStore.js

@@ -0,0 +1,45 @@
+import { getDb } from "../db.js";
+const COLUMNS = "request_id, kind, status, started_at, finished_at, phase, phase_at, http_status, error_code, meta";
+function parseMeta(raw) {
+    if (typeof raw !== "string" || !raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function fromRow(row) {
+    return {
+        requestId: row.request_id, kind: row.kind, status: row.status,
+        startedAt: Number(row.started_at), finishedAt: Number(row.finished_at),
+        durationMs: Number(row.finished_at) - Number(row.started_at),
+        phase: row.phase || "unknown", phaseAt: Number(row.phase_at || row.finished_at),
+        httpStatus: row.http_status ?? undefined, errorCode: row.error_code ?? undefined,
+        meta: parseMeta(row.meta),
+    };
+}
+export function readTerminalJobs(cutoff) {
+    const rows = getDb().prepare(`SELECT ${COLUMNS} FROM terminal_jobs WHERE finished_at > ?`)
+        .all(cutoff);
+    return rows.map(fromRow);
+}
+export function readTerminalJob(requestId, cutoff) {
+    const row = getDb().prepare(`SELECT ${COLUMNS} FROM terminal_jobs WHERE request_id = ? AND finished_at > ?`)
+        .get(requestId, cutoff);
+    return row ? fromRow(row) : null;
+}
+/** Throws on failure so the caller can include the write in its transaction. */
+export function writeTerminalJob(job) {
+    getDb().prepare(`INSERT OR REPLACE INTO terminal_jobs (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(job.requestId, job.kind, job.status, job.startedAt, job.finishedAt, job.phase, job.phaseAt, job.httpStatus ?? null, job.errorCode ?? null, JSON.stringify(job.meta ?? {}));
+}
+export function deleteTerminalJob(requestId) {
+    getDb().prepare("DELETE FROM terminal_jobs WHERE request_id = ?").run(requestId);
+}
+export function deleteExpiredTerminalJobs(cutoff) {
+    getDb().prepare("DELETE FROM terminal_jobs WHERE finished_at <= ?").run(cutoff);
+}

package/lib/lanSessionStore.js

@@ -0,0 +1,131 @@
+import { createHash, randomBytes as cryptoRandomBytes } from "node:crypto";
+import { localAccessError } from "./localAccessPolicy.js";
+const ID_ATTEMPTS = 4;
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+class LanSessionStore {
+    options;
+    now;
+    random;
+    records = new Map();
+    timer;
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.random = options.randomBytes ?? cryptoRandomBytes;
+    }
+    remove(key) {
+        const record = this.records.get(key);
+        this.records.delete(key);
+        if (!record)
+            return;
+        const closers = [...record.closers];
+        record.closers.clear();
+        for (const close of closers) {
+            try {
+                close();
+            }
+            catch { /* A broken response must not prevent revoking its siblings. */ }
+        }
+    }
+    schedule() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        if (this.disposed || !this.records.size)
+            return;
+        const nearest = Math.min(...[...this.records.values()].map(record => record.expiresAt));
+        this.timer = setTimeout(() => { this.prune(); this.schedule(); }, Math.max(1, nearest - this.now()));
+        this.timer.unref();
+    }
+    prune() {
+        for (const [key, record] of this.records)
+            if (record.expiresAt <= this.now())
+                this.remove(key);
+    }
+    issue(origin) {
+        if (this.disposed)
+            throw localAccessError("LAN_SESSION_UNAVAILABLE", 503);
+        this.prune();
+        if (this.disposed)
+            throw localAccessError("LAN_SESSION_UNAVAILABLE", 503);
+        const { records, options, random, now } = this;
+        if (records.size >= options.maxSessions)
+            throw localAccessError("LAN_SESSION_CAPACITY", 503);
+        for (let attempt = 0; attempt < ID_ATTEMPTS; attempt++) {
+            let value;
+            try {
+                value = random(32).toString("base64url");
+            }
+            catch {
+                throw localAccessError("LAN_SESSION_UNAVAILABLE", 503);
+            }
+            const key = digest(value);
+            if (records.has(key))
+                continue;
+            const issuedAt = now(), expiresAt = issuedAt + options.ttlMs;
+            records.set(key, { origin, issuedAt, expiresAt, closers: new Set() });
+            this.schedule();
+            return { value, expiresAt };
+        }
+        throw localAccessError("LAN_SESSION_UNAVAILABLE", 503);
+    }
+    validate(value, origin) {
+        this.prune();
+        this.schedule();
+        const record = this.records.get(digest(value));
+        return record?.origin === origin ? { expiresAt: record.expiresAt } : null;
+    }
+    track(value, close) {
+        this.prune();
+        this.schedule();
+        const record = this.records.get(digest(value));
+        if (!record) {
+            close();
+            return () => { };
+        }
+        record.closers.add(close);
+        return () => { record.closers.delete(close); };
+    }
+    revoke(value) { this.remove(digest(value)); this.schedule(); }
+    dispose() {
+        this.disposed = true;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        for (const key of this.records.keys())
+            this.remove(key);
+    }
+}
+export function createLanSessionStore(options) {
+    return new LanSessionStore(options);
+}
+/** Socket-peer failure budget; independent of the app's API admission budget. */
+export function createLanAuthThrottle(options) {
+    const now = options.now ?? Date.now;
+    const buckets = new Map();
+    function prune() {
+        for (const [peer, bucket] of buckets)
+            if (bucket.expiresAt <= now())
+                buckets.delete(peer);
+    }
+    return {
+        retryAfter(peer) {
+            prune();
+            const bucket = buckets.get(peer);
+            if (bucket && bucket.failures >= options.maxFailures)
+                return Math.max(1, Math.ceil((bucket.expiresAt - now()) / 1000));
+            if (!bucket && buckets.size >= options.maxBuckets) {
+                return Math.max(1, Math.ceil((Math.min(...[...buckets.values()].map(b => b.expiresAt)) - now()) / 1000));
+            }
+            return 0;
+        },
+        fail(peer) {
+            prune();
+            const bucket = buckets.get(peer);
+            if (bucket)
+                bucket.failures++;
+            else if (buckets.size < options.maxBuckets)
+                buckets.set(peer, { failures: 1, expiresAt: now() + options.windowMs });
+        },
+        dispose() { buckets.clear(); },
+    };
+}