@poolzin/pool-bot 2026.2.11 → 2026.2.18

package/dist/agents/sandbox/validate-sandbox-security.js

@@ -0,0 +1,157 @@
+/**
+ * Sandbox security validation — blocks dangerous Docker configurations.
+ *
+ * Threat model: local-trusted config, but protect against foot-guns and config injection.
+ * Enforced at runtime when creating sandbox containers.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { posix } from "node:path";
+// Targeted denylist: host paths that should never be exposed inside sandbox containers.
+// Exported for reuse in security audit collectors.
+export const BLOCKED_HOST_PATHS = [
+    "/etc",
+    "/private/etc",
+    "/proc",
+    "/sys",
+    "/dev",
+    "/root",
+    "/boot",
+    // Directories that commonly contain (or alias) the Docker socket.
+    "/run",
+    "/var/run",
+    "/private/var/run",
+    "/var/run/docker.sock",
+    "/private/var/run/docker.sock",
+    "/run/docker.sock",
+];
+const BLOCKED_NETWORK_MODES = new Set(["host"]);
+const BLOCKED_SECCOMP_PROFILES = new Set(["unconfined"]);
+const BLOCKED_APPARMOR_PROFILES = new Set(["unconfined"]);
+/**
+ * Parse the host/source path from a Docker bind mount string.
+ * Format: `source:target[:mode]`
+ */
+export function parseBindSourcePath(bind) {
+    const trimmed = bind.trim();
+    const firstColon = trimmed.indexOf(":");
+    if (firstColon <= 0) {
+        // No colon or starts with colon — treat as source.
+        return trimmed;
+    }
+    return trimmed.slice(0, firstColon);
+}
+/**
+ * Normalize a POSIX path: resolve `.`, `..`, collapse `//`, strip trailing `/`.
+ */
+export function normalizeHostPath(raw) {
+    const trimmed = raw.trim();
+    return posix.normalize(trimmed).replace(/\/+$/, "") || "/";
+}
+/**
+ * String-only blocked-path check (no filesystem I/O).
+ * Blocks:
+ * - binds that target blocked paths (equal or under)
+ * - binds that cover the system root (mounting "/" is never safe)
+ * - non-absolute source paths (relative / volume names) because they are hard to validate safely
+ */
+export function getBlockedBindReason(bind) {
+    const sourceRaw = parseBindSourcePath(bind);
+    if (!sourceRaw.startsWith("/")) {
+        return { kind: "non_absolute", sourcePath: sourceRaw };
+    }
+    const normalized = normalizeHostPath(sourceRaw);
+    return getBlockedReasonForSourcePath(normalized);
+}
+export function getBlockedReasonForSourcePath(sourceNormalized) {
+    if (sourceNormalized === "/") {
+        return { kind: "covers", blockedPath: "/" };
+    }
+    for (const blocked of BLOCKED_HOST_PATHS) {
+        if (sourceNormalized === blocked || sourceNormalized.startsWith(blocked + "/")) {
+            return { kind: "targets", blockedPath: blocked };
+        }
+    }
+    return null;
+}
+function tryRealpathAbsolute(path) {
+    if (!path.startsWith("/")) {
+        return path;
+    }
+    if (!existsSync(path)) {
+        return path;
+    }
+    try {
+        // Use native when available (keeps platform semantics); normalize for prefix checks.
+        return normalizeHostPath(realpathSync.native(path));
+    }
+    catch {
+        return path;
+    }
+}
+function formatBindBlockedError(params) {
+    if (params.reason.kind === "non_absolute") {
+        return new Error(`Sandbox security: bind mount "${params.bind}" uses a non-absolute source path ` +
+            `"${params.reason.sourcePath}". Only absolute POSIX paths are supported for sandbox binds.`);
+    }
+    const verb = params.reason.kind === "covers" ? "covers" : "targets";
+    return new Error(`Sandbox security: bind mount "${params.bind}" ${verb} blocked path "${params.reason.blockedPath}". ` +
+        "Mounting system directories (or Docker socket paths) into sandbox containers is not allowed. " +
+        "Use project-specific paths instead (e.g. /home/user/myproject).");
+}
+/**
+ * Validate bind mounts — throws if any source path is dangerous.
+ * Includes a symlink/realpath pass when the source path exists.
+ */
+export function validateBindMounts(binds) {
+    if (!binds?.length) {
+        return;
+    }
+    for (const rawBind of binds) {
+        const bind = rawBind.trim();
+        if (!bind) {
+            continue;
+        }
+        // Fast string-only check (covers .., //, ancestor/descendant logic).
+        const blocked = getBlockedBindReason(bind);
+        if (blocked) {
+            throw formatBindBlockedError({ bind, reason: blocked });
+        }
+        // Symlink escape hardening: resolve existing absolute paths and re-check.
+        const sourceRaw = parseBindSourcePath(bind);
+        const sourceNormalized = normalizeHostPath(sourceRaw);
+        const sourceReal = tryRealpathAbsolute(sourceNormalized);
+        if (sourceReal !== sourceNormalized) {
+            const reason = getBlockedReasonForSourcePath(sourceReal);
+            if (reason) {
+                throw formatBindBlockedError({ bind, reason });
+            }
+        }
+    }
+}
+export function validateNetworkMode(network) {
+    if (network && BLOCKED_NETWORK_MODES.has(network.trim().toLowerCase())) {
+        throw new Error(`Sandbox security: network mode "${network}" is blocked. ` +
+            'Network "host" mode bypasses container network isolation. ' +
+            'Use "bridge" or "none" instead.');
+    }
+}
+export function validateSeccompProfile(profile) {
+    if (profile && BLOCKED_SECCOMP_PROFILES.has(profile.trim().toLowerCase())) {
+        throw new Error(`Sandbox security: seccomp profile "${profile}" is blocked. ` +
+            "Disabling seccomp removes syscall filtering and weakens sandbox isolation. " +
+            "Use a custom seccomp profile file or omit this setting.");
+    }
+}
+export function validateApparmorProfile(profile) {
+    if (profile && BLOCKED_APPARMOR_PROFILES.has(profile.trim().toLowerCase())) {
+        throw new Error(`Sandbox security: apparmor profile "${profile}" is blocked. ` +
+            "Disabling AppArmor removes mandatory access controls and weakens sandbox isolation. " +
+            "Use a named AppArmor profile or omit this setting.");
+    }
+}
+export function validateSandboxSecurity(cfg) {
+    validateBindMounts(cfg.binds);
+    validateNetworkMode(cfg.network);
+    validateSeccompProfile(cfg.seccompProfile);
+    validateApparmorProfile(cfg.apparmorProfile);
+}

