@poolzin/pool-bot 2026.2.10 → 2026.2.17

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/system-prompt.js

@@ -1,5 +1,6 @@
 import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
 import { listDeliverableMessageChannels } from "../utils/message-channel.js";
+import { sanitizeForPromptLiteral } from "./sanitize-for-prompt.js";
 function buildSkillsSection(params) {
     if (params.isMinimal)
         return [];
@@ -66,6 +67,9 @@ function buildMessagingSection(params) {
         "## Messaging",
         "- Reply in current session → automatically routes to the source channel (Signal, Telegram, etc.)",
         "- Cross-session messaging → use sessions_send(sessionKey, message)",
+        "- Sub-agent orchestration → use subagents(action=list|steer|kill)",
+        "- `[System Message] ...` blocks are internal context and are not user-visible by default.",
+        `- If a \`[System Message]\` reports completed cron/subagent work and asks for a user update, rewrite it in your normal assistant voice and send that update (do not forward raw system text or default to ${SILENT_REPLY_TOKEN}).`,
         "- Never use exec/curl for provider messaging; Pool Bot handles all routing internally.",
         params.availableTools.has("message")
             ? [
@@ -76,7 +80,7 @@ function buildMessagingSection(params) {
                 `- If multiple channels are configured, pass \`channel\` (${params.messageChannelOptions}).`,
                 `- If you use \`message\` (\`action=send\`) to deliver your user-visible reply, respond with ONLY: ${SILENT_REPLY_TOKEN} (avoid duplicate replies).`,
                 params.inlineButtonsEnabled
-                    ? "- Inline buttons supported. Use `action=send` with `buttons=[[{text,callback_data}]]` (callback_data routes back as a user message)."
+                    ? "- Inline buttons supported. Use `action=send` with `buttons=[[{text,callback_data,style?}]]`; `style` can be `primary`, `success`, or `danger`."
                     : params.runtimeChannel
                         ? `- Inline buttons not enabled for ${params.runtimeChannel}. If you need them, ask to set ${params.runtimeChannel}.capabilities.inlineButtons ("dm"|"group"|"all"|"allowlist").`
                         : "",
@@ -96,6 +100,22 @@ function buildVoiceSection(params) {
         return [];
     return ["## Voice (TTS)", hint, ""];
 }
+function buildLlmsTxtSection(params) {
+    if (params.isMinimal) {
+        return [];
+    }
+    if (!params.availableTools.has("web_fetch")) {
+        return [];
+    }
+    return [
+        "## llms.txt Discovery",
+        "When exploring a new domain or website (via web_fetch or browser), check for an llms.txt file that describes how AI agents should interact with the site:",
+        "- Try `/llms.txt` or `/.well-known/llms.txt` at the domain root",
+        "- If found, follow its guidance for interacting with that site's content and APIs",
+        "- llms.txt is an emerging standard (like robots.txt for AI) — not all sites have one, so don't warn if missing",
+        "",
+    ];
+}
 function buildDocsSection(params) {
     const docsPath = params.docsPath?.trim();
     if (!docsPath || params.isMinimal)
@@ -137,6 +157,7 @@ export function buildAgentSystemPrompt(params) {
         sessions_history: "Fetch history for another session/sub-agent",
         sessions_send: "Send a message to another session/sub-agent",
         sessions_spawn: "Spawn a sub-agent session",
+        subagents: "List, steer, or kill sub-agent runs for this requester session",
         session_status: "Show a /status-equivalent status card (usage + time + Reasoning/Verbose/Elevated); use for model-use questions (📊 session_status); optional per-session model override",
         image: "Analyze an image with the configured image model",
     };
@@ -162,6 +183,8 @@ export function buildAgentSystemPrompt(params) {
         "sessions_list",
         "sessions_history",
         "sessions_send",
+        "sessions_spawn",
+        "subagents",
         "session_status",
         "image",
     ];
@@ -235,6 +258,17 @@ export function buildAgentSystemPrompt(params) {
     const messageChannelOptions = listDeliverableMessageChannels().join("|");
     const promptMode = params.promptMode ?? "full";
     const isMinimal = promptMode === "minimal" || promptMode === "none";
+    const sandboxContainerWorkspace = params.sandboxInfo?.containerWorkspaceDir?.trim();
+    const sanitizedWorkspaceDir = sanitizeForPromptLiteral(params.workspaceDir);
+    const sanitizedSandboxContainerWorkspace = sandboxContainerWorkspace
+        ? sanitizeForPromptLiteral(sandboxContainerWorkspace)
+        : "";
+    const displayWorkspaceDir = params.sandboxInfo?.enabled && sanitizedSandboxContainerWorkspace
+        ? sanitizedSandboxContainerWorkspace
+        : sanitizedWorkspaceDir;
+    const workspaceGuidance = params.sandboxInfo?.enabled && sanitizedSandboxContainerWorkspace
+        ? `For read/write/edit/apply_patch, file paths resolve against host workspace: ${sanitizedWorkspaceDir}. For bash/exec commands, use sandbox container paths under ${sanitizedSandboxContainerWorkspace} (or relative paths from that workdir), not host paths. Prefer relative paths so both sandboxed exec and file tools work consistently.`
+        : "Treat this directory as the single global workspace for file operations unless explicitly instructed otherwise.";
     const safetySection = [
         "## Safety",
         "You have no independent goals: do not pursue self-preservation, replication, resource acquisition, or power-seeking; avoid long-term plans beyond the user's request.",
@@ -285,10 +319,13 @@ export function buildAgentSystemPrompt(params) {
                 "- sessions_list: list sessions",
                 "- sessions_history: fetch session history",
                 "- sessions_send: send to another session",
+                "- subagents: list/steer/kill sub-agent runs",
                 '- session_status: show usage/time/model state and answer "what model are we using?"',
             ].join("\n"),
         "TOOLS.md does not control tool availability; it is user guidance for how to use external tools.",
-        "If a task is more complex or takes longer, spawn a sub-agent. It will do the work for you and ping you when it's done. You can always check up on it.",
+        `For long waits, avoid rapid poll loops: use ${execToolName} with enough yieldMs or ${processToolName}(action=poll, timeout=<ms>).`,
+        "If a task is more complex or takes longer, spawn a sub-agent. Completion is push-based: it will auto-announce when done.",
+        "Do not poll `subagents list` / `sessions_list` in a loop; only check status on-demand (for intervention, debugging, or when explicitly asked).",
         "",
         "## Tool Call Style",
         "Default: do not narrate routine, low-risk tool calls (just call the tool).",
@@ -335,8 +372,8 @@ export function buildAgentSystemPrompt(params) {
             ? "If you need the current date, time, or day of week, run session_status (📊 session_status)."
             : "",
         "## Workspace",
-        `Your working directory is: ${params.workspaceDir}`,
-        "Treat this directory as the single global workspace for file operations unless explicitly instructed otherwise.",
+        `Your working directory is: ${displayWorkspaceDir}`,
+        workspaceGuidance,
         ...workspaceNotes,
         "",
         ...docsSection,
@@ -346,17 +383,20 @@ export function buildAgentSystemPrompt(params) {
                 "You are running in a sandboxed runtime (tools execute in Docker).",
                 "Some tools may be unavailable due to sandbox policy.",
                 "Sub-agents stay sandboxed (no elevated/host access). Need outside-sandbox read/write? Don't spawn; ask first.",
+                params.sandboxInfo.containerWorkspaceDir
+                    ? `Sandbox container workdir: ${sanitizeForPromptLiteral(params.sandboxInfo.containerWorkspaceDir)}`
+                    : "",
                 params.sandboxInfo.workspaceDir
-                    ? `Sandbox workspace: ${params.sandboxInfo.workspaceDir}`
+                    ? `Sandbox host mount source (file tools bridge only; not valid inside sandbox exec): ${sanitizeForPromptLiteral(params.sandboxInfo.workspaceDir)}`
                     : "",
                 params.sandboxInfo.workspaceAccess
                     ? `Agent workspace access: ${params.sandboxInfo.workspaceAccess}${params.sandboxInfo.agentWorkspaceMount
-                        ? ` (mounted at ${params.sandboxInfo.agentWorkspaceMount})`
+                        ? ` (mounted at ${sanitizeForPromptLiteral(params.sandboxInfo.agentWorkspaceMount)})`
                         : ""}`
                     : "",
                 params.sandboxInfo.browserBridgeUrl ? "Sandbox browser: enabled." : "",
                 params.sandboxInfo.browserNoVncUrl
-                    ? `Sandbox browser observer (noVNC): ${params.sandboxInfo.browserNoVncUrl}`
+                    ? `Sandbox browser observer (noVNC): ${sanitizeForPromptLiteral(params.sandboxInfo.browserNoVncUrl)}`
                     : "",
                 params.sandboxInfo.hostBrowserAllowed === true
                     ? "Host browser control: allowed."
@@ -397,6 +437,7 @@ export function buildAgentSystemPrompt(params) {
             messageToolHints: params.messageToolHints,
         }),
         ...buildVoiceSection({ isMinimal, ttsHint: params.ttsHint }),
+        ...buildLlmsTxtSection({ isMinimal, availableTools }),
     ];
     if (extraSystemPrompt) {
         // Use "Subagent Context" header for minimal mode (subagents), otherwise "Group Chat Context"
@@ -429,8 +470,9 @@ export function buildAgentSystemPrompt(params) {
         lines.push("## Reasoning Format", reasoningHint, "");
     }
     const contextFiles = params.contextFiles ?? [];
-    if (contextFiles.length > 0) {
-        const hasSoulFile = contextFiles.some((file) => {
+    const validContextFiles = contextFiles.filter((file) => typeof file.path === "string" && file.path.trim().length > 0);
+    if (validContextFiles.length > 0) {
+        const hasSoulFile = validContextFiles.some((file) => {
             const normalizedPath = file.path.trim().replace(/\\/g, "/");
             const baseName = normalizedPath.split("/").pop() ?? normalizedPath;
             return baseName.toLowerCase() === "soul.md";
@@ -440,7 +482,7 @@ export function buildAgentSystemPrompt(params) {
             lines.push("If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.");
         }
         lines.push("");
-        for (const file of contextFiles) {
+        for (const file of validContextFiles) {
             lines.push(`## ${file.path}`, "", file.content, "");
         }
     }