@ystemsrx/cfshare 0.1.2 → 0.1.3

package/dist/src/manager.js

@@ -0,0 +1,2251 @@
+import { spawn, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { createReadStream, createWriteStream } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import ignore from "ignore";
+import { lookup as mimeLookup } from "mime-types";
+import yazl from "yazl";
+import { renderFileExplorerTemplate } from "./templates/fileExplorerTemplate.js";
+import { renderMarkdownPreviewTemplate } from "./templates/markdownPreviewTemplate.js";
+import { loadPolicy } from "./policy.js";
+const MAX_LOG_LINES = 4000;
+const MAX_RESPONSE_MANIFEST_ITEMS = 200;
+const MAX_RESPONSE_MANIFEST_ITEMS_MULTI_GET = 20;
+const MAX_EXPOSURE_GET_ITEMS = 200;
+const MAX_EXPOSURE_LOG_ITEMS = 100;
+const MAX_EXPOSURE_LOG_LINES_RESPONSE = 1000;
+const DEFAULT_PROBE_TIMEOUT_MS = 3000;
+const CLOUDFLARE_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com\b/gi;
+const MARKDOWN_PREVIEW_EXTENSIONS = new Set([".md", ".rmd", ".qmd"]);
+const INLINE_TEXT_PREVIEW_EXTENSIONS = new Set([".html", ".htm", ".svg"]);
+const BINARY_MIME_PREFIXES = ["image/", "audio/", "video/", "font/"];
+const BINARY_MIME_EXACT = new Set([
+    "application/pdf",
+    "application/zip",
+    "application/x-zip-compressed",
+    "application/gzip",
+    "application/x-gzip",
+    "application/x-7z-compressed",
+    "application/x-rar-compressed",
+    "application/octet-stream",
+]);
+const INVALID_QUICK_TUNNEL_SUBDOMAINS = new Set(["api"]);
+const WINDOWS_METADATA_SUFFIX_RE = /:zone\.identifier$/i;
+function nowIso() {
+    return toLocalIso(new Date());
+}
+function toLocalIso(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    const hours = String(date.getHours()).padStart(2, "0");
+    const minutes = String(date.getMinutes()).padStart(2, "0");
+    const seconds = String(date.getSeconds()).padStart(2, "0");
+    const millis = String(date.getMilliseconds()).padStart(3, "0");
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const absOffsetMinutes = Math.abs(offsetMinutes);
+    const offsetHours = String(Math.trunc(absOffsetMinutes / 60)).padStart(2, "0");
+    const offsetMins = String(absOffsetMinutes % 60).padStart(2, "0");
+    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${millis}${sign}${offsetHours}:${offsetMins}`;
+}
+function timestampMs(input) {
+    if (!input) {
+        return undefined;
+    }
+    const ms = Date.parse(input);
+    return Number.isFinite(ms) ? ms : undefined;
+}
+function randomId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${crypto.randomBytes(3).toString("hex")}`;
+}
+function maskSecret(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value.length <= 6) {
+        return "*".repeat(value.length);
+    }
+    return `${value.slice(0, 3)}***${value.slice(-2)}`;
+}
+function isSubPath(target, base) {
+    const rel = path.relative(base, target);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function normalizePathForIgnore(input) {
+    const normalized = input.split(path.sep).join("/");
+    if (!normalized || normalized === "." || normalized === "..") {
+        return undefined;
+    }
+    if (normalized.startsWith("/") ||
+        normalized.startsWith("../") ||
+        normalized.includes("/../") ||
+        normalized.endsWith("/..")) {
+        return undefined;
+    }
+    return normalized.replace(/^\.\/+/, "");
+}
+function getIgnoreMatchCandidates(realPath) {
+    const candidates = new Set();
+    const relToCwd = normalizePathForIgnore(path.relative(process.cwd(), realPath));
+    const relToRoot = normalizePathForIgnore(path.relative(path.parse(realPath).root, realPath));
+    const baseName = normalizePathForIgnore(path.basename(realPath));
+    if (relToCwd) {
+        candidates.add(relToCwd);
+    }
+    if (relToRoot) {
+        candidates.add(relToRoot);
+    }
+    if (baseName) {
+        candidates.add(baseName);
+    }
+    return Array.from(candidates);
+}
+function normalizeAllowlistPaths(values) {
+    if (!values) {
+        return [];
+    }
+    const out = values
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => (entry.startsWith("/") ? entry : `/${entry}`));
+    return Array.from(new Set(out));
+}
+function normalizeAccessMode(value, fallback) {
+    if (value === "token" || value === "basic" || value === "none") {
+        return value;
+    }
+    return fallback;
+}
+function normalizeTtl(value, policy) {
+    const n = typeof value === "number" ? Math.trunc(value) : policy.defaultTtlSeconds;
+    return Math.max(60, Math.min(policy.maxTtlSeconds, n));
+}
+function normalizeFilePresentation(value) {
+    if (value === "preview" || value === "raw" || value === "download") {
+        return value;
+    }
+    return "download";
+}
+function parseRequestedPresentation(input) {
+    if (input === "preview" || input === "raw" || input === "download") {
+        return input;
+    }
+    return undefined;
+}
+function resolveRequestPresentation(url, fallback) {
+    const requested = parseRequestedPresentation(ensureString(url.searchParams.get("delivery"))) ??
+        parseRequestedPresentation(ensureString(url.searchParams.get("presentation"))) ??
+        parseRequestedPresentation(ensureString(url.searchParams.get("view")));
+    return requested ?? fallback;
+}
+function normalizeWorkspaceRelativePath(input) {
+    if (!input) {
+        return undefined;
+    }
+    const normalized = input.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!normalized || normalized === ".") {
+        return undefined;
+    }
+    const safe = path.posix.normalize(normalized);
+    if (!safe || safe === "." || safe === ".." || safe.startsWith("../") || safe.includes("/../")) {
+        return undefined;
+    }
+    return safe;
+}
+function sanitizeFilename(input) {
+    // Keep Unicode to preserve original filenames, but replace characters that are
+    // invalid or problematic across common filesystems (Windows in particular).
+    // We only sanitize a single path segment (basename), not a full path.
+    //
+    // Reference set:
+    // - ASCII control chars: 0x00-0x1F and 0x7F
+    // - Windows reserved: <>:"/\\|?*
+    // - Trailing dots/spaces are invalid on Windows
+    const cleaned = input
+        .replace(/[\u0000-\u001F\u007F]/g, "_")
+        .replace(/[<>:"/\\|?*]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/[. ]+$/g, "_");
+    const trimmed = cleaned.trim();
+    return trimmed || "item";
+}
+function ensureString(input) {
+    if (typeof input !== "string") {
+        return undefined;
+    }
+    const trimmed = input.trim();
+    return trimmed || undefined;
+}
+function buildContentDisposition(params) {
+    if (params.mode === "raw") {
+        return undefined;
+    }
+    const verb = params.mode === "preview" ? "inline" : "attachment";
+    const filename = params.downloadName ?? path.basename(params.filePath);
+    return `${verb}; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
+function isTextLikeMime(mime) {
+    const base = mime.split(";")[0]?.trim().toLowerCase() ?? "";
+    if (!base) {
+        return false;
+    }
+    if (base.startsWith("text/")) {
+        return true;
+    }
+    if (base.endsWith("+json") || base.endsWith("+xml")) {
+        return true;
+    }
+    return (base === "application/json" ||
+        base === "application/xml" ||
+        base === "application/javascript" ||
+        base === "application/x-javascript" ||
+        base === "application/typescript" ||
+        base === "application/x-typescript" ||
+        base === "application/yaml" ||
+        base === "application/x-yaml" ||
+        base === "application/toml" ||
+        base === "application/graphql" ||
+        base === "application/sql");
+}
+function isLikelyBinaryMime(mime) {
+    const base = mime.split(";")[0]?.trim().toLowerCase() ?? "";
+    if (!base) {
+        return false;
+    }
+    if (isTextLikeMime(base)) {
+        return false;
+    }
+    if (BINARY_MIME_EXACT.has(base)) {
+        return true;
+    }
+    return BINARY_MIME_PREFIXES.some((prefix) => base.startsWith(prefix));
+}
+async function sniffFileSample(filePath, maxBytes = 8192) {
+    const handle = await fs.open(filePath, "r");
+    try {
+        const buf = Buffer.alloc(maxBytes);
+        const { bytesRead } = await handle.read(buf, 0, maxBytes, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function isLikelyTextBuffer(sample) {
+    if (sample.length === 0) {
+        return true;
+    }
+    for (const byte of sample) {
+        if (byte === 0) {
+            return false;
+        }
+    }
+    let suspicious = 0;
+    for (const byte of sample) {
+        if (byte === 9 || byte === 10 || byte === 13) {
+            continue;
+        }
+        if (byte < 32 || byte === 127) {
+            suspicious += 1;
+        }
+    }
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(sample);
+        return suspicious / sample.length < 0.2;
+    }
+    catch {
+        return suspicious / sample.length < 0.05;
+    }
+}
+async function detectFileDeliveryCapabilities(params) {
+    const ext = path.extname(params.filePath).toLowerCase();
+    const mimeBase = params.mime.split(";")[0]?.trim().toLowerCase() ?? "";
+    const likelyBinaryByMime = isLikelyBinaryMime(params.mime);
+    const sample = await sniffFileSample(params.filePath);
+    const textByContent = isLikelyTextBuffer(sample);
+    const isBinary = sample.length > 0 ? !textByContent : likelyBinaryByMime;
+    const imagePreviewByMime = mimeBase.startsWith("image/");
+    const imagePreviewByExt = [
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".gif",
+        ".webp",
+        ".bmp",
+        ".tif",
+        ".tiff",
+        ".ico",
+        ".heic",
+        ".svg",
+    ].includes(ext);
+    const mediaPreviewByMime = mimeBase.startsWith("audio/") || mimeBase.startsWith("video/");
+    const mediaPreviewByExt = [
+        ".mp3",
+        ".wav",
+        ".flac",
+        ".ogg",
+        ".m4a",
+        ".aac",
+        ".mp4",
+        ".mov",
+        ".webm",
+        ".m4v",
+    ].includes(ext);
+    const previewSupported = (isBinary &&
+        (ext === ".pdf" ||
+            mimeBase === "application/pdf" ||
+            imagePreviewByMime ||
+            imagePreviewByExt ||
+            mediaPreviewByMime ||
+            mediaPreviewByExt)) ||
+        (!isBinary && (MARKDOWN_PREVIEW_EXTENSIONS.has(ext) || INLINE_TEXT_PREVIEW_EXTENSIONS.has(ext)));
+    return { isBinary, previewSupported };
+}
+function shouldRenderMarkdownPreview(filePath, presentation) {
+    if (presentation !== "preview") {
+        return false;
+    }
+    return MARKDOWN_PREVIEW_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+function stripLeadingFrontMatter(input) {
+    const source = input.replace(/^\uFEFF/, "");
+    const match = source.match(/^---\r?\n[\s\S]*?\r?\n(?:---|\.\.\.)\r?\n?/);
+    if (!match) {
+        return source;
+    }
+    return source.slice(match[0].length);
+}
+function buildMarkdownPreviewHtml(params) {
+    const payload = Buffer.from(stripLeadingFrontMatter(params.markdown), "utf8").toString("base64");
+    return renderMarkdownPreviewTemplate({
+        title: params.title,
+        payload,
+    });
+}
+function resolveBinPath(bin) {
+    if (path.isAbsolute(bin)) {
+        return bin;
+    }
+    const pathEnv = process.env.PATH ?? "";
+    const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+    const candidates = process.platform === "win32" ? [bin, `${bin}.exe`, `${bin}.cmd`, `${bin}.bat`] : [bin];
+    for (const dir of dirs) {
+        for (const candidate of candidates) {
+            const full = path.join(dir, candidate);
+            try {
+                const stat = spawnSync(full, ["--version"], {
+                    timeout: 1500,
+                    stdio: "ignore",
+                });
+                if (!stat.error) {
+                    return full;
+                }
+            }
+            catch {
+                // ignore candidate
+            }
+        }
+    }
+    return undefined;
+}
+function extractCloudflaredVersion(output) {
+    const match = output.match(/version\s+([0-9]+\.[0-9]+\.[0-9]+)/i);
+    return match?.[1];
+}
+async function fileExists(input) {
+    try {
+        await fs.access(input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function mkdirp(input) {
+    await fs.mkdir(input, { recursive: true });
+}
+async function findFreePort() {
+    return await new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close();
+                reject(new Error("failed to resolve free port"));
+                return;
+            }
+            const port = address.port;
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve(port);
+            });
+        });
+    });
+}
+async function probeLocalPort(port) {
+    return await new Promise((resolve) => {
+        const socket = net.connect({ port, host: "127.0.0.1" });
+        const done = (ok) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+        socket.setTimeout(1200, () => done(false));
+    });
+}
+function formatRelativeUrl(input) {
+    return input
+        .split(path.sep)
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+async function walkFiles(dir, baseDir = dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (WINDOWS_METADATA_SUFFIX_RE.test(entry.name)) {
+            continue;
+        }
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await walkFiles(abs, baseDir)));
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push(path.relative(baseDir, abs));
+        }
+    }
+    return files;
+}
+async function sha256File(input) {
+    const hash = crypto.createHash("sha256");
+    const stream = createReadStream(input);
+    for await (const chunk of stream) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+function parseBasicAuth(input) {
+    if (!input || !input.startsWith("Basic ")) {
+        return null;
+    }
+    const encoded = input.slice("Basic ".length).trim();
+    try {
+        const decoded = Buffer.from(encoded, "base64").toString("utf8");
+        const index = decoded.indexOf(":");
+        if (index < 0) {
+            return null;
+        }
+        return { username: decoded.slice(0, index), password: decoded.slice(index + 1) };
+    }
+    catch {
+        return null;
+    }
+}
+function parseBearerToken(authHeader) {
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        return undefined;
+    }
+    const token = authHeader.slice("Bearer ".length).trim();
+    return token || undefined;
+}
+function shouldAllowPath(pathname, allowlist) {
+    if (allowlist.length === 0) {
+        return true;
+    }
+    return allowlist.some((prefix) => {
+        if (prefix === "/") {
+            return true;
+        }
+        if (pathname === prefix) {
+            return true;
+        }
+        return pathname.startsWith(`${prefix.endsWith("/") ? prefix : `${prefix}/`}`);
+    });
+}
+function isValidQuickTunnelUrl(input) {
+    try {
+        const parsed = new URL(input);
+        if (parsed.protocol !== "https:") {
+            return false;
+        }
+        const host = parsed.hostname.toLowerCase();
+        if (!host.endsWith(".trycloudflare.com")) {
+            return false;
+        }
+        const subdomain = host.slice(0, -".trycloudflare.com".length);
+        if (!subdomain || subdomain.includes(".")) {
+            return false;
+        }
+        if (INVALID_QUICK_TUNNEL_SUBDOMAINS.has(subdomain)) {
+            return false;
+        }
+        return /^[a-z0-9-]+$/i.test(subdomain);
+    }
+    catch {
+        return false;
+    }
+}
+function pickQuickTunnelUrlFromLine(line) {
+    const matches = line.match(CLOUDFLARE_URL_RE);
+    if (!matches) {
+        return undefined;
+    }
+    for (const candidate of matches) {
+        if (isValidQuickTunnelUrl(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function matchAuditFilters(event, filters) {
+    const fromMs = timestampMs(filters.from_ts);
+    const toMs = timestampMs(filters.to_ts);
+    const eventMs = timestampMs(event.ts);
+    if (filters.id && event.id !== filters.id) {
+        return false;
+    }
+    if (filters.event && event.event !== filters.event) {
+        return false;
+    }
+    if (filters.type && event.type !== filters.type) {
+        return false;
+    }
+    if (filters.from_ts) {
+        if (fromMs !== undefined && eventMs !== undefined) {
+            if (eventMs < fromMs) {
+                return false;
+            }
+        }
+        else if (event.ts < filters.from_ts) {
+            return false;
+        }
+    }
+    if (filters.to_ts) {
+        if (toMs !== undefined && eventMs !== undefined) {
+            if (eventMs > toMs) {
+                return false;
+            }
+        }
+        else if (event.ts > filters.to_ts) {
+            return false;
+        }
+    }
+    return true;
+}
+export class CfshareManager {
+    logger;
+    resolvePath;
+    pluginConfig;
+    cloudflaredPathInput;
+    stateDir;
+    policyFile;
+    ignoreFile;
+    workspaceRoot;
+    auditFile;
+    sessionsFile;
+    exportsDir;
+    initialized = false;
+    initializing;
+    policy;
+    policyWarnings = [];
+    ignoreMatcher = ignore();
+    cloudflaredResolvedPath;
+    guardTimer;
+    sessions = new Map();
+    constructor(api) {
+        this.logger = api.logger;
+        this.resolvePath = api.resolvePath;
+        this.pluginConfig = (api.pluginConfig ?? {});
+        this.stateDir = this.resolvePath(this.pluginConfig.stateDir ?? "~/.openclaw/cfshare");
+        this.policyFile = this.resolvePath(this.pluginConfig.policyFile ?? path.join(this.stateDir, "policy.json"));
+        this.ignoreFile = this.resolvePath(this.pluginConfig.ignoreFile ?? path.join(this.stateDir, "policy.ignore"));
+        this.workspaceRoot = path.join(this.stateDir, "workspaces");
+        this.auditFile = path.join(this.stateDir, "audit.jsonl");
+        this.sessionsFile = path.join(this.stateDir, "sessions.json");
+        this.exportsDir = path.join(this.stateDir, "exports");
+        this.cloudflaredPathInput = this.pluginConfig.cloudflaredPath ?? "cloudflared";
+    }
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        if (!this.initializing) {
+            this.initializing = this.initialize();
+        }
+        await this.initializing;
+    }
+    async initialize() {
+        await mkdirp(this.stateDir);
+        await mkdirp(this.workspaceRoot);
+        await mkdirp(this.exportsDir);
+        await this.reloadPolicy();
+        this.startGuard();
+        this.initialized = true;
+    }
+    async reloadPolicy() {
+        const loaded = await loadPolicy({
+            policyFile: this.policyFile,
+            ignoreFile: this.ignoreFile,
+            pluginConfig: this.pluginConfig,
+        });
+        this.policy = loaded.effective;
+        this.policyWarnings = loaded.warnings;
+        this.ignoreMatcher = loaded.matcher;
+    }
+    appendLog(session, component, line) {
+        const entry = { ts: nowIso(), component, line };
+        session.logs.push(entry);
+        if (session.logs.length > MAX_LOG_LINES) {
+            session.logs.splice(0, session.logs.length - MAX_LOG_LINES);
+        }
+    }
+    async writeAudit(event) {
+        try {
+            await fs.appendFile(this.auditFile, `${JSON.stringify(event)}\n`, "utf8");
+        }
+        catch (error) {
+            this.logger.warn(`cfshare: failed to write audit event: ${String(error)}`);
+        }
+    }
+    async persistSessionsSnapshot() {
+        const records = Array.from(this.sessions.values()).map((session) => ({
+            id: session.id,
+            type: session.type,
+            status: session.status,
+            expiresAt: session.expiresAt,
+            workspaceDir: session.workspaceDir,
+            processPid: session.process?.pid,
+        }));
+        await fs.writeFile(this.sessionsFile, JSON.stringify(records, null, 2), "utf8");
+    }
+    makeAccessState(params) {
+        const allowlistPaths = normalizeAllowlistPaths(params.allowlistPaths);
+        if (params.mode === "token") {
+            return {
+                mode: "token",
+                protectOrigin: params.protectOrigin,
+                allowlistPaths,
+                token: crypto.randomBytes(16).toString("hex"),
+            };
+        }
+        if (params.mode === "basic") {
+            return {
+                mode: "basic",
+                protectOrigin: params.protectOrigin,
+                allowlistPaths,
+                username: "cfshare",
+                password: crypto.randomBytes(12).toString("base64url"),
+            };
+        }
+        return {
+            mode: "none",
+            protectOrigin: params.protectOrigin,
+            allowlistPaths,
+        };
+    }
+    makeResponsePublicUrl(session) {
+        const base = session.publicUrl;
+        if (!base) {
+            return undefined;
+        }
+        if (session.access.mode !== "token" || !session.access.token) {
+            return base;
+        }
+        try {
+            const out = new URL(base);
+            out.searchParams.set("token", session.access.token);
+            return out.toString();
+        }
+        catch {
+            const sep = base.includes("?") ? "&" : "?";
+            return `${base}${sep}token=${encodeURIComponent(session.access.token)}`;
+        }
+    }
+    buildRateLimiter(policy) {
+        if (!policy.enabled) {
+            return () => true;
+        }
+        const state = new Map();
+        return (ip) => {
+            const now = Date.now();
+            const row = state.get(ip);
+            if (!row || now - row.windowStart >= policy.windowMs) {
+                state.set(ip, { windowStart: now, count: 1 });
+                return true;
+            }
+            if (row.count >= policy.maxRequests) {
+                return false;
+            }
+            row.count += 1;
+            return true;
+        };
+    }
+    isAuthorized(req, access) {
+        if (!access.protectOrigin || access.mode === "none") {
+            return true;
+        }
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (access.mode === "token") {
+            const queryToken = ensureString(url.searchParams.get("token"));
+            const headerToken = ensureString(req.headers["x-cfshare-token"]);
+            const bearer = parseBearerToken(req.headers.authorization);
+            return queryToken === access.token || headerToken === access.token || bearer === access.token;
+        }
+        const basic = parseBasicAuth(req.headers.authorization);
+        return basic?.username === access.username && basic?.password === access.password;
+    }
+    async startReverseProxy(params) {
+        const proxyPort = await findFreePort();
+        const allowRequest = this.buildRateLimiter(this.policy.rateLimit);
+        const upstreamBase = `http://127.0.0.1:${params.upstreamPort}`;
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            const clientIp = req.socket.remoteAddress ?? "unknown";
+            params.session.stats.requests += 1;
+            params.session.stats.lastAccessAt = nowIso();
+            if (!allowRequest(clientIp)) {
+                res.writeHead(429, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: "rate_limited" }));
+                this.appendLog(params.session, "origin", `rate limit blocked ip=${clientIp}`);
+                return;
+            }
+            if (!shouldAllowPath(url.pathname, params.access.allowlistPaths)) {
+                res.writeHead(403, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: "path_not_allowed", path: url.pathname }));
+                return;
+            }
+            if (!this.isAuthorized(req, params.access)) {
+                const headers = {
+                    "content-type": "application/json",
+                };
+                if (params.access.mode === "basic") {
+                    headers["www-authenticate"] = 'Basic realm="cfshare"';
+                }
+                res.writeHead(401, headers);
+                res.end(JSON.stringify({ error: "unauthorized" }));
+                return;
+            }
+            const upstreamUrl = new URL(url.pathname + url.search, upstreamBase);
+            const transport = upstreamUrl.protocol === "https:" ? https : http;
+            const proxyReq = transport.request({
+                protocol: upstreamUrl.protocol,
+                hostname: upstreamUrl.hostname,
+                port: upstreamUrl.port,
+                method: req.method,
+                path: upstreamUrl.pathname + upstreamUrl.search,
+                headers: {
+                    ...req.headers,
+                    host: upstreamUrl.host,
+                },
+            }, (proxyRes) => {
+                res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+                proxyRes.on("data", (chunk) => {
+                    params.session.stats.bytesSent += chunk.length;
+                });
+                proxyRes.pipe(res);
+            });
+            proxyReq.on("error", (error) => {
+                this.appendLog(params.session, "origin", `proxy error: ${String(error)}`);
+                if (!res.headersSent) {
+                    res.writeHead(502, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "proxy_error" }));
+                    return;
+                }
+                res.end();
+            });
+            req.pipe(proxyReq);
+        });
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(proxyPort, "127.0.0.1", () => resolve());
+        });
+        this.appendLog(params.session, "origin", `reverse proxy listening on 127.0.0.1:${proxyPort}`);
+        return { server, port: proxyPort };
+    }
+    async sendFileResponse(params) {
+        const stat = await fs.stat(params.filePath);
+        const detectedMime = String(mimeLookup(params.filePath) || "application/octet-stream");
+        const capabilities = await detectFileDeliveryCapabilities({
+            filePath: params.filePath,
+            mime: detectedMime,
+        });
+        let presentation = params.presentation ?? "download";
+        if (presentation === "preview" && !capabilities.previewSupported) {
+            presentation = "raw";
+        }
+        const mime = presentation === "raw" && !capabilities.isBinary
+            ? "text/plain; charset=utf-8"
+            : detectedMime;
+        const method = (params.req.method ?? "GET").toUpperCase();
+        if (method !== "GET" && method !== "HEAD") {
+            params.res.writeHead(405, { "content-type": "application/json" });
+            params.res.end(JSON.stringify({ error: "method_not_allowed" }));
+            return;
+        }
+        if (shouldRenderMarkdownPreview(params.filePath, presentation)) {
+            const fileRaw = await fs.readFile(params.filePath, "utf8");
+            const previewHtml = buildMarkdownPreviewHtml({
+                title: params.downloadName ?? path.basename(params.filePath),
+                markdown: fileRaw,
+            });
+            const body = Buffer.from(previewHtml, "utf8");
+            const headers = {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+                "content-length": String(body.length),
+            };
+            params.res.writeHead(200, headers);
+            if (method === "HEAD") {
+                params.res.end();
+                return;
+            }
+            if (params.countAsDownload) {
+                params.session.stats.downloads += 1;
+            }
+            params.session.stats.bytesSent += body.length;
+            params.res.end(body);
+            return;
+        }
+        const headers = {
+            "content-type": String(mime),
+            "accept-ranges": "bytes",
+            "cache-control": "no-store",
+            "x-content-type-options": "nosniff",
+        };
+        const contentDisposition = buildContentDisposition({
+            mode: presentation,
+            filePath: params.filePath,
+            downloadName: params.downloadName,
+        });
+        if (contentDisposition) {
+            headers["content-disposition"] = contentDisposition;
+        }
+        const range = ensureString(params.req.headers.range);
+        if (!range) {
+            headers["content-length"] = String(stat.size);
+            params.res.writeHead(200, headers);
+            if (method === "HEAD") {
+                params.res.end();
+                return;
+            }
+            if (params.countAsDownload) {
+                params.session.stats.downloads += 1;
+            }
+            params.session.stats.bytesSent += stat.size;
+            await pipeline(createReadStream(params.filePath), params.res);
+            return;
+        }
+        const match = range.match(/^bytes=(\d*)-(\d*)$/i);
+        if (!match) {
+            params.res.writeHead(416, { "content-type": "application/json" });
+            params.res.end(JSON.stringify({ error: "invalid_range" }));
+            return;
+        }
+        const start = match[1] ? Number.parseInt(match[1], 10) : 0;
+        const end = match[2] ? Number.parseInt(match[2], 10) : stat.size - 1;
+        if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end < start || end >= stat.size) {
+            params.res.writeHead(416, { "content-type": "application/json" });
+            params.res.end(JSON.stringify({ error: "invalid_range" }));
+            return;
+        }
+        headers["content-length"] = String(end - start + 1);
+        headers["content-range"] = `bytes ${start}-${end}/${stat.size}`;
+        params.res.writeHead(206, headers);
+        if (method === "HEAD") {
+            params.res.end();
+            return;
+        }
+        if (params.countAsDownload) {
+            params.session.stats.downloads += 1;
+        }
+        params.session.stats.bytesSent += end - start + 1;
+        await pipeline(createReadStream(params.filePath, { start, end }), params.res);
+    }
+    async createZipArchive(workspaceDir) {
+        const zipPath = path.join(workspaceDir, "_cfshare_bundle.zip");
+        const files = await walkFiles(workspaceDir);
+        await new Promise((resolve, reject) => {
+            const zip = new yazl.ZipFile();
+            const out = createWriteStream(zipPath);
+            out.once("error", reject);
+            out.once("close", () => resolve());
+            zip.outputStream.pipe(out);
+            for (const relPath of files) {
+                // Zip entries should use "/" separators regardless of OS.
+                const zipEntry = relPath.split(path.sep).join("/");
+                if (zipEntry === path.basename(zipPath)) {
+                    continue;
+                }
+                zip.addFile(path.join(workspaceDir, relPath), zipEntry);
+            }
+            zip.end();
+        });
+        const stat = await fs.stat(zipPath);
+        return { zipPath, size: stat.size };
+    }
+    async createFolderZipArchive(params) {
+        const safeFolderPath = normalizeWorkspaceRelativePath(params.folderPath);
+        if (!safeFolderPath) {
+            throw new Error("invalid_folder_path");
+        }
+        const folderAbs = path.join(params.workspaceDir, safeFolderPath);
+        if (!isSubPath(folderAbs, params.workspaceDir) || !(await fileExists(folderAbs))) {
+            throw new Error("folder_not_found");
+        }
+        const stat = await fs.stat(folderAbs);
+        if (!stat.isDirectory()) {
+            throw new Error("not_a_directory");
+        }
+        const zipName = `${sanitizeFilename(path.basename(folderAbs) || "folder")}.zip`;
+        const tempZipName = `.cfshare_folder_${randomId("zip")}.zip`;
+        const zipPath = path.join(params.workspaceDir, tempZipName);
+        const files = await walkFiles(folderAbs);
+        await new Promise((resolve, reject) => {
+            const zip = new yazl.ZipFile();
+            const out = createWriteStream(zipPath);
+            out.once("error", reject);
+            out.once("close", () => resolve());
+            zip.outputStream.pipe(out);
+            for (const relPath of files) {
+                const zipEntry = path.posix.join(path.basename(folderAbs), relPath.split(path.sep).join("/"));
+                zip.addFile(path.join(folderAbs, relPath), zipEntry);
+            }
+            zip.end();
+        });
+        const zipStat = await fs.stat(zipPath);
+        return {
+            zipPath,
+            size: zipStat.size,
+            downloadName: zipName,
+        };
+    }
+    async startFileServer(params) {
+        const port = await findFreePort();
+        const manifest = [];
+        let zipBundle;
+        if (params.mode === "normal") {
+            const files = await walkFiles(params.workspaceDir);
+            for (const relPath of files) {
+                if (relPath === "_cfshare_bundle.zip") {
+                    continue;
+                }
+                const abs = path.join(params.workspaceDir, relPath);
+                const stat = await fs.stat(abs);
+                const detectedMime = String(mimeLookup(abs) || "application/octet-stream");
+                const capabilities = await detectFileDeliveryCapabilities({
+                    filePath: abs,
+                    mime: detectedMime,
+                });
+                manifest.push({
+                    name: relPath,
+                    size: stat.size,
+                    sha256: await sha256File(abs),
+                    relative_url: `/${formatRelativeUrl(relPath)}`,
+                    modified_at: toLocalIso(stat.mtime),
+                    is_binary: capabilities.isBinary,
+                    preview_supported: capabilities.previewSupported,
+                });
+            }
+        }
+        else {
+            zipBundle = await this.createZipArchive(params.workspaceDir);
+            manifest.push({
+                name: "download.zip",
+                size: zipBundle.size,
+                sha256: await sha256File(zipBundle.zipPath),
+                relative_url: "/__cfshare__/download.zip",
+                modified_at: nowIso(),
+                is_binary: true,
+                preview_supported: false,
+            });
+        }
+        const explorerManifest = manifest;
+        const allowRequest = this.buildRateLimiter(this.policy.rateLimit);
+        const server = http.createServer(async (req, res) => {
+            const clientIp = req.socket.remoteAddress ?? "unknown";
+            params.session.stats.requests += 1;
+            params.session.stats.lastAccessAt = nowIso();
+            if (!allowRequest(clientIp)) {
+                res.writeHead(429, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: "rate_limited" }));
+                return;
+            }
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            const pathname = decodeURIComponent(url.pathname);
+            const requestedPresentation = resolveRequestPresentation(url, params.presentation);
+            const checkMaxDownloads = async () => {
+                if (typeof params.maxDownloads !== "number") {
+                    return;
+                }
+                if (params.session.stats.downloads >= params.maxDownloads) {
+                    await this.stopExposure(params.session.id, { reason: "max_downloads_reached", expired: false });
+                }
+            };
+            try {
+                if (pathname === "/") {
+                    if (params.mode === "normal" && params.directSingleFileRoot && explorerManifest.length === 1) {
+                        const filePath = path.join(params.workspaceDir, explorerManifest[0].name);
+                        await this.sendFileResponse({
+                            req,
+                            res,
+                            session: params.session,
+                            filePath,
+                            presentation: requestedPresentation,
+                            countAsDownload: true,
+                        });
+                        await checkMaxDownloads();
+                        return;
+                    }
+                    const body = Buffer.from(renderFileExplorerTemplate({
+                        title: "cfshare",
+                        mode: params.mode,
+                        presentation: params.presentation,
+                        manifest: explorerManifest,
+                        autoEnterSingleDirectory: params.autoEnterSingleDirectory,
+                        rootDirectories: params.rootDirectories,
+                    }), "utf8");
+                    res.writeHead(200, {
+                        "content-type": "text/html; charset=utf-8",
+                        "cache-control": "no-store",
+                        "x-content-type-options": "nosniff",
+                        "content-length": String(body.length),
+                    });
+                    if ((req.method ?? "GET").toUpperCase() === "HEAD") {
+                        res.end();
+                        return;
+                    }
+                    params.session.stats.bytesSent += body.length;
+                    res.end(body);
+                    return;
+                }
+                if (pathname === "/__cfshare__/download-folder.zip" && params.mode === "normal") {
+                    const folderPath = normalizeWorkspaceRelativePath(ensureString(url.searchParams.get("path")));
+                    if (!folderPath) {
+                        res.writeHead(400, { "content-type": "application/json" });
+                        res.end(JSON.stringify({ error: "invalid_folder_path" }));
+                        return;
+                    }
+                    let bundle;
+                    try {
+                        bundle = await this.createFolderZipArchive({
+                            workspaceDir: params.workspaceDir,
+                            folderPath,
+                        });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        const status = message === "folder_not_found" ? 404 : 400;
+                        res.writeHead(status, { "content-type": "application/json" });
+                        res.end(JSON.stringify({ error: message }));
+                        return;
+                    }
+                    try {
+                        await this.sendFileResponse({
+                            req,
+                            res,
+                            session: params.session,
+                            filePath: bundle.zipPath,
+                            downloadName: bundle.downloadName,
+                            presentation: "download",
+                            countAsDownload: true,
+                        });
+                    }
+                    finally {
+                        await fs.unlink(bundle.zipPath).catch(() => undefined);
+                    }
+                    await checkMaxDownloads();
+                    return;
+                }
+                if (pathname === "/__cfshare__/download.zip" && params.mode === "zip" && zipBundle) {
+                    await this.sendFileResponse({
+                        req,
+                        res,
+                        session: params.session,
+                        filePath: zipBundle.zipPath,
+                        downloadName: "download.zip",
+                        presentation: "download",
+                        countAsDownload: true,
+                    });
+                    await checkMaxDownloads();
+                    return;
+                }
+                if (params.mode === "zip") {
+                    res.writeHead(404, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "not_found" }));
+                    return;
+                }
+                const normalized = pathname.replace(/^\/+/, "");
+                const target = path.join(params.workspaceDir, normalized);
+                if (!isSubPath(target, params.workspaceDir) || !(await fileExists(target))) {
+                    res.writeHead(404, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "not_found" }));
+                    return;
+                }
+                const stat = await fs.stat(target);
+                if (!stat.isFile()) {
+                    res.writeHead(404, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "not_file" }));
+                    return;
+                }
+                await this.sendFileResponse({
+                    req,
+                    res,
+                    session: params.session,
+                    filePath: target,
+                    presentation: requestedPresentation,
+                    countAsDownload: true,
+                });
+                await checkMaxDownloads();
+            }
+            catch (error) {
+                this.appendLog(params.session, "origin", `file server error: ${String(error)}`);
+                if (!res.headersSent) {
+                    res.writeHead(500, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: "internal_error" }));
+                    return;
+                }
+                res.end();
+            }
+        });
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(port, "127.0.0.1", () => resolve());
+        });
+        this.appendLog(params.session, "origin", `file server listening on 127.0.0.1:${port}`);
+        return { server, port, manifest };
+    }
+    async detectWorkspaceRootBehavior(workspaceDir) {
+        const entries = await fs.readdir(workspaceDir, { withFileTypes: true });
+        const rootDirectories = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+        if (entries.length !== 1) {
+            return {
+                directSingleFileRoot: false,
+                autoEnterSingleDirectory: false,
+                rootDirectories,
+            };
+        }
+        const rootEntry = entries[0];
+        return {
+            directSingleFileRoot: rootEntry.isFile(),
+            autoEnterSingleDirectory: rootEntry.isDirectory(),
+            rootDirectories,
+        };
+    }
+    async copyInputsToWorkspace(pathsInput, workspaceDir, ctx) {
+        const allowedRoots = this.policy.allowedPathRoots.map((root) => this.resolvePath(root));
+        const workspaceRoot = ctx?.workspaceDir ? this.resolvePath(ctx.workspaceDir) : undefined;
+        for (const item of pathsInput) {
+            const resolved = path.resolve(item);
+            const real = await fs.realpath(resolved).catch(() => resolved);
+            const ignoreCandidates = getIgnoreMatchCandidates(real);
+            if (ignoreCandidates.some((candidate) => this.ignoreMatcher.ignores(candidate))) {
+                throw new Error(`path blocked by ignore policy: ${item}`);
+            }
+            if (allowedRoots.length > 0 && !allowedRoots.some((root) => isSubPath(real, root))) {
+                throw new Error(`path outside allowed roots: ${item}`);
+            }
+            if (workspaceRoot && !isSubPath(real, workspaceRoot)) {
+                this.logger.warn(`cfshare: exposing path outside workspace (${item})`);
+            }
+            const sourceStat = await fs.stat(real);
+            const baseName = sanitizeFilename(path.basename(real) || "item");
+            const makeCandidate = (n) => {
+                if (n === 0) {
+                    return baseName;
+                }
+                // For directories, treat dots as part of the name (do not split extension).
+                if (sourceStat.isDirectory()) {
+                    return `${baseName}_${n}`;
+                }
+                // For files, keep extension stable: "a.txt" -> "a_1.txt".
+                const parsed = path.parse(baseName);
+                return `${parsed.name || "item"}_${n}${parsed.ext || ""}`;
+            };
+            let target = path.join(workspaceDir, makeCandidate(0));
+            let seq = 1;
+            while (await fileExists(target)) {
+                target = path.join(workspaceDir, makeCandidate(seq));
+                seq += 1;
+            }
+            if (sourceStat.isDirectory()) {
+                await fs.cp(real, target, { recursive: true, dereference: true });
+            }
+            else if (sourceStat.isFile()) {
+                await mkdirp(path.dirname(target));
+                await fs.copyFile(real, target);
+            }
+            else {
+                throw new Error(`unsupported path type: ${item}`);
+            }
+        }
+    }
+    makeExposureRecord(session) {
+        return {
+            id: session.id,
+            type: session.type,
+            status: session.status,
+            public_url: this.makeResponsePublicUrl(session),
+            local_url: session.localUrl,
+            expires_at: session.expiresAt,
+        };
+    }
+    async summarizeExposeInputs(pathsInput) {
+        const out = [];
+        for (const rawPath of pathsInput) {
+            const resolved = path.resolve(rawPath);
+            const real = await fs.realpath(resolved).catch(() => resolved);
+            const stat = await fs.stat(real);
+            if (stat.isDirectory()) {
+                out.push({
+                    input_path: rawPath,
+                    name: path.basename(real) || rawPath,
+                    type: "directory",
+                });
+                continue;
+            }
+            if (stat.isFile()) {
+                out.push({
+                    input_path: rawPath,
+                    name: path.basename(real) || rawPath,
+                    type: "file",
+                    size: stat.size,
+                });
+            }
+        }
+        return out;
+    }
+    buildExposeFilesResponseManifest(params) {
+        const allFiles = params.inputs.length > 0 && params.inputs.every((entry) => entry.type === "file");
+        const shouldReturnDetailed = allFiles && params.inputs.length > 1;
+        const totalSizeBytes = params.fullManifest.reduce((sum, entry) => sum + entry.size, 0);
+        if (shouldReturnDetailed) {
+            const limit = Math.max(1, Math.trunc(params.detailedLimit ?? MAX_RESPONSE_MANIFEST_ITEMS));
+            const manifest = params.fullManifest.slice(0, limit);
+            return {
+                manifest,
+                manifest_mode: "detailed",
+                manifest_meta: {
+                    total_count: params.fullManifest.length,
+                    returned_count: manifest.length,
+                    truncated: params.fullManifest.length > manifest.length,
+                    total_size_bytes: totalSizeBytes,
+                },
+            };
+        }
+        return {
+            manifest: params.inputs,
+            manifest_mode: "summary",
+            manifest_meta: {
+                total_count: params.inputs.length,
+                returned_count: params.inputs.length,
+                truncated: false,
+                total_size_bytes: totalSizeBytes,
+            },
+        };
+    }
+    makeManifestResponse(manifest, limit = MAX_RESPONSE_MANIFEST_ITEMS) {
+        const source = manifest ?? [];
+        const safeLimit = Math.max(1, Math.trunc(limit));
+        const sliced = source.slice(0, safeLimit);
+        const totalSizeBytes = source.reduce((sum, entry) => sum + entry.size, 0);
+        return {
+            manifest: sliced,
+            manifest_meta: {
+                total_count: source.length,
+                returned_count: sliced.length,
+                truncated: source.length > sliced.length,
+                total_size_bytes: totalSizeBytes,
+            },
+        };
+    }
+    startGuard() {
+        if (this.guardTimer) {
+            return;
+        }
+        this.guardTimer = setInterval(() => {
+            void this.reapExpired();
+        }, 30_000);
+        this.guardTimer.unref();
+    }
+    async reapExpired() {
+        const now = Date.now();
+        const toStop = Array.from(this.sessions.values()).filter((session) => session.status === "running" && new Date(session.expiresAt).getTime() <= now);
+        for (const session of toStop) {
+            await this.stopExposure(session.id, { reason: "expired", expired: true });
+        }
+    }
+    async startTunnel(session, targetPort) {
+        const cloudflaredBin = this.cloudflaredResolvedPath ?? resolveBinPath(this.cloudflaredPathInput);
+        if (!cloudflaredBin) {
+            throw new Error(`cloudflared not found in PATH: ${this.cloudflaredPathInput}`);
+        }
+        this.cloudflaredResolvedPath = cloudflaredBin;
+        const edgeIpVersion = this.policy.tunnel.edgeIpVersion;
+        const protocol = this.policy.tunnel.protocol;
+        const args = [
+            "tunnel",
+            "--url",
+            `http://127.0.0.1:${targetPort}`,
+            "--edge-ip-version",
+            edgeIpVersion,
+            "--protocol",
+            protocol,
+            "--no-autoupdate",
+        ];
+        this.appendLog(session, "tunnel", `spawn: ${cloudflaredBin} ${args.join(" ")}`);
+        const proc = spawn(cloudflaredBin, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let settled = false;
+        return await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                proc.kill("SIGTERM");
+                reject(new Error("timed out waiting for cloudflared URL"));
+            }, 30_000);
+            const onLine = (line) => {
+                this.appendLog(session, "tunnel", line);
+                const url = pickQuickTunnelUrlFromLine(line);
+                if (url && !settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    resolve({ process: proc, publicUrl: url });
+                }
+            };
+            const attachStream = (stream) => {
+                let buffer = "";
+                stream.on("data", (chunk) => {
+                    buffer += chunk.toString();
+                    const lines = buffer.split(/\r?\n/);
+                    buffer = lines.pop() ?? "";
+                    for (const line of lines) {
+                        if (line.trim()) {
+                            onLine(line.trim());
+                        }
+                    }
+                });
+                stream.on("end", () => {
+                    if (buffer.trim()) {
+                        onLine(buffer.trim());
+                    }
+                });
+            };
+            attachStream(proc.stdout);
+            attachStream(proc.stderr);
+            proc.once("error", (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timeout);
+                reject(error);
+            });
+            proc.once("exit", (code, signal) => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    reject(new Error(`cloudflared exited before URL (code=${String(code)}, signal=${String(signal)})`));
+                }
+            });
+        });
+    }
+    async startTunnelWithRetry(params) {
+        const maxAttempts = Math.max(1, Math.trunc(params.maxAttempts ?? 2));
+        let lastError = "unknown";
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            let tunnel;
+            try {
+                this.appendLog(params.session, "manager", `starting tunnel attempt ${attempt}/${maxAttempts} on port ${params.targetPort}`);
+                tunnel = await this.startTunnel(params.session, params.targetPort);
+                if (!isValidQuickTunnelUrl(tunnel.publicUrl)) {
+                    throw new Error(`invalid quick tunnel url: ${tunnel.publicUrl}`);
+                }
+                this.appendLog(params.session, "manager", `tunnel ready on attempt ${attempt}/${maxAttempts}: ${tunnel.publicUrl}`);
+                return tunnel;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : String(error);
+                this.appendLog(params.session, "manager", `tunnel attempt ${attempt}/${maxAttempts} failed: ${lastError}`);
+                if (tunnel?.process) {
+                    this.appendLog(params.session, "manager", "stopping failed tunnel process before retry");
+                    await this.terminateProcess(tunnel.process);
+                }
+            }
+        }
+        throw new Error(`failed to start cloudflared tunnel after ${maxAttempts} attempts: ${lastError}`);
+    }
+    async terminateProcess(proc) {
+        if (!proc || proc.killed) {
+            return;
+        }
+        const pid = proc.pid;
+        if (!pid) {
+            return;
+        }
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            return;
+        }
+        proc.kill("SIGTERM");
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                try {
+                    proc.kill("SIGKILL");
+                }
+                catch {
+                    // ignore
+                }
+                resolve();
+            }, 2500);
+            proc.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    async envCheck() {
+        await this.ensureInitialized();
+        await this.reloadPolicy();
+        const warnings = [...this.policyWarnings];
+        let cloudflaredPath = resolveBinPath(this.cloudflaredPathInput);
+        let cloudflaredVersion;
+        if (!cloudflaredPath && path.isAbsolute(this.cloudflaredPathInput)) {
+            cloudflaredPath = this.cloudflaredPathInput;
+        }
+        if (cloudflaredPath) {
+            const result = spawnSync(cloudflaredPath, ["--version"], {
+                timeout: 2000,
+                encoding: "utf8",
+            });
+            if (result.error) {
+                warnings.push(`cloudflared exists but version check failed: ${String(result.error)}`);
+            }
+            else {
+                const combined = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+                cloudflaredVersion = extractCloudflaredVersion(combined) ?? combined.trim().split(/\r?\n/)[0];
+            }
+        }
+        else {
+            warnings.push(`cloudflared binary not found (${this.cloudflaredPathInput})`);
+        }
+        const defaults = {
+            ...this.policy,
+            state_dir: this.stateDir,
+            policy_file: this.policyFile,
+            ignore_file: this.ignoreFile,
+            os: {
+                platform: process.platform,
+                arch: process.arch,
+                release: os.release(),
+                uid: typeof process.getuid === "function" ? process.getuid() : undefined,
+            },
+        };
+        return {
+            cloudflared: {
+                ok: Boolean(cloudflaredPath && cloudflaredVersion),
+                path: cloudflaredPath,
+                version: cloudflaredVersion,
+            },
+            defaults,
+            warnings,
+        };
+    }
+    async exposePort(params) {
+        await this.ensureInitialized();
+        const port = Math.trunc(params.port);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error("invalid port");
+        }
+        if (this.policy.blockedPorts.includes(port)) {
+            throw new Error(`port blocked by policy: ${port}`);
+        }
+        const alive = await probeLocalPort(port);
+        if (!alive) {
+            throw new Error(`local service is not reachable on 127.0.0.1:${port}`);
+        }
+        const ttlSeconds = normalizeTtl(params.opts?.ttl_seconds, this.policy);
+        const expiresAt = toLocalIso(new Date(Date.now() + ttlSeconds * 1000));
+        const accessMode = normalizeAccessMode(params.opts?.access, this.policy.defaultExposePortAccess);
+        const protectOrigin = typeof params.opts?.protect_origin === "boolean" ? params.opts.protect_origin : accessMode !== "none";
+        const id = randomId("port");
+        const session = {
+            id,
+            type: "port",
+            status: "starting",
+            createdAt: nowIso(),
+            expiresAt,
+            localUrl: `http://127.0.0.1:${port}`,
+            sourcePort: port,
+            originPort: port,
+            tunnelPort: port,
+            logs: [],
+            stats: { requests: 0, downloads: 0, bytesSent: 0 },
+            access: this.makeAccessState({
+                mode: accessMode,
+                protectOrigin,
+                allowlistPaths: params.opts?.allowlist_paths,
+            }),
+        };
+        this.sessions.set(id, session);
+        try {
+            let tunnelTargetPort = port;
+            if (protectOrigin || session.access.allowlistPaths.length > 0 || this.policy.rateLimit.enabled) {
+                const proxy = await this.startReverseProxy({
+                    upstreamPort: port,
+                    session,
+                    access: session.access,
+                });
+                session.proxyServer = proxy.server;
+                session.tunnelPort = proxy.port;
+                tunnelTargetPort = proxy.port;
+            }
+            const tunnel = await this.startTunnelWithRetry({
+                session,
+                targetPort: tunnelTargetPort,
+                maxAttempts: 2,
+            });
+            session.process = tunnel.process;
+            session.publicUrl = tunnel.publicUrl;
+            session.status = "running";
+            session.process.on("exit", (code, signal) => {
+                if (session.status === "running") {
+                    session.status = "error";
+                    session.lastError = `cloudflared exited (code=${String(code)}, signal=${String(signal)})`;
+                    this.appendLog(session, "tunnel", session.lastError);
+                }
+            });
+            session.timeoutHandle = setTimeout(() => {
+                void this.stopExposure(session.id, { reason: "expired", expired: true });
+            }, ttlSeconds * 1000);
+            session.timeoutHandle.unref();
+            await this.persistSessionsSnapshot();
+            await this.writeAudit({
+                ts: nowIso(),
+                event: "exposure_started",
+                id: session.id,
+                type: session.type,
+                details: {
+                    source_port: port,
+                    public_url: session.publicUrl,
+                    expires_at: expiresAt,
+                    access_mode: session.access.mode,
+                },
+            });
+            return {
+                id: session.id,
+                public_url: this.makeResponsePublicUrl(session),
+                local_url: session.localUrl,
+                expires_at: session.expiresAt,
+                access_info: {
+                    mode: session.access.mode,
+                    protect_origin: session.access.protectOrigin,
+                    token: maskSecret(session.access.token),
+                    username: session.access.username,
+                    password: maskSecret(session.access.password),
+                    allowlist_paths: session.access.allowlistPaths,
+                },
+            };
+        }
+        catch (error) {
+            session.status = "error";
+            session.lastError = error instanceof Error ? error.message : String(error);
+            await this.stopExposure(id, { reason: session.lastError, expired: false, keepAudit: true });
+            throw error;
+        }
+    }
+    async exposeFiles(params, ctx) {
+        await this.ensureInitialized();
+        if (!Array.isArray(params.paths) || params.paths.length === 0) {
+            throw new Error("paths is required");
+        }
+        const ttlSeconds = normalizeTtl(params.opts?.ttl_seconds, this.policy);
+        const expiresAt = toLocalIso(new Date(Date.now() + ttlSeconds * 1000));
+        const mode = params.opts?.mode ?? "normal";
+        const presentation = normalizeFilePresentation(params.opts?.presentation);
+        const accessMode = normalizeAccessMode(params.opts?.access, this.policy.defaultExposeFilesAccess);
+        const protectOrigin = accessMode !== "none";
+        const id = randomId("files");
+        const workspaceDir = path.join(this.workspaceRoot, id);
+        await mkdirp(workspaceDir);
+        const inputSummary = await this.summarizeExposeInputs(params.paths);
+        const session = {
+            id,
+            type: "files",
+            status: "starting",
+            createdAt: nowIso(),
+            expiresAt,
+            localUrl: "",
+            originPort: 0,
+            tunnelPort: 0,
+            workspaceDir,
+            fileMode: mode,
+            filePresentation: presentation,
+            logs: [],
+            stats: { requests: 0, downloads: 0, bytesSent: 0 },
+            access: this.makeAccessState({
+                mode: accessMode,
+                protectOrigin,
+            }),
+            maxDownloads: typeof params.opts?.max_downloads === "number" ? Math.trunc(params.opts.max_downloads) : undefined,
+        };
+        this.sessions.set(id, session);
+        try {
+            await this.copyInputsToWorkspace(params.paths, workspaceDir, ctx);
+            const rootBehavior = await this.detectWorkspaceRootBehavior(workspaceDir);
+            const fileServer = await this.startFileServer({
+                session,
+                workspaceDir,
+                mode,
+                presentation,
+                maxDownloads: session.maxDownloads,
+                directSingleFileRoot: mode === "normal" && rootBehavior.directSingleFileRoot,
+                autoEnterSingleDirectory: mode === "normal" && rootBehavior.autoEnterSingleDirectory,
+                rootDirectories: mode === "normal" ? rootBehavior.rootDirectories : [],
+            });
+            session.originServer = fileServer.server;
+            session.manifest = fileServer.manifest;
+            session.originPort = fileServer.port;
+            session.localUrl = `http://127.0.0.1:${fileServer.port}`;
+            let tunnelTargetPort = fileServer.port;
+            if (protectOrigin) {
+                const proxy = await this.startReverseProxy({
+                    upstreamPort: fileServer.port,
+                    session,
+                    access: session.access,
+                });
+                session.proxyServer = proxy.server;
+                session.tunnelPort = proxy.port;
+                tunnelTargetPort = proxy.port;
+            }
+            if (!session.tunnelPort) {
+                session.tunnelPort = tunnelTargetPort;
+            }
+            const tunnel = await this.startTunnelWithRetry({
+                session,
+                targetPort: tunnelTargetPort,
+                maxAttempts: 2,
+            });
+            session.process = tunnel.process;
+            session.publicUrl = tunnel.publicUrl;
+            session.status = "running";
+            session.process.on("exit", (code, signal) => {
+                if (session.status === "running") {
+                    session.status = "error";
+                    session.lastError = `cloudflared exited (code=${String(code)}, signal=${String(signal)})`;
+                    this.appendLog(session, "tunnel", session.lastError);
+                }
+            });
+            session.timeoutHandle = setTimeout(() => {
+                void this.stopExposure(session.id, { reason: "expired", expired: true });
+            }, ttlSeconds * 1000);
+            session.timeoutHandle.unref();
+            await this.persistSessionsSnapshot();
+            await this.writeAudit({
+                ts: nowIso(),
+                event: "exposure_started",
+                id: session.id,
+                type: session.type,
+                details: {
+                    public_url: session.publicUrl,
+                    expires_at: session.expiresAt,
+                    files_count: session.manifest?.length ?? 0,
+                    mode,
+                    presentation,
+                },
+            });
+            const responseManifest = mode === "zip"
+                ? {
+                    ...this.makeManifestResponse(session.manifest, MAX_RESPONSE_MANIFEST_ITEMS),
+                    manifest_mode: "detailed",
+                }
+                : this.buildExposeFilesResponseManifest({
+                    inputs: inputSummary,
+                    fullManifest: session.manifest ?? [],
+                    detailedLimit: MAX_RESPONSE_MANIFEST_ITEMS,
+                });
+            return {
+                id: session.id,
+                public_url: this.makeResponsePublicUrl(session),
+                expires_at: session.expiresAt,
+                mode,
+                presentation,
+                manifest_mode: responseManifest.manifest_mode,
+                manifest_meta: responseManifest.manifest_meta,
+                manifest: responseManifest.manifest,
+            };
+        }
+        catch (error) {
+            session.status = "error";
+            session.lastError = error instanceof Error ? error.message : String(error);
+            await this.stopExposure(id, { reason: session.lastError, expired: false, keepAudit: true });
+            throw error;
+        }
+    }
+    exposureList() {
+        return Array.from(this.sessions.values()).map((session) => this.makeExposureRecord(session));
+    }
+    normalizeRequestedIds(rawIds) {
+        const out = [];
+        const seen = new Set();
+        for (const item of rawIds) {
+            if (typeof item !== "string") {
+                continue;
+            }
+            const id = item.trim();
+            if (!id || seen.has(id)) {
+                continue;
+            }
+            seen.add(id);
+            out.push(id);
+        }
+        return out;
+    }
+    matchesExposureFilter(session, filter) {
+        if (!filter) {
+            return true;
+        }
+        if (filter.status && session.status !== filter.status) {
+            return false;
+        }
+        if (filter.type && session.type !== filter.type) {
+            return false;
+        }
+        return true;
+    }
+    resolveExposureSelection(query) {
+        const explicitIds = this.normalizeRequestedIds([
+            ...(typeof query.id === "string" ? [query.id] : []),
+            ...((query.ids ?? []).filter((value) => typeof value === "string")),
+        ]);
+        const hasAll = explicitIds.includes("all");
+        const allSessions = Array.from(this.sessions.values());
+        if (hasAll) {
+            const selectedIds = allSessions
+                .filter((session) => this.matchesExposureFilter(session, query.filter))
+                .map((session) => session.id);
+            return { selectorUsed: true, selectedIds, missingIds: [] };
+        }
+        if (explicitIds.length > 0) {
+            const selectedIds = [];
+            const missingIds = [];
+            for (const id of explicitIds) {
+                const session = this.sessions.get(id);
+                if (!session) {
+                    missingIds.push(id);
+                    continue;
+                }
+                if (this.matchesExposureFilter(session, query.filter)) {
+                    selectedIds.push(id);
+                }
+            }
+            return { selectorUsed: true, selectedIds, missingIds };
+        }
+        if (query.filter) {
+            const selectedIds = allSessions
+                .filter((session) => this.matchesExposureFilter(session, query.filter))
+                .map((session) => session.id);
+            return { selectorUsed: true, selectedIds, missingIds: [] };
+        }
+        return { selectorUsed: false, selectedIds: [], missingIds: [] };
+    }
+    async buildExposureDetail(session, opts) {
+        const tunnelAlive = Boolean(session.process && !session.process.killed);
+        const originAlive = session.type === "port"
+            ? await probeLocalPort(session.sourcePort ?? session.originPort)
+            : Boolean(session.originServer?.listening);
+        let publicProbe;
+        if (opts?.probe_public && session.publicUrl) {
+            try {
+                const probeUrl = new URL(session.publicUrl);
+                if (session.access.mode === "token" && session.access.token) {
+                    probeUrl.searchParams.set("token", session.access.token);
+                }
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), DEFAULT_PROBE_TIMEOUT_MS);
+                const headers = {};
+                if (session.access.mode === "basic" && session.access.username && session.access.password) {
+                    headers.authorization = `Basic ${Buffer.from(`${session.access.username}:${session.access.password}`).toString("base64")}`;
+                }
+                const response = await fetch(probeUrl.toString(), {
+                    method: "HEAD",
+                    signal: controller.signal,
+                    headers,
+                });
+                clearTimeout(timer);
+                publicProbe = { ok: response.ok, status: response.status };
+            }
+            catch (error) {
+                publicProbe = { ok: false, error: String(error) };
+            }
+        }
+        const fileSharing = session.type === "files"
+            ? {
+                mode: session.fileMode ?? "normal",
+                presentation: session.filePresentation ?? "download",
+            }
+            : undefined;
+        const includeManifest = Boolean(opts?.include_manifest);
+        const manifestBundle = session.type === "files" ? this.makeManifestResponse(session.manifest, opts?.manifest_limit) : undefined;
+        const detail = {
+            id: session.id,
+            type: session.type,
+            created_at: session.createdAt,
+            status: {
+                state: session.status,
+                tunnel_alive: tunnelAlive,
+                origin_alive: originAlive,
+                public_probe: publicProbe,
+            },
+            port: {
+                source_port: session.sourcePort,
+                origin_port: session.originPort,
+                tunnel_port: session.tunnelPort,
+            },
+            public_url: this.makeResponsePublicUrl(session),
+            expires_at: session.expiresAt,
+            local_url: session.localUrl,
+            stats: session.stats,
+            file_sharing: fileSharing,
+            last_error: session.lastError,
+        };
+        if (manifestBundle) {
+            detail.manifest_meta = manifestBundle.manifest_meta;
+            if (includeManifest) {
+                detail.manifest = manifestBundle.manifest;
+            }
+        }
+        return detail;
+    }
+    projectExposureDetail(detail, fields) {
+        if (!fields || fields.length === 0) {
+            return detail;
+        }
+        const out = {
+            id: detail.id,
+        };
+        for (const field of fields) {
+            if (field === "id") {
+                continue;
+            }
+            if (Object.prototype.hasOwnProperty.call(detail, field)) {
+                out[field] = detail[field];
+                if (field === "manifest" && Object.prototype.hasOwnProperty.call(detail, "manifest_meta")) {
+                    out.manifest_meta = detail.manifest_meta;
+                }
+            }
+        }
+        return out;
+    }
+    makeExposureGetNotFound(id, fields) {
+        const out = { id, error: "not_found" };
+        if (fields?.includes("status")) {
+            out.status = "not_found";
+        }
+        return out;
+    }
+    async exposureGet(params) {
+        await this.ensureInitialized();
+        const fields = Array.isArray(params.fields) ? this.normalizeRequestedIds(params.fields) : undefined;
+        const typedFields = fields;
+        const legacySingle = Boolean(params.id) && params.id !== "all" && !params.ids && !params.filter && !params.fields;
+        const selection = this.resolveExposureSelection({
+            id: params.id,
+            ids: params.ids,
+            filter: params.filter,
+        });
+        if (!selection.selectorUsed) {
+            throw new Error("id, ids, or filter is required");
+        }
+        if (legacySingle) {
+            const legacyId = params.id;
+            const session = this.sessions.get(legacyId);
+            if (!session) {
+                return { id: legacyId, status: "not_found" };
+            }
+            return await this.buildExposureDetail(session, {
+                probe_public: params.opts?.probe_public,
+                include_manifest: true,
+                manifest_limit: MAX_RESPONSE_MANIFEST_ITEMS,
+            });
+        }
+        const manifestRequested = typedFields?.includes("manifest") ?? false;
+        const manifestLimit = selection.selectedIds.length > 1
+            ? MAX_RESPONSE_MANIFEST_ITEMS_MULTI_GET
+            : MAX_RESPONSE_MANIFEST_ITEMS;
+        const responseSelectedIds = selection.selectedIds.slice(0, MAX_EXPOSURE_GET_ITEMS);
+        const selectedIdsTruncated = selection.selectedIds.length > responseSelectedIds.length;
+        const items = [];
+        for (const id of responseSelectedIds) {
+            const session = this.sessions.get(id);
+            if (!session) {
+                items.push(this.makeExposureGetNotFound(id, typedFields));
+                continue;
+            }
+            const detail = await this.buildExposureDetail(session, {
+                probe_public: params.opts?.probe_public,
+                include_manifest: manifestRequested,
+                manifest_limit: manifestLimit,
+            });
+            items.push(this.projectExposureDetail(detail, typedFields));
+        }
+        for (const missingId of selection.missingIds) {
+            items.push(this.makeExposureGetNotFound(missingId, typedFields));
+        }
+        return {
+            items,
+            count: items.length,
+            matched_ids: responseSelectedIds,
+            matched_total_count: selection.selectedIds.length,
+            matched_ids_truncated: selectedIdsTruncated,
+            missing_ids: selection.missingIds,
+            filter: params.filter,
+            fields: typedFields,
+        };
+    }
+    async stopExposure(idOrIds, opts) {
+        await this.ensureInitialized();
+        const requested = this.normalizeRequestedIds(Array.isArray(idOrIds) ? idOrIds : [idOrIds]);
+        if (requested.length === 0) {
+            return { stopped: [], failed: [{ id: "unknown", error: "id or ids is required" }], cleaned: [] };
+        }
+        const includeAll = requested.includes("all");
+        const ids = [];
+        const failed = [];
+        if (includeAll) {
+            ids.push(...Array.from(this.sessions.keys()));
+            if (ids.length === 0) {
+                return { stopped: [], failed: [{ id: "all", error: "not_found" }], cleaned: [] };
+            }
+        }
+        else {
+            for (const id of requested) {
+                if (this.sessions.has(id)) {
+                    ids.push(id);
+                }
+                else {
+                    failed.push({ id, error: "not_found" });
+                }
+            }
+        }
+        const stopIds = this.normalizeRequestedIds(ids);
+        if (stopIds.length === 0) {
+            return { stopped: [], failed, cleaned: [] };
+        }
+        const stopped = [];
+        const cleaned = [];
+        for (const id of stopIds) {
+            const session = this.sessions.get(id);
+            if (!session) {
+                failed.push({ id, error: "not_found" });
+                continue;
+            }
+            try {
+                if (session.timeoutHandle) {
+                    clearTimeout(session.timeoutHandle);
+                    session.timeoutHandle = undefined;
+                }
+                await this.terminateProcess(session.process);
+                if (session.proxyServer?.listening) {
+                    await new Promise((resolve) => session.proxyServer?.close(() => resolve()));
+                }
+                if (session.originServer?.listening) {
+                    await new Promise((resolve) => session.originServer?.close(() => resolve()));
+                }
+                if (session.workspaceDir && (await fileExists(session.workspaceDir))) {
+                    await fs.rm(session.workspaceDir, { recursive: true, force: true });
+                    cleaned.push(session.workspaceDir);
+                }
+                session.status = opts?.expired ? "expired" : "stopped";
+                if (opts?.reason) {
+                    session.lastError = opts.reason;
+                    this.appendLog(session, "manager", `stop reason: ${opts.reason}`);
+                }
+                stopped.push(id);
+                await this.writeAudit({
+                    ts: nowIso(),
+                    event: opts?.expired ? "exposure_expired" : "exposure_stopped",
+                    id: session.id,
+                    type: session.type,
+                    details: {
+                        reason: opts?.reason,
+                        public_url: session.publicUrl,
+                    },
+                });
+            }
+            catch (error) {
+                failed.push({ id, error: String(error) });
+            }
+            finally {
+                this.sessions.delete(id);
+            }
+        }
+        await this.persistSessionsSnapshot();
+        return { stopped, failed, cleaned };
+    }
+    exposureLogsOne(session, opts) {
+        const lines = Math.max(1, Math.min(MAX_EXPOSURE_LOG_LINES_RESPONSE, Math.trunc(opts?.lines ?? 200)));
+        const component = opts?.component ?? "all";
+        const threshold = typeof opts?.since_seconds === "number"
+            ? Date.now() - Math.max(1, Math.trunc(opts.since_seconds)) * 1000
+            : undefined;
+        const filtered = session.logs.filter((entry) => {
+            if (component !== "all" && entry.component !== component) {
+                return false;
+            }
+            if (threshold !== undefined && new Date(entry.ts).getTime() < threshold) {
+                return false;
+            }
+            return true;
+        });
+        return {
+            id: session.id,
+            component,
+            lines: filtered
+                .slice(-lines)
+                .map((entry) => `${entry.ts} [${entry.component}] ${entry.line}`),
+        };
+    }
+    exposureLogs(idOrIds, opts) {
+        const requested = this.normalizeRequestedIds(Array.isArray(idOrIds) ? idOrIds : [idOrIds]);
+        if (requested.length === 0) {
+            return { items: [], missing_ids: [], error: "id or ids is required" };
+        }
+        const includeAll = requested.includes("all");
+        const targetIds = includeAll ? Array.from(this.sessions.keys()) : requested;
+        const responseTargetIds = targetIds.slice(0, MAX_EXPOSURE_LOG_ITEMS);
+        const targetIdsTruncated = targetIds.length > responseTargetIds.length;
+        const singleLegacy = !Array.isArray(idOrIds) && !includeAll;
+        if (singleLegacy) {
+            const session = this.sessions.get(targetIds[0] ?? "");
+            if (!session) {
+                return { id: idOrIds, component: opts?.component ?? "all", lines: [], error: "not_found" };
+            }
+            return this.exposureLogsOne(session, opts);
+        }
+        const missingIds = [];
+        const items = [];
+        for (const id of responseTargetIds) {
+            const session = this.sessions.get(id);
+            if (!session) {
+                missingIds.push(id);
+                items.push({ id, component: opts?.component ?? "all", lines: [], error: "not_found" });
+                continue;
+            }
+            items.push(this.exposureLogsOne(session, opts));
+        }
+        return {
+            items,
+            requested_count: responseTargetIds.length,
+            requested_total_count: targetIds.length,
+            requested_ids_truncated: targetIdsTruncated,
+            found_count: responseTargetIds.length - missingIds.length,
+            missing_ids: missingIds,
+        };
+    }
+    async maintenance(action, opts) {
+        await this.ensureInitialized();
+        if (action === "start_guard") {
+            this.startGuard();
+            return {
+                ok: true,
+                action,
+                details: {
+                    running: Boolean(this.guardTimer),
+                },
+            };
+        }
+        if (action === "run_gc") {
+            const details = await this.runGc();
+            return { ok: true, action, details };
+        }
+        if (!opts?.policy && !opts?.ignore_patterns) {
+            return {
+                ok: false,
+                action,
+                details: "set_policy requires opts.policy or opts.ignore_patterns",
+            };
+        }
+        const current = await this.readPolicyJson();
+        const nextPolicy = this.deepMerge(current, (opts.policy ?? {}));
+        await fs.writeFile(this.policyFile, `${JSON.stringify(nextPolicy, null, 2)}\n`, "utf8");
+        if (Array.isArray(opts.ignore_patterns)) {
+            await fs.writeFile(this.ignoreFile, `${opts.ignore_patterns.join("\n")}\n`, "utf8");
+        }
+        await this.reloadPolicy();
+        await this.writeAudit({
+            ts: nowIso(),
+            event: "policy_updated",
+            details: {
+                policy_file: this.policyFile,
+            },
+        });
+        return {
+            ok: true,
+            action,
+            details: {
+                policy_file: this.policyFile,
+                ignore_file: this.ignoreFile,
+                effective: this.policy,
+            },
+        };
+    }
+    deepMerge(base, patch) {
+        const out = { ...base };
+        for (const [key, value] of Object.entries(patch)) {
+            if (value &&
+                typeof value === "object" &&
+                !Array.isArray(value) &&
+                typeof out[key] === "object" &&
+                out[key] !== null &&
+                !Array.isArray(out[key])) {
+                out[key] = this.deepMerge(out[key], value);
+            }
+            else {
+                out[key] = value;
+            }
+        }
+        return out;
+    }
+    async readPolicyJson() {
+        try {
+            const raw = await fs.readFile(this.policyFile, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object") {
+                return parsed;
+            }
+        }
+        catch {
+            // fallback to empty
+        }
+        return {};
+    }
+    async runGc() {
+        const removedWorkspaces = [];
+        const killedPids = [];
+        const activeWorkspaces = new Set(Array.from(this.sessions.values())
+            .map((session) => session.workspaceDir)
+            .filter((entry) => Boolean(entry)));
+        const workspaces = await fs.readdir(this.workspaceRoot, { withFileTypes: true }).catch(() => []);
+        for (const entry of workspaces) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const abs = path.join(this.workspaceRoot, entry.name);
+            if (activeWorkspaces.has(abs)) {
+                continue;
+            }
+            await fs.rm(abs, { recursive: true, force: true });
+            removedWorkspaces.push(abs);
+        }
+        try {
+            const raw = await fs.readFile(this.sessionsFile, "utf8");
+            const rows = JSON.parse(raw);
+            for (const row of rows ?? []) {
+                if (!row.processPid || this.sessions.has(String(row.id ?? ""))) {
+                    continue;
+                }
+                try {
+                    process.kill(row.processPid, 0);
+                    process.kill(row.processPid, "SIGTERM");
+                    killedPids.push(row.processPid);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        catch {
+            // ignore missing snapshot
+        }
+        await this.persistSessionsSnapshot();
+        await this.writeAudit({
+            ts: nowIso(),
+            event: "gc_run",
+            details: {
+                removed_workspaces: removedWorkspaces.length,
+                killed_pids: killedPids.length,
+            },
+        });
+        return {
+            removed_workspaces: removedWorkspaces,
+            killed_pids: killedPids,
+        };
+    }
+    async auditQuery(filters) {
+        await this.ensureInitialized();
+        const limit = Math.max(1, Math.min(10_000, Math.trunc(filters?.limit ?? 500)));
+        let raw = "";
+        try {
+            raw = await fs.readFile(this.auditFile, "utf8");
+        }
+        catch (error) {
+            if (error?.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+        const events = raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((event) => Boolean(event));
+        return events.filter((event) => matchAuditFilters(event, filters ?? {})).slice(-limit);
+    }
+    async auditExport(range) {
+        await this.ensureInitialized();
+        const events = await this.auditQuery({
+            id: range?.id,
+            event: range?.event,
+            type: range?.type,
+            from_ts: range?.from_ts,
+            to_ts: range?.to_ts,
+            limit: 10_000,
+        });
+        const outputPath = this.resolvePath(range?.output_path ?? path.join(this.exportsDir, `audit-${Date.now().toString(36)}.jsonl`));
+        await mkdirp(path.dirname(outputPath));
+        const data = events.map((event) => JSON.stringify(event)).join("\n");
+        await fs.writeFile(outputPath, data ? `${data}\n` : "", "utf8");
+        await this.writeAudit({
+            ts: nowIso(),
+            event: "audit_exported",
+            details: {
+                output_path: outputPath,
+                count: events.length,
+            },
+        });
+        return {
+            ok: true,
+            output_path: outputPath,
+            count: events.length,
+        };
+    }
+}