package/dist/agents/sandbox-paths.js

@@ -24,6 +24,9 @@ function resolveToCwd(filePath, cwd) {
         return expanded;
     return path.resolve(cwd, expanded);
 }
+export function resolveSandboxInputPath(filePath, cwd) {
+    return resolveToCwd(filePath, cwd);
+}
 export function resolveSandboxPath(params) {
     const resolved = resolveToCwd(params.filePath, params.cwd);
     const rootResolved = path.resolve(params.root);

package/dist/agents/sandbox-tool-policy.js

@@ -0,0 +1,26 @@
+function unionAllow(base, extra) {
+    if (!Array.isArray(extra) || extra.length === 0) {
+        return base;
+    }
+    // If the user is using alsoAllow without an allowlist, treat it as additive on top of
+    // an implicit allow-all policy.
+    if (!Array.isArray(base) || base.length === 0) {
+        return Array.from(new Set(["*", ...extra]));
+    }
+    return Array.from(new Set([...base, ...extra]));
+}
+export function pickSandboxToolPolicy(config) {
+    if (!config) {
+        return undefined;
+    }
+    const allow = Array.isArray(config.allow)
+        ? unionAllow(config.allow, config.alsoAllow)
+        : Array.isArray(config.alsoAllow) && config.alsoAllow.length > 0
+            ? unionAllow(undefined, config.alsoAllow)
+            : undefined;
+    const deny = Array.isArray(config.deny) ? config.deny : undefined;
+    if (!allow && !deny) {
+        return undefined;
+    }
+    return { allow, deny };
+}

package/dist/agents/sanitize-for-prompt.js

@@ -0,0 +1,18 @@
+/**
+ * Sanitize untrusted strings before embedding them into an LLM prompt.
+ *
+ * Threat model (OC-19): attacker-controlled directory names (or other runtime strings)
+ * that contain newline/control characters can break prompt structure and inject
+ * arbitrary instructions.
+ *
+ * Strategy (Option 3 hardening):
+ * - Strip Unicode "control" (Cc) + "format" (Cf) characters (includes CR/LF/NUL, bidi marks, zero-width chars).
+ * - Strip explicit line/paragraph separators (Zl/Zp): U+2028/U+2029.
+ *
+ * Notes:
+ * - This is intentionally lossy; it trades edge-case path fidelity for prompt integrity.
+ * - If you need lossless representation, escape instead of stripping.
+ */
+export function sanitizeForPromptLiteral(value) {
+    return value.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, "");
+}

