@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/infra/exec-safe-bin-policy.js

@@ -0,0 +1,277 @@
+import { parseExecArgvToken } from "./exec-approvals-analysis.js";
+function isPathLikeToken(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (trimmed === "-") {
+        return false;
+    }
+    if (trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("~")) {
+        return true;
+    }
+    if (trimmed.startsWith("/")) {
+        return true;
+    }
+    return /^[A-Za-z]:[\\/]/.test(trimmed);
+}
+function hasGlobToken(value) {
+    // Safe bins are stdin-only; globbing is both surprising and a historical bypass vector.
+    // Note: we still harden execution-time expansion separately.
+    return /[*?[\]]/.test(value);
+}
+const NO_FLAGS = new Set();
+const toFlagSet = (flags) => {
+    if (!flags || flags.length === 0) {
+        return NO_FLAGS;
+    }
+    return new Set(flags);
+};
+function compileSafeBinProfile(fixture) {
+    return {
+        minPositional: fixture.minPositional,
+        maxPositional: fixture.maxPositional,
+        allowedValueFlags: toFlagSet(fixture.allowedValueFlags),
+        deniedFlags: toFlagSet(fixture.deniedFlags),
+    };
+}
+function compileSafeBinProfiles(fixtures) {
+    return Object.fromEntries(Object.entries(fixtures).map(([name, fixture]) => [name, compileSafeBinProfile(fixture)]));
+}
+export const SAFE_BIN_GENERIC_PROFILE_FIXTURE = {};
+export const SAFE_BIN_PROFILE_FIXTURES = {
+    jq: {
+        maxPositional: 1,
+        allowedValueFlags: ["--arg", "--argjson", "--argstr"],
+        deniedFlags: [
+            "--argfile",
+            "--rawfile",
+            "--slurpfile",
+            "--from-file",
+            "--library-path",
+            "-L",
+            "-f",
+        ],
+    },
+    grep: {
+        // Keep grep stdin-only: pattern must come from -e/--regexp.
+        // Allowing one positional is ambiguous because -e consumes the pattern and
+        // frees the positional slot for a filename.
+        maxPositional: 0,
+        allowedValueFlags: [
+            "--regexp",
+            "--max-count",
+            "--after-context",
+            "--before-context",
+            "--context",
+            "--devices",
+            "--binary-files",
+            "--exclude",
+            "--include",
+            "--label",
+            "-e",
+            "-m",
+            "-A",
+            "-B",
+            "-C",
+            "-D",
+        ],
+        deniedFlags: [
+            "--file",
+            "--exclude-from",
+            "--dereference-recursive",
+            "--directories",
+            "--recursive",
+            "-f",
+            "-d",
+            "-r",
+            "-R",
+        ],
+    },
+    cut: {
+        maxPositional: 0,
+        allowedValueFlags: [
+            "--bytes",
+            "--characters",
+            "--fields",
+            "--delimiter",
+            "--output-delimiter",
+            "-b",
+            "-c",
+            "-f",
+            "-d",
+        ],
+    },
+    sort: {
+        maxPositional: 0,
+        allowedValueFlags: [
+            "--key",
+            "--field-separator",
+            "--buffer-size",
+            "--temporary-directory",
+            "--parallel",
+            "--batch-size",
+            "--random-source",
+            "-k",
+            "-t",
+            "-S",
+            "-T",
+        ],
+        // --compress-program can invoke an external executable and breaks stdin-only guarantees.
+        deniedFlags: ["--compress-program", "--files0-from", "--output", "-o"],
+    },
+    uniq: {
+        maxPositional: 0,
+        allowedValueFlags: [
+            "--skip-fields",
+            "--skip-chars",
+            "--check-chars",
+            "--group",
+            "-f",
+            "-s",
+            "-w",
+        ],
+    },
+    head: {
+        maxPositional: 0,
+        allowedValueFlags: ["--lines", "--bytes", "-n", "-c"],
+    },
+    tail: {
+        maxPositional: 0,
+        allowedValueFlags: [
+            "--lines",
+            "--bytes",
+            "--sleep-interval",
+            "--max-unchanged-stats",
+            "--pid",
+            "-n",
+            "-c",
+        ],
+    },
+    tr: {
+        minPositional: 1,
+        maxPositional: 2,
+    },
+    wc: {
+        maxPositional: 0,
+        deniedFlags: ["--files0-from"],
+    },
+};
+export const SAFE_BIN_GENERIC_PROFILE = compileSafeBinProfile(SAFE_BIN_GENERIC_PROFILE_FIXTURE);
+export const SAFE_BIN_PROFILES = compileSafeBinProfiles(SAFE_BIN_PROFILE_FIXTURES);
+export function resolveSafeBinDeniedFlags(fixtures = SAFE_BIN_PROFILE_FIXTURES) {
+    const out = {};
+    for (const [name, fixture] of Object.entries(fixtures)) {
+        const denied = Array.from(new Set(fixture.deniedFlags ?? [])).toSorted();
+        if (denied.length > 0) {
+            out[name] = denied;
+        }
+    }
+    return out;
+}
+export function renderSafeBinDeniedFlagsDocBullets(fixtures = SAFE_BIN_PROFILE_FIXTURES) {
+    const deniedByBin = resolveSafeBinDeniedFlags(fixtures);
+    const bins = Object.keys(deniedByBin).toSorted();
+    return bins
+        .map((bin) => `- \`${bin}\`: ${deniedByBin[bin].map((flag) => `\`${flag}\``).join(", ")}`)
+        .join("\n");
+}
+function isSafeLiteralToken(value) {
+    if (!value || value === "-") {
+        return true;
+    }
+    return !hasGlobToken(value) && !isPathLikeToken(value);
+}
+function isInvalidValueToken(value) {
+    return !value || !isSafeLiteralToken(value);
+}
+function consumeLongOptionToken(args, index, flag, inlineValue, allowedValueFlags, deniedFlags) {
+    if (deniedFlags.has(flag)) {
+        return -1;
+    }
+    if (inlineValue !== undefined) {
+        return isSafeLiteralToken(inlineValue) ? index + 1 : -1;
+    }
+    if (!allowedValueFlags.has(flag)) {
+        return index + 1;
+    }
+    return isInvalidValueToken(args[index + 1]) ? -1 : index + 2;
+}
+function consumeShortOptionClusterToken(args, index, raw, cluster, flags, allowedValueFlags, deniedFlags) {
+    for (let j = 0; j < flags.length; j += 1) {
+        const flag = flags[j];
+        if (deniedFlags.has(flag)) {
+            return -1;
+        }
+        if (!allowedValueFlags.has(flag)) {
+            continue;
+        }
+        const inlineValue = cluster.slice(j + 1);
+        if (inlineValue) {
+            return isSafeLiteralToken(inlineValue) ? index + 1 : -1;
+        }
+        return isInvalidValueToken(args[index + 1]) ? -1 : index + 2;
+    }
+    return hasGlobToken(raw) ? -1 : index + 1;
+}
+function consumePositionalToken(token, positional) {
+    if (!isSafeLiteralToken(token)) {
+        return false;
+    }
+    positional.push(token);
+    return true;
+}
+function validatePositionalCount(positional, profile) {
+    const minPositional = profile.minPositional ?? 0;
+    if (positional.length < minPositional) {
+        return false;
+    }
+    return typeof profile.maxPositional !== "number" || positional.length <= profile.maxPositional;
+}
+export function validateSafeBinArgv(args, profile) {
+    const allowedValueFlags = profile.allowedValueFlags ?? NO_FLAGS;
+    const deniedFlags = profile.deniedFlags ?? NO_FLAGS;
+    const positional = [];
+    let i = 0;
+    while (i < args.length) {
+        const rawToken = args[i] ?? "";
+        const token = parseExecArgvToken(rawToken);
+        if (token.kind === "empty" || token.kind === "stdin") {
+            i += 1;
+            continue;
+        }
+        if (token.kind === "terminator") {
+            for (let j = i + 1; j < args.length; j += 1) {
+                const rest = args[j];
+                if (!rest || rest === "-") {
+                    continue;
+                }
+                if (!consumePositionalToken(rest, positional)) {
+                    return false;
+                }
+            }
+            break;
+        }
+        if (token.kind === "positional") {
+            if (!consumePositionalToken(token.raw, positional)) {
+                return false;
+            }
+            i += 1;
+            continue;
+        }
+        if (token.style === "long") {
+            const nextIndex = consumeLongOptionToken(args, i, token.flag, token.inlineValue, allowedValueFlags, deniedFlags);
+            if (nextIndex < 0) {
+                return false;
+            }
+            i = nextIndex;
+            continue;
+        }
+        const nextIndex = consumeShortOptionClusterToken(args, i, token.raw, token.cluster, token.flags, allowedValueFlags, deniedFlags);
+        if (nextIndex < 0) {
+            return false;
+        }
+        i = nextIndex;
+    }
+    return validatePositionalCount(positional, profile);
+}

package/dist/infra/fixed-window-rate-limit.js

@@ -0,0 +1,33 @@
+export function createFixedWindowRateLimiter(params) {
+    const maxRequests = Math.max(1, Math.floor(params.maxRequests));
+    const windowMs = Math.max(1, Math.floor(params.windowMs));
+    const now = params.now ?? Date.now;
+    let count = 0;
+    let windowStartMs = 0;
+    return {
+        consume() {
+            const nowMs = now();
+            if (nowMs - windowStartMs >= windowMs) {
+                windowStartMs = nowMs;
+                count = 0;
+            }
+            if (count >= maxRequests) {
+                return {
+                    allowed: false,
+                    retryAfterMs: Math.max(0, windowStartMs + windowMs - nowMs),
+                    remaining: 0,
+                };
+            }
+            count += 1;
+            return {
+                allowed: true,
+                retryAfterMs: 0,
+                remaining: Math.max(0, maxRequests - count),
+            };
+        },
+        reset() {
+            count = 0;
+            windowStartMs = 0;
+        },
+    };
+}

package/dist/infra/fs-safe.js

@@ -1,76 +1,108 @@
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path-guards.js";
 export class SafeOpenError extends Error {
     code;
-    constructor(code, message) {
-        super(message);
+    constructor(code, message, options) {
+        super(message, options);
         this.code = code;
         this.name = "SafeOpenError";
     }
 }
-const NOT_FOUND_CODES = new Set(["ENOENT", "ENOTDIR"]);
+const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
+const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 const ensureTrailingSep = (value) => (value.endsWith(path.sep) ? value : value + path.sep);
-const isNodeError = (err) => Boolean(err && typeof err === "object" && "code" in err);
-const isNotFoundError = (err) => isNodeError(err) && typeof err.code === "string" && NOT_FOUND_CODES.has(err.code);
-const isSymlinkOpenError = (err) => isNodeError(err) && (err.code === "ELOOP" || err.code === "EINVAL" || err.code === "ENOTSUP");
-export async function openFileWithinRoot(params) {
-    let rootReal;
-    try {
-        rootReal = await fs.realpath(params.rootDir);
-    }
-    catch (err) {
-        if (isNotFoundError(err)) {
-            throw new SafeOpenError("not-found", "root dir not found");
-        }
-        throw err;
-    }
-    const rootWithSep = ensureTrailingSep(rootReal);
-    const resolved = path.resolve(rootWithSep, params.relativePath);
-    if (!resolved.startsWith(rootWithSep)) {
-        throw new SafeOpenError("invalid-path", "path escapes root");
-    }
-    const supportsNoFollow = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
-    const flags = fsConstants.O_RDONLY | (supportsNoFollow ? fsConstants.O_NOFOLLOW : 0);
+async function openVerifiedLocalFile(filePath) {
     let handle;
     try {
-        handle = await fs.open(resolved, flags);
+        handle = await fs.open(filePath, OPEN_READ_FLAGS);
     }
     catch (err) {
-        if (isNotFoundError(err)) {
+        if (isNotFoundPathError(err)) {
             throw new SafeOpenError("not-found", "file not found");
         }
         if (isSymlinkOpenError(err)) {
-            throw new SafeOpenError("invalid-path", "symlink open blocked");
+            throw new SafeOpenError("symlink", "symlink open blocked", { cause: err });
         }
         throw err;
     }
     try {
-        const lstat = await fs.lstat(resolved).catch(() => null);
-        if (lstat?.isSymbolicLink()) {
-            throw new SafeOpenError("invalid-path", "symlink not allowed");
-        }
-        const realPath = await fs.realpath(resolved);
-        if (!realPath.startsWith(rootWithSep)) {
-            throw new SafeOpenError("invalid-path", "path escapes root");
+        const [stat, lstat] = await Promise.all([handle.stat(), fs.lstat(filePath)]);
+        if (lstat.isSymbolicLink()) {
+            throw new SafeOpenError("symlink", "symlink not allowed");
         }
-        const stat = await handle.stat();
         if (!stat.isFile()) {
-            throw new SafeOpenError("invalid-path", "not a file");
+            throw new SafeOpenError("not-file", "not a file");
         }
+        if (stat.ino !== lstat.ino || stat.dev !== lstat.dev) {
+            throw new SafeOpenError("path-mismatch", "path changed during read");
+        }
+        const realPath = await fs.realpath(filePath);
         const realStat = await fs.stat(realPath);
         if (stat.ino !== realStat.ino || stat.dev !== realStat.dev) {
-            throw new SafeOpenError("invalid-path", "path mismatch");
+            throw new SafeOpenError("path-mismatch", "path mismatch");
         }
         return { handle, realPath, stat };
     }
     catch (err) {
         await handle.close().catch(() => { });
-        if (err instanceof SafeOpenError)
+        if (err instanceof SafeOpenError) {
             throw err;
-        if (isNotFoundError(err)) {
+        }
+        if (isNotFoundPathError(err)) {
             throw new SafeOpenError("not-found", "file not found");
         }
         throw err;
     }
 }
+export async function openFileWithinRoot(params) {
+    let rootReal;
+    try {
+        rootReal = await fs.realpath(params.rootDir);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            throw new SafeOpenError("not-found", "root dir not found");
+        }
+        throw err;
+    }
+    const rootWithSep = ensureTrailingSep(rootReal);
+    const resolved = path.resolve(rootWithSep, params.relativePath);
+    if (!isPathInside(rootWithSep, resolved)) {
+        throw new SafeOpenError("invalid-path", "path escapes root");
+    }
+    let opened;
+    try {
+        opened = await openVerifiedLocalFile(resolved);
+    }
+    catch (err) {
+        if (err instanceof SafeOpenError) {
+            if (err.code === "not-found") {
+                throw err;
+            }
+            throw new SafeOpenError("invalid-path", "path is not a regular file under root", {
+                cause: err,
+            });
+        }
+        throw err;
+    }
+    if (!isPathInside(rootWithSep, opened.realPath)) {
+        await opened.handle.close().catch(() => { });
+        throw new SafeOpenError("invalid-path", "path escapes root");
+    }
+    return opened;
+}
+export async function readLocalFileSafely(params) {
+    const opened = await openVerifiedLocalFile(params.filePath);
+    try {
+        if (params.maxBytes !== undefined && opened.stat.size > params.maxBytes) {
+            throw new SafeOpenError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${opened.stat.size})`);
+        }
+        const buffer = await opened.handle.readFile();
+        return { buffer, realPath: opened.realPath, stat: opened.stat };
+    }
+    finally {
+        await opened.handle.close().catch(() => { });
+    }
+}

