aiden-runtime 4.1.5 → 4.5.0

package/dist/core/v4/daemon/triggers/webhookSpec.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/webhookSpec.ts — v4.5 Phase 3.
+ *
+ * Typed spec stored in triggers.spec_json for source='webhook'.
+ *
+ * Secret handling (corrected design):
+ *   HMAC verification REQUIRES the raw secret at request time, so
+ *   we store it RAW. Daemon.db sits under user-private
+ *   %LOCALAPPDATA%/aiden/daemon/ on Windows and is chmod 600 on POSIX
+ *   (see db/connection.ts). The raw secret is surfaced to the user
+ *   ONLY on creation by `aiden trigger add webhook` with an explicit
+ *   "save this now" warning.
+ *
+ * INSECURE_NO_AUTH sentinel: literal string the user can place in
+ * spec.secret to disable HMAC verification entirely. Only usable
+ * when the daemon is bound to loopback (127.0.0.1). Phase 3
+ * refuses to start a public-bound daemon with any INSECURE_NO_AUTH
+ * route configured.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WEBHOOK_SPEC = exports.INSECURE_NO_AUTH = void 0;
+exports.parseWebhookSpec = parseWebhookSpec;
+exports.INSECURE_NO_AUTH = '__INSECURE_NO_AUTH__';
+exports.DEFAULT_WEBHOOK_SPEC = {
+    hmacFormat: 'generic',
+    rateLimit: { perMinute: 30 },
+    maxBodyBytes: 1048576, // 1 MiB
+    idempotencyTtlMs: 60 * 60 * 1000, // 1 hour
+    deliverOnly: false,
+    publicBound: false,
+};
+function parseWebhookSpec(raw) {
+    const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        throw new Error('WebhookSpec: input must be an object');
+    }
+    const o = obj;
+    const name = typeof o.name === 'string' ? o.name : '';
+    if (!name)
+        throw new Error('WebhookSpec: name required');
+    const secret = typeof o.secret === 'string' ? o.secret : '';
+    if (!secret)
+        throw new Error('WebhookSpec: secret required (use INSECURE_NO_AUTH sentinel for loopback testing)');
+    const hmacFormat = sanitizeHmacFormat(o.hmacFormat);
+    const rateLimitObj = (o.rateLimit && typeof o.rateLimit === 'object') ? o.rateLimit : {};
+    const perMinute = sanitizeNum(rateLimitObj.perMinute, exports.DEFAULT_WEBHOOK_SPEC.rateLimit.perMinute, 1);
+    return {
+        name,
+        secret,
+        hmacFormat,
+        allowedEvents: Array.isArray(o.allowedEvents) ? o.allowedEvents.filter((s) => typeof s === 'string') : undefined,
+        rateLimit: { perMinute },
+        maxBodyBytes: sanitizeNum(o.maxBodyBytes, exports.DEFAULT_WEBHOOK_SPEC.maxBodyBytes, 1),
+        idempotencyTtlMs: sanitizeNum(o.idempotencyTtlMs, exports.DEFAULT_WEBHOOK_SPEC.idempotencyTtlMs, 1),
+        deliverOnly: typeof o.deliverOnly === 'boolean' ? o.deliverOnly : exports.DEFAULT_WEBHOOK_SPEC.deliverOnly,
+        promptTemplate: typeof o.promptTemplate === 'string' ? o.promptTemplate : undefined,
+        publicBound: typeof o.publicBound === 'boolean' ? o.publicBound : exports.DEFAULT_WEBHOOK_SPEC.publicBound,
+    };
+}
+function sanitizeHmacFormat(v) {
+    if (v === 'github' || v === 'gitlab' || v === 'generic')
+        return v;
+    return exports.DEFAULT_WEBHOOK_SPEC.hmacFormat;
+}
+function sanitizeNum(v, fallback, min) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < min)
+        return fallback;
+    return v;
+}

package/dist/core/v4/daemon/triggers/webhookVerifier.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/webhookVerifier.ts — v4.5 Phase 3.
+ *
+ * Per-format HMAC verification. Constant-time comparison via
+ * `crypto.timingSafeEqual` to defeat timing attacks.
+ *
+ * Three formats supported in Phase 3:
+ *   github   — X-Hub-Signature-256: sha256=<hex>
+ *              HMAC-SHA256(secret, body) == hex
+ *
+ *   gitlab   — X-Gitlab-Token: <plain>
+ *              Plain shared-secret comparison. No HMAC; the token
+ *              header IS the secret. Constant-time compared.
+ *
+ *   generic  — X-Webhook-Signature: <hex>
+ *              HMAC-SHA256(secret, body) == hex
+ *
+ * Phase 3.x extensibility: add new entries to `VERIFIERS` map.
+ * Stripe (timestamped) and Slack (timestamped) would each get a
+ * function that pulls timestamp + signature from headers and
+ * verifies HMAC-SHA256(secret, `${ts}.${body}`).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.deriveEventName = deriveEventName;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const webhookSpec_1 = require("./webhookSpec");
+function verifyWebhookSignature(opts) {
+    // Loopback-only insecure mode — the SAFETY of this depends on
+    // the daemon being bound to 127.0.0.1, enforced by bootstrap.
+    if (opts.secret === webhookSpec_1.INSECURE_NO_AUTH)
+        return true;
+    const fn = VERIFIERS[opts.format];
+    if (!fn)
+        return false;
+    try {
+        return fn(opts);
+    }
+    catch {
+        return false;
+    }
+}
+const VERIFIERS = {
+    github(o) {
+        const raw = pickHeader(o.headers, 'x-hub-signature-256');
+        if (!raw)
+            return false;
+        // GitHub header is `sha256=<hex>`. Strip the prefix.
+        const m = raw.match(/^sha256=([0-9a-fA-F]+)$/);
+        if (!m)
+            return false;
+        const expected = hmacHex(o.secret, o.body);
+        return safeEqualHex(expected, m[1]);
+    },
+    gitlab(o) {
+        const received = pickHeader(o.headers, 'x-gitlab-token');
+        if (!received)
+            return false;
+        // Plain shared-secret. Compare as bytes; constant-time.
+        return safeEqualString(o.secret, received);
+    },
+    generic(o) {
+        const raw = pickHeader(o.headers, 'x-webhook-signature');
+        if (!raw)
+            return false;
+        const expected = hmacHex(o.secret, o.body);
+        return safeEqualHex(expected, raw.trim());
+    },
+};
+function hmacHex(secret, body) {
+    return node_crypto_1.default.createHmac('sha256', secret).update(body).digest('hex');
+}
+function safeEqualHex(a, b) {
+    // Both must be same hex length to call timingSafeEqual without
+    // throwing.
+    if (a.length !== b.length)
+        return false;
+    try {
+        return node_crypto_1.default.timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+    }
+    catch {
+        return false;
+    }
+}
+function safeEqualString(a, b) {
+    const ab = Buffer.from(a, 'utf-8');
+    const bb = Buffer.from(b, 'utf-8');
+    if (ab.length !== bb.length)
+        return false;
+    try {
+        return node_crypto_1.default.timingSafeEqual(ab, bb);
+    }
+    catch {
+        return false;
+    }
+}
+function pickHeader(headers, name) {
+    // Express lowercases header names. Be defensive in case caller
+    // passes uppercase.
+    const k = name.toLowerCase();
+    const v = headers[k] ?? headers[name];
+    if (Array.isArray(v))
+        return v[0] ?? null;
+    if (typeof v === 'string')
+        return v;
+    return null;
+}
+/**
+ * Map an event name out of the request headers, per format. Used
+ * for the optional spec.allowedEvents filter.
+ */
+function deriveEventName(format, headers) {
+    if (format === 'github')
+        return pickHeader(headers, 'x-github-event') ?? '';
+    if (format === 'gitlab')
+        return pickHeader(headers, 'x-gitlab-event') ?? '';
+    return pickHeader(headers, 'x-webhook-event') ?? '';
+}