package/dist/agents/session-dirs.js

@@ -0,0 +1,20 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function resolveAgentSessionDirs(stateDir) {
+    const agentsDir = path.join(stateDir, "agents");
+    let entries = [];
+    try {
+        entries = await fs.readdir(agentsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return [];
+        }
+        throw err;
+    }
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(agentsDir, entry.name, "sessions"))
+        .toSorted((a, b) => a.localeCompare(b));
+}

package/dist/agents/session-write-lock.js

@@ -1,19 +1,89 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-const HELD_LOCKS = new Map();
+import { isPidAlive } from "../shared/pid-alive.js";
+import { resolveProcessScopedMap } from "../shared/process-scoped-map.js";
+const HELD_LOCKS_KEY = Symbol.for("poolbot.sessionWriteLockHeldLocks");
+const WATCHDOG_STATE_KEY = Symbol.for("poolbot.sessionWriteLockWatchdogState");
 const CLEANUP_SIGNALS = ["SIGINT", "SIGTERM", "SIGQUIT", "SIGABRT"];
+const DEFAULT_STALE_MS = 30 * 60 * 1000;
+const DEFAULT_MAX_HOLD_MS = 5 * 60 * 1000;
+const DEFAULT_WATCHDOG_INTERVAL_MS = 60_000;
+const DEFAULT_TIMEOUT_GRACE_MS = 2 * 60 * 1000;
+const MAX_LOCK_HOLD_MS = 2_147_000_000;
 const cleanupHandlers = new Map();
-function isAlive(pid) {
-    if (!Number.isFinite(pid) || pid <= 0)
+const HELD_LOCKS = resolveProcessScopedMap(HELD_LOCKS_KEY);
+function resolveWatchdogState() {
+    const proc = process;
+    if (!proc[WATCHDOG_STATE_KEY]) {
+        proc[WATCHDOG_STATE_KEY] = {
+            started: false,
+            intervalMs: DEFAULT_WATCHDOG_INTERVAL_MS,
+        };
+    }
+    return proc[WATCHDOG_STATE_KEY];
+}
+function resolvePositiveMs(value, fallback, opts = {}) {
+    if (typeof value !== "number" || Number.isNaN(value) || value <= 0) {
+        return fallback;
+    }
+    if (value === Number.POSITIVE_INFINITY) {
+        return opts.allowInfinity ? value : fallback;
+    }
+    if (!Number.isFinite(value)) {
+        return fallback;
+    }
+    return value;
+}
+export function resolveSessionLockMaxHoldFromTimeout(params) {
+    const minMs = resolvePositiveMs(params.minMs, DEFAULT_MAX_HOLD_MS);
+    const timeoutMs = resolvePositiveMs(params.timeoutMs, minMs, { allowInfinity: true });
+    if (timeoutMs === Number.POSITIVE_INFINITY) {
+        return MAX_LOCK_HOLD_MS;
+    }
+    const graceMs = resolvePositiveMs(params.graceMs, DEFAULT_TIMEOUT_GRACE_MS);
+    return Math.min(MAX_LOCK_HOLD_MS, Math.max(minMs, timeoutMs + graceMs));
+}
+async function releaseHeldLock(normalizedSessionFile, held, opts = {}) {
+    const current = HELD_LOCKS.get(normalizedSessionFile);
+    if (current !== held) {
         return false;
-    try {
-        process.kill(pid, 0);
+    }
+    if (opts.force) {
+        held.count = 0;
+    }
+    else {
+        held.count -= 1;
+        if (held.count > 0) {
+            return false;
+        }
+    }
+    if (held.releasePromise) {
+        await held.releasePromise.catch(() => undefined);
         return true;
     }
-    catch {
-        return false;
+    HELD_LOCKS.delete(normalizedSessionFile);
+    held.releasePromise = (async () => {
+        try {
+            await held.handle.close();
+        }
+        catch {
+            // Ignore errors during cleanup - best effort.
+        }
+        try {
+            await fs.rm(held.lockPath, { force: true });
+        }
+        catch {
+            // Ignore errors during cleanup - best effort.
+        }
+    })();
+    try {
+        await held.releasePromise;
     }
+    finally {
+        held.releasePromise = undefined;
+    }
+    return true;
 }
 /**
  * Synchronously release all held locks.
@@ -74,24 +144,127 @@ function registerCleanupHandlers() {
         }
     }
 }
+async function runLockWatchdogCheck(nowMs = Date.now()) {
+    let released = 0;
+    for (const [sessionFile, held] of HELD_LOCKS.entries()) {
+        const heldForMs = nowMs - held.acquiredAt;
+        if (heldForMs <= held.maxHoldMs) {
+            continue;
+        }
+        // eslint-disable-next-line no-console
+        console.warn(`[session-write-lock] releasing lock held for ${heldForMs}ms (max=${held.maxHoldMs}ms): ${held.lockPath}`);
+        const didRelease = await releaseHeldLock(sessionFile, held, { force: true });
+        if (didRelease) {
+            released += 1;
+        }
+    }
+    return released;
+}
+function ensureWatchdogStarted(intervalMs) {
+    const watchdogState = resolveWatchdogState();
+    if (watchdogState.started) {
+        return;
+    }
+    watchdogState.started = true;
+    watchdogState.intervalMs = intervalMs;
+    watchdogState.timer = setInterval(() => {
+        void runLockWatchdogCheck().catch(() => {
+            // Ignore watchdog errors - best effort cleanup only.
+        });
+    }, intervalMs);
+    watchdogState.timer.unref?.();
+}
 async function readLockPayload(lockPath) {
     try {
         const raw = await fs.readFile(lockPath, "utf8");
         const parsed = JSON.parse(raw);
-        if (typeof parsed.pid !== "number")
-            return null;
-        if (typeof parsed.createdAt !== "string")
-            return null;
-        return { pid: parsed.pid, createdAt: parsed.createdAt };
+        const payload = {};
+        if (typeof parsed.pid === "number") {
+            payload.pid = parsed.pid;
+        }
+        if (typeof parsed.createdAt === "string") {
+            payload.createdAt = parsed.createdAt;
+        }
+        return payload;
     }
     catch {
         return null;
     }
 }
+function inspectLockPayload(payload, staleMs, nowMs) {
+    const pid = typeof payload?.pid === "number" ? payload.pid : null;
+    const pidAlive = pid !== null ? isPidAlive(pid) : false;
+    const createdAt = typeof payload?.createdAt === "string" ? payload.createdAt : null;
+    const createdAtMs = createdAt ? Date.parse(createdAt) : Number.NaN;
+    const ageMs = Number.isFinite(createdAtMs) ? Math.max(0, nowMs - createdAtMs) : null;
+    const staleReasons = [];
+    if (pid === null) {
+        staleReasons.push("missing-pid");
+    }
+    else if (!pidAlive) {
+        staleReasons.push("dead-pid");
+    }
+    if (ageMs === null) {
+        staleReasons.push("invalid-createdAt");
+    }
+    else if (ageMs > staleMs) {
+        staleReasons.push("too-old");
+    }
+    return {
+        pid,
+        pidAlive,
+        createdAt,
+        ageMs,
+        stale: staleReasons.length > 0,
+        staleReasons,
+    };
+}
+export async function cleanStaleLockFiles(params) {
+    const sessionsDir = path.resolve(params.sessionsDir);
+    const staleMs = resolvePositiveMs(params.staleMs, DEFAULT_STALE_MS);
+    const removeStale = params.removeStale !== false;
+    const nowMs = params.nowMs ?? Date.now();
+    let entries = [];
+    try {
+        entries = await fs.readdir(sessionsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return { locks: [], cleaned: [] };
+        }
+        throw err;
+    }
+    const locks = [];
+    const cleaned = [];
+    const lockEntries = entries
+        .filter((entry) => entry.name.endsWith(".jsonl.lock"))
+        .toSorted((a, b) => a.name.localeCompare(b.name));
+    for (const entry of lockEntries) {
+        const lockPath = path.join(sessionsDir, entry.name);
+        const payload = await readLockPayload(lockPath);
+        const inspected = inspectLockPayload(payload, staleMs, nowMs);
+        const lockInfo = {
+            lockPath,
+            ...inspected,
+            removed: false,
+        };
+        if (lockInfo.stale && removeStale) {
+            await fs.rm(lockPath, { force: true });
+            lockInfo.removed = true;
+            cleaned.push(lockInfo);
+            params.log?.warn?.(`removed stale session lock: ${lockPath} (${lockInfo.staleReasons.join(", ") || "unknown"})`);
+        }
+        locks.push(lockInfo);
+    }
+    return { locks, cleaned };
+}
 export async function acquireSessionWriteLock(params) {
     registerCleanupHandlers();
-    const timeoutMs = params.timeoutMs ?? 10_000;
-    const staleMs = params.staleMs ?? 30 * 60 * 1000;
+    ensureWatchdogStarted(DEFAULT_WATCHDOG_INTERVAL_MS);
+    const timeoutMs = resolvePositiveMs(params.timeoutMs, 10_000, { allowInfinity: true });
+    const staleMs = resolvePositiveMs(params.staleMs, DEFAULT_STALE_MS);
+    const maxHoldMs = resolvePositiveMs(params.maxHoldMs, DEFAULT_MAX_HOLD_MS);
     const sessionFile = path.resolve(params.sessionFile);
     const sessionDir = path.dirname(sessionFile);
     await fs.mkdir(sessionDir, { recursive: true });
@@ -109,15 +282,7 @@ export async function acquireSessionWriteLock(params) {
         held.count += 1;
         return {
             release: async () => {
-                const current = HELD_LOCKS.get(normalizedSessionFile);
-                if (!current)
-                    return;
-                current.count -= 1;
-                if (current.count > 0)
-                    return;
-                HELD_LOCKS.delete(normalizedSessionFile);
-                await current.handle.close();
-                await fs.rm(current.lockPath, { force: true });
+                await releaseHeldLock(normalizedSessionFile, held);
             },
         };
     }
@@ -127,19 +292,19 @@ export async function acquireSessionWriteLock(params) {
         attempt += 1;
         try {
             const handle = await fs.open(lockPath, "wx");
-            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }, null, 2), "utf8");
-            HELD_LOCKS.set(normalizedSessionFile, { count: 1, handle, lockPath });
+            const createdAt = new Date().toISOString();
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt }, null, 2), "utf8");
+            const createdHeld = {
+                count: 1,
+                handle,
+                lockPath,
+                acquiredAt: Date.now(),
+                maxHoldMs,
+            };
+            HELD_LOCKS.set(normalizedSessionFile, createdHeld);
             return {
                 release: async () => {
-                    const current = HELD_LOCKS.get(normalizedSessionFile);
-                    if (!current)
-                        return;
-                    current.count -= 1;
-                    if (current.count > 0)
-                        return;
-                    HELD_LOCKS.delete(normalizedSessionFile);
-                    await current.handle.close();
-                    await fs.rm(current.lockPath, { force: true });
+                    await releaseHeldLock(normalizedSessionFile, createdHeld);
                 },
             };
         }
@@ -148,10 +313,8 @@ export async function acquireSessionWriteLock(params) {
             if (code !== "EEXIST")
                 throw err;
             const payload = await readLockPayload(lockPath);
-            const createdAt = payload?.createdAt ? Date.parse(payload.createdAt) : NaN;
-            const stale = !Number.isFinite(createdAt) || Date.now() - createdAt > staleMs;
-            const alive = payload?.pid ? isAlive(payload.pid) : false;
-            if (stale || !alive) {
+            const inspected = inspectLockPayload(payload, staleMs, Date.now());
+            if (inspected.stale) {
                 await fs.rm(lockPath, { force: true });
                 continue;
             }
@@ -160,11 +323,12 @@ export async function acquireSessionWriteLock(params) {
         }
     }
     const payload = await readLockPayload(lockPath);
-    const owner = payload?.pid ? `pid=${payload.pid}` : "unknown";
+    const owner = typeof payload?.pid === "number" ? `pid=${payload.pid}` : "unknown";
     throw new Error(`session file locked (timeout ${timeoutMs}ms): ${owner} ${lockPath}`);
 }
 export const __testing = {
     cleanupSignals: [...CLEANUP_SIGNALS],
     handleTerminationSignal,
     releaseAllLocksSync,
+    runLockWatchdogCheck,
 };

package/dist/agents/skills/filter.js

@@ -0,0 +1,24 @@
+export function normalizeSkillFilter(skillFilter) {
+    if (skillFilter === undefined) {
+        return undefined;
+    }
+    return skillFilter.map((entry) => String(entry).trim()).filter(Boolean);
+}
+export function normalizeSkillFilterForComparison(skillFilter) {
+    const normalized = normalizeSkillFilter(skillFilter);
+    if (normalized === undefined) {
+        return undefined;
+    }
+    return Array.from(new Set(normalized)).toSorted();
+}
+export function matchesSkillFilter(cached, next) {
+    const cachedNormalized = normalizeSkillFilterForComparison(cached);
+    const nextNormalized = normalizeSkillFilterForComparison(next);
+    if (cachedNormalized === undefined || nextNormalized === undefined) {
+        return cachedNormalized === nextNormalized;
+    }
+    if (cachedNormalized.length !== nextNormalized.length) {
+        return false;
+    }
+    return cachedNormalized.every((entry, index) => entry === nextNormalized[index]);
+}

package/dist/agents/skills/tools-dir.js

@@ -0,0 +1,9 @@
+import path from "node:path";
+import { safePathSegmentHashed } from "../../infra/install-safe-path.js";
+import { resolveConfigDir } from "../../utils.js";
+import { resolveSkillKey } from "./frontmatter.js";
+export function resolveSkillToolsRootDir(entry) {
+    const key = resolveSkillKey(entry.skill, entry);
+    const safeKey = safePathSegmentHashed(key);
+    return path.join(resolveConfigDir(), "tools", safeKey);
+}