package/dist/infra/gateway-lock.js

@@ -118,7 +118,7 @@ async function readLockPayload(lockPath) {
 function resolveGatewayLockPath(env) {
     const stateDir = resolveStateDir(env);
     const configPath = resolveConfigPath(env, stateDir);
-    const hash = createHash("sha1").update(configPath).digest("hex").slice(0, 8);
+    const hash = createHash("sha256").update(configPath).digest("hex").slice(0, 8);
     const lockDir = resolveGatewayLockDir();
     const lockPath = path.join(lockDir, `gateway.${hash}.lock`);
     return { lockPath, configPath };
@@ -186,7 +186,11 @@ export async function acquireGatewayLock(opts = {}) {
                         stale = Date.now() - st.mtimeMs > staleMs;
                     }
                     catch {
-                        stale = true;
+                        // On Windows or locked filesystems we may be unable to stat the
+                        // lock file even though the existing gateway is still healthy.
+                        // Treat the lock as non-stale so we keep waiting instead of
+                        // forcefully removing another gateway's lock.
+                        stale = false;
                     }
                 }
                 if (stale) {

package/dist/infra/git-root.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+export const DEFAULT_GIT_DISCOVERY_MAX_DEPTH = 12;
+function walkUpFrom(startDir, opts, resolveAtDir) {
+    let current = path.resolve(startDir);
+    const maxDepth = opts.maxDepth ?? DEFAULT_GIT_DISCOVERY_MAX_DEPTH;
+    for (let i = 0; i < maxDepth; i += 1) {
+        const resolved = resolveAtDir(current);
+        if (resolved !== null && resolved !== undefined) {
+            return resolved;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+function hasGitMarker(repoRoot) {
+    const gitPath = path.join(repoRoot, ".git");
+    try {
+        const stat = fs.statSync(gitPath);
+        return stat.isDirectory() || stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function findGitRoot(startDir, opts = {}) {
+    // A `.git` file counts as a repo marker even if it is not a valid gitdir pointer.
+    return walkUpFrom(startDir, opts, (repoRoot) => (hasGitMarker(repoRoot) ? repoRoot : null));
+}
+function resolveGitDirFromMarker(repoRoot) {
+    const gitPath = path.join(repoRoot, ".git");
+    try {
+        const stat = fs.statSync(gitPath);
+        if (stat.isDirectory()) {
+            return gitPath;
+        }
+        if (!stat.isFile()) {
+            return null;
+        }
+        const raw = fs.readFileSync(gitPath, "utf-8");
+        const match = raw.match(/gitdir:\s*(.+)/i);
+        if (!match?.[1]) {
+            return null;
+        }
+        return path.resolve(repoRoot, match[1].trim());
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveGitHeadPath(startDir, opts = {}) {
+    // Stricter than findGitRoot: keep walking until a resolvable git dir is found.
+    return walkUpFrom(startDir, opts, (repoRoot) => {
+        const gitDir = resolveGitDirFromMarker(repoRoot);
+        return gitDir ? path.join(gitDir, "HEAD") : null;
+    });
+}

package/dist/infra/heartbeat-active-hours.js

@@ -1,5 +1,5 @@
 import { resolveUserTimezone } from "../agents/date-time.js";
-const ACTIVE_HOURS_TIME_PATTERN = /^([01]\d|2[0-3]|24):([0-5]\d)$/;
+const ACTIVE_HOURS_TIME_PATTERN = /^(?:([01]\d|2[0-3]):([0-5]\d)|24:00)$/;
 function resolveActiveHoursTimezone(cfg, raw) {
     const trimmed = raw?.trim();
     if (!trimmed || trimmed === "user") {
@@ -71,7 +71,7 @@ export function isWithinActiveHours(cfg, heartbeat, nowMs) {
         return true;
     }
     if (startMin === endMin) {
-        return true;
+        return false;
     }
     const timeZone = resolveActiveHoursTimezone(cfg, active.timezone);
     const currentMin = resolveMinutesInTimeZone(nowMs ?? Date.now(), timeZone);

package/dist/infra/heartbeat-reason.js

@@ -0,0 +1,40 @@
+function trimReason(reason) {
+    return typeof reason === "string" ? reason.trim() : "";
+}
+export function normalizeHeartbeatWakeReason(reason) {
+    const trimmed = trimReason(reason);
+    return trimmed.length > 0 ? trimmed : "requested";
+}
+export function resolveHeartbeatReasonKind(reason) {
+    const trimmed = trimReason(reason);
+    if (trimmed === "retry") {
+        return "retry";
+    }
+    if (trimmed === "interval") {
+        return "interval";
+    }
+    if (trimmed === "manual") {
+        return "manual";
+    }
+    if (trimmed === "exec-event") {
+        return "exec-event";
+    }
+    if (trimmed === "wake") {
+        return "wake";
+    }
+    if (trimmed.startsWith("cron:")) {
+        return "cron";
+    }
+    if (trimmed.startsWith("hook:")) {
+        return "hook";
+    }
+    return "other";
+}
+export function isHeartbeatEventDrivenReason(reason) {
+    const kind = resolveHeartbeatReasonKind(reason);
+    return kind === "exec-event" || kind === "cron" || kind === "wake" || kind === "hook";
+}
+export function isHeartbeatActionWakeReason(reason) {
+    const kind = resolveHeartbeatReasonKind(reason);
+    return kind === "manual" || kind === "exec-event" || kind === "hook";
+}