package/dist/core/v4/daemon/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/types.ts — v4.5 Phase 1: shared type surface.
+ *
+ * Pure types only. No I/O, no imports of side-effecting modules.
+ * Keeps the dependency graph one-way (every other daemon module
+ * imports from here, but this imports nothing of consequence).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/v4/dockerSession.js

@@ -0,0 +1,461 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/dockerSession.ts — v4.4 Phase 3: long-lived sandbox container
+ * lifecycle + reuse cache.
+ *
+ * One long-lived `docker run -d ... sleep` container is created per
+ * session and reused across every `shell_exec` call within that
+ * session. Per-command execution goes through `docker exec` — orders
+ * of magnitude faster than the old single-shot `docker run --rm`
+ * pattern (no image-resolution, no namespace setup, no teardown
+ * per call).
+ *
+ * Lifecycle:
+ *   - first exec for a sessionId  → start container (`docker run -d`),
+ *                                  cache the handle, run `docker exec`.
+ *   - subsequent execs            → reuse the cached container.
+ *   - idle past `idleReaperMs`    → background reaper stops + removes.
+ *   - SIGINT / SIGTERM / beforeExit → reapAllContainers() (parallel
+ *                                  best-effort, never blocks shutdown).
+ *
+ * Concurrency:
+ *   - Stampede defense: every handle carries an in-flight `starting`
+ *     promise. A second caller that finds an existing handle with
+ *     `starting != null` awaits it before proceeding.
+ *   - Reaper is fire-and-forget; mark the handle `reaped: true` first,
+ *     then `docker stop` async. Racing callers either find `reaped`
+ *     and create a new container, or hit a dead container in
+ *     `docker exec` and we restart.
+ *
+ * Local fallback (Q-P3-5):
+ *   - When `isDockerAvailable() === false`, route through
+ *     `localBackendExecute` and emit a one-time warning per session.
+ *     The returned `backend` field stays `'local'` so traces are
+ *     honest about what actually ran.
+ *
+ * Hardening flags applied unconditionally:
+ *   --cap-drop ALL
+ *   --security-opt no-new-privileges
+ *   --pids-limit <config>
+ *   --memory <config>
+ *   --cpus <config>
+ *   --tmpfs /tmp:rw,size=256m
+ *   --tmpfs /var/tmp:rw,size=64m
+ *   --tmpfs /run:rw,size=16m
+ *   --network <bridge|none>
+ *   -v cwd:/workspace            (only when persistent === true)
+ *   --tmpfs /workspace:rw,...    (only when persistent === false)
+ *
+ * Gated by `config.enabled` (AIDEN_SANDBOX=1 strict in Phase 1-5).
+ * The status-quo single-shot `dockerBackendExecute` in
+ * `tools/v4/backends/docker.ts` is retained for the `AIDEN_SANDBOX=0
+ * + ctx.terminalBackend='docker'` path — zero regression there.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._clearDockerAvailCacheForTests = _clearDockerAvailCacheForTests;
+exports.dockerSessionExec = dockerSessionExec;
+exports.reapSessionContainer = reapSessionContainer;
+exports.reapAllContainers = reapAllContainers;
+exports._resetDockerSessionForTests = _resetDockerSessionForTests;
+exports._inspectDockerSessionsForTests = _inspectDockerSessionsForTests;
+exports._setDockerAvailableForTests = _setDockerAvailableForTests;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const sandboxConfig_1 = require("./sandboxConfig");
+const local_1 = require("../../tools/v4/backends/local");
+// ── Module state ────────────────────────────────────────────────────────────
+const _containers = new Map();
+/** Sessions for which we already logged the local-fallback warning. */
+const _warnedFallback = new Set();
+let _reaperInterval = null;
+let _shutdownHookInstalled = false;
+// ── Docker availability cache (60s) ─────────────────────────────────────────
+let _dockerAvailCache = null;
+const DOCKER_AVAIL_TTL = 60000;
+function isDockerAvailableCached() {
+    const now = Date.now();
+    if (_dockerAvailCache && now - _dockerAvailCache.ts < DOCKER_AVAIL_TTL) {
+        return _dockerAvailCache.value;
+    }
+    let value = false;
+    try {
+        const r = (0, node_child_process_1.spawnSync)('docker', ['version', '--format', '{{.Server.Version}}'], {
+            timeout: 3000,
+            stdio: 'pipe',
+        });
+        value = r.status === 0;
+    }
+    catch {
+        value = false;
+    }
+    _dockerAvailCache = { ts: now, value };
+    return value;
+}
+/** Test-only — clears the docker-availability cache. */
+function _clearDockerAvailCacheForTests() {
+    _dockerAvailCache = null;
+}
+// ── Container start ─────────────────────────────────────────────────────────
+function shortId() {
+    return (0, node_crypto_1.randomBytes)(4).toString('hex');
+}
+function buildRunArgs(opts) {
+    const args = [
+        'run',
+        '-d',
+        '--name', opts.name,
+        '--cap-drop', 'ALL',
+        '--security-opt', 'no-new-privileges',
+        '--pids-limit', String(opts.config.resourceLimits.pidsLimit),
+        '--memory', opts.config.resourceLimits.memory,
+        '--cpus', opts.config.resourceLimits.cpus,
+        '--tmpfs', '/tmp:rw,size=256m',
+        '--tmpfs', '/var/tmp:rw,size=64m',
+        '--tmpfs', '/run:rw,size=16m',
+        '--network', opts.config.networkMode,
+    ];
+    if (opts.persistent) {
+        args.push('-v', `${opts.cwd}:/workspace`);
+    }
+    else {
+        args.push('--tmpfs', '/workspace:rw,size=512m');
+    }
+    args.push('-w', '/workspace');
+    args.push(opts.image);
+    // sleep loop — busybox `sleep infinity` isn't portable; use a loop
+    // so plain alpine images work without GNU coreutils.
+    args.push('sh', '-c', 'while true; do sleep 3600; done');
+    return args;
+}
+async function startContainer(sessionId, image, cwd, persistent, config) {
+    const name = `aiden-sbx-${sessionId.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 32)}-${shortId()}`;
+    const args = buildRunArgs({ config, image, cwd, name, persistent });
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)('docker', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+        }, 120000); // first run may pull the image
+        child.stdout?.on('data', (b) => { stdout += b.toString(); });
+        child.stderr?.on('data', (b) => { stderr += b.toString(); });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(new Error(`docker run failed: ${err.message}`));
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                reject(new Error('docker run timed out (120s)'));
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`docker run exited ${code}: ${stderr.trim()}`));
+                return;
+            }
+            const id = stdout.trim().split(/\s+/)[0];
+            if (!id) {
+                reject(new Error('docker run produced no container id'));
+                return;
+            }
+            resolve(id);
+        });
+    });
+}
+// ── Container exec ──────────────────────────────────────────────────────────
+function execInContainer(handle, args, cb) {
+    handle.lastUsedAt = Date.now();
+    const timeoutMs = args.timeoutMs ?? 30000;
+    const capture = args.captureOutput ?? true;
+    const start = Date.now();
+    const execArgs = ['exec', '-i'];
+    if (args.env) {
+        for (const [k, v] of Object.entries(args.env)) {
+            execArgs.push('-e', `${k}=${v}`);
+        }
+    }
+    execArgs.push(handle.id, 'sh', '-c', args.command);
+    return new Promise((resolve) => {
+        const child = (0, node_child_process_1.spawn)('docker', execArgs, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        if (capture) {
+            child.stdout?.on('data', (b) => {
+                const s = b.toString();
+                stdout += s;
+                cb.log?.('info', s.slice(0, 200));
+            });
+            child.stderr?.on('data', (b) => {
+                const s = b.toString();
+                stderr += s;
+                cb.log?.('warn', s.slice(0, 200));
+            });
+        }
+        else {
+            child.stdout?.resume();
+            child.stderr?.resume();
+        }
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+            setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* ignore */ }
+            }, 2000);
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: -1,
+                stdout,
+                stderr: stderr || err.message,
+                durationMs: Date.now() - start,
+                timedOut,
+                backend: 'docker',
+            });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: typeof code === 'number' ? code : -1,
+                stdout,
+                stderr,
+                durationMs: Date.now() - start,
+                timedOut,
+                backend: 'docker',
+            });
+        });
+    });
+}
+// ── Public exec entry point ─────────────────────────────────────────────────
+/**
+ * Execute a command inside the long-lived sandbox container for the
+ * given session. Starts a new container if none exists, reuses
+ * otherwise. Falls back to the local backend when Docker isn't
+ * available, warning once per session.
+ */
+async function dockerSessionExec(args, cb = {}) {
+    const config = (0, sandboxConfig_1.getSandboxConfig)();
+    const sessionId = args.sessionId ?? 'default';
+    const cwd = args.cwd ?? process.cwd();
+    const image = args.image ?? config.image;
+    // Local fallback when Docker isn't reachable.
+    if (!isDockerAvailableCached()) {
+        if (!_warnedFallback.has(sessionId)) {
+            _warnedFallback.add(sessionId);
+            cb.log?.('warn', 'Sandbox: Docker is not running or unreachable. ' +
+                'Falling back to local backend for this session — resource ' +
+                'limits and isolation are NOT enforced.');
+        }
+        return (0, local_1.localBackendExecute)({
+            command: args.command,
+            cwd,
+            env: args.env,
+            timeoutMs: args.timeoutMs,
+            captureOutput: args.captureOutput,
+        }, cb);
+    }
+    // Opportunistic idle sweep on the active path (Q-P3-4 hybrid).
+    sweepIdleAsync(config);
+    // Hot path — reuse existing container if any.
+    let handle = _containers.get(sessionId);
+    if (handle && !handle.reaped) {
+        if (handle.starting) {
+            try {
+                await handle.starting;
+            }
+            catch {
+                // start failed; drop the handle and fall through to restart.
+                _containers.delete(sessionId);
+                handle = undefined;
+            }
+        }
+    }
+    if (!handle || handle.reaped) {
+        // Start a new container.
+        const newHandle = {
+            id: '',
+            sessionId,
+            image,
+            cwd,
+            persistent: config.persistent,
+            startedAt: Date.now(),
+            lastUsedAt: Date.now(),
+            reaped: false,
+            warnedFallback: false,
+        };
+        let resolveStart = () => undefined;
+        let rejectStart = () => undefined;
+        newHandle.starting = new Promise((res, rej) => {
+            resolveStart = res;
+            rejectStart = rej;
+        });
+        _containers.set(sessionId, newHandle);
+        armReaperIfNeeded();
+        try {
+            const id = await startContainer(sessionId, image, cwd, config.persistent, config);
+            newHandle.id = id;
+            newHandle.starting = undefined;
+            resolveStart();
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            _containers.delete(sessionId);
+            rejectStart(err);
+            return {
+                exitCode: -1,
+                stdout: '',
+                stderr: `Sandbox: failed to start container: ${err.message}`,
+                durationMs: 0,
+                timedOut: false,
+                backend: 'docker',
+            };
+        }
+        handle = newHandle;
+    }
+    return execInContainer(handle, args, cb);
+}
+// ── Idle reaper ─────────────────────────────────────────────────────────────
+function sweepIdleAsync(config) {
+    const now = Date.now();
+    for (const handle of _containers.values()) {
+        if (handle.starting)
+            continue;
+        if (handle.reaped)
+            continue;
+        if (now - handle.lastUsedAt > config.idleReaperMs) {
+            // Fire-and-forget.
+            void reapSessionContainer(handle.sessionId);
+        }
+    }
+}
+function armReaperIfNeeded() {
+    if (_reaperInterval)
+        return;
+    _reaperInterval = setInterval(() => {
+        try {
+            sweepIdleAsync((0, sandboxConfig_1.getSandboxConfig)());
+            if (_containers.size === 0 && _reaperInterval) {
+                clearInterval(_reaperInterval);
+                _reaperInterval = null;
+            }
+        }
+        catch {
+            /* never let the reaper crash the process */
+        }
+    }, 30000);
+    // Don't keep the process alive just for the reaper.
+    if (typeof _reaperInterval.unref === 'function') {
+        _reaperInterval.unref();
+    }
+    installShutdownHook();
+}
+function installShutdownHook() {
+    if (_shutdownHookInstalled)
+        return;
+    _shutdownHookInstalled = true;
+    const handler = () => {
+        // Fire-and-forget — never block shutdown.
+        void reapAllContainers();
+    };
+    process.once('beforeExit', handler);
+    process.once('SIGINT', () => { handler(); });
+    process.once('SIGTERM', () => { handler(); });
+}
+// ── Reap APIs ───────────────────────────────────────────────────────────────
+function dockerStopRemove(id) {
+    return new Promise((resolve) => {
+        // -t 2: 2-second grace period before SIGKILL.
+        const stop = (0, node_child_process_1.spawn)('docker', ['stop', '-t', '2', id], { stdio: 'ignore' });
+        const timer = setTimeout(() => {
+            try {
+                stop.kill('SIGKILL');
+            }
+            catch { /* ignore */ }
+        }, 5000);
+        stop.on('close', () => {
+            clearTimeout(timer);
+            const rm = (0, node_child_process_1.spawn)('docker', ['rm', '-f', id], { stdio: 'ignore' });
+            const rmTimer = setTimeout(() => {
+                try {
+                    rm.kill('SIGKILL');
+                }
+                catch { /* ignore */ }
+            }, 3000);
+            rm.on('close', () => { clearTimeout(rmTimer); resolve(); });
+            rm.on('error', () => { clearTimeout(rmTimer); resolve(); });
+        });
+        stop.on('error', () => { clearTimeout(timer); resolve(); });
+    });
+}
+/** Reap one session's container. Idempotent + fire-and-forget safe. */
+async function reapSessionContainer(sessionId) {
+    const handle = _containers.get(sessionId);
+    if (!handle)
+        return;
+    if (handle.reaped)
+        return;
+    handle.reaped = true;
+    _containers.delete(sessionId);
+    if (handle.id) {
+        try {
+            await dockerStopRemove(handle.id);
+        }
+        catch { /* never throw on cleanup */ }
+    }
+}
+/** Reap every cached container. Used by shutdown hooks. */
+async function reapAllContainers() {
+    const ids = Array.from(_containers.keys());
+    await Promise.all(ids.map((sid) => reapSessionContainer(sid)));
+    if (_reaperInterval) {
+        clearInterval(_reaperInterval);
+        _reaperInterval = null;
+    }
+}
+// ── Test helpers ────────────────────────────────────────────────────────────
+/** Test-only — synchronously wipe in-memory state. Does NOT call docker. */
+function _resetDockerSessionForTests() {
+    _containers.clear();
+    _warnedFallback.clear();
+    if (_reaperInterval) {
+        clearInterval(_reaperInterval);
+        _reaperInterval = null;
+    }
+    _dockerAvailCache = null;
+}
+/** Test-only — inspect the cache state. */
+function _inspectDockerSessionsForTests() {
+    return {
+        count: _containers.size,
+        sessionIds: Array.from(_containers.keys()),
+        warnedSessions: Array.from(_warnedFallback),
+    };
+}
+/**
+ * Test-only — inject a fake docker-availability decision so unit
+ * tests can exercise the local-fallback warn-once path without
+ * actually probing docker.
+ */
+function _setDockerAvailableForTests(value) {
+    _dockerAvailCache = { ts: Date.now(), value };
+}