patchwarden 1.5.1 → 1.6.2

package/dist/control/routes/process.js

@@ -8,17 +8,36 @@
  * launching, so the non-interactive web UI never deadlocks on a missing
  * dependency. All endpoints are POST routes gated by the control token.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { delimiter, extname, join } from "node:path";
 import { homedir } from "node:os";
 import { spawn } from "node:child_process";
+import { buildChildEnvironment, redactProcessOutput, resolveTrustedExecutable, sanitizeTrustedPath, } from "../../runner/processSecurity.js";
 import { recordEvent } from "../runtime.js";
-import { DEFAULT_TUNNEL_CLIENT_EXE, errorMessage, getRuntimeRoot, manageScriptPath, projectRoot, sendJson } from "../shared.js";
+import { launchFileManager } from "../fileManager.js";
+import { config, CORE_BASE_URL, DIRECT_BASE_URL, errorMessage, getRuntimeRoot, manageScriptPath, projectRoot, sendJson, } from "../shared.js";
+const MAX_MANAGE_OUTPUT_CHARS = 128 * 1024;
+const MANAGE_ALLOWED_ENVIRONMENT = [
+    "PATCHWARDEN_CONFIG",
+    "PATCHWARDEN_TUNNEL_ID",
+    "PATCHWARDEN_CREDENTIAL_PATH",
+    "PATCHWARDEN_TUNNEL_CLIENT_EXE",
+    "TUNNEL_CLIENT_EXE",
+    "OPENCODE_BIN_DIR",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NO_PROXY",
+];
 function runManageAction(action, mode) {
     return new Promise((resolveP, rejectP) => {
         let child;
+        let exactValues = [];
         try {
-            child = spawn("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", manageScriptPath, action, mode, "-Background"], { cwd: projectRoot, windowsHide: true });
+            const env = buildManageEnvironment();
+            exactValues = manageSensitiveValues(env);
+            const command = resolveTrustedExecutable("powershell.exe", projectRoot, { pathValue: env.PATH });
+            child = spawn(command, ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", manageScriptPath, action, mode, "-Background"], { cwd: projectRoot, windowsHide: true, env });
         }
         catch (err) {
             rejectP(err);
@@ -38,10 +57,10 @@ function runManageAction(action, mode) {
             rejectP(new Error(`manage-patchwarden.ps1 timed out after 60s (action=${action}, mode=${mode})`));
         }, 60_000);
         child.stdout.on("data", (d) => {
-            stdout += d.toString("utf-8");
+            stdout = appendBoundedManageOutput(stdout, d.toString("utf-8"));
         });
         child.stderr.on("data", (d) => {
-            stderr += d.toString("utf-8");
+            stderr = appendBoundedManageOutput(stderr, d.toString("utf-8"));
         });
         child.on("error", (err) => {
             if (settled)
@@ -55,21 +74,36 @@ function runManageAction(action, mode) {
                 return;
             settled = true;
             clearTimeout(timer);
-            resolveP({ exitCode: code ?? -1, stdout, stderr });
+            resolveP({
+                exitCode: code ?? -1,
+                stdout: redactProcessOutput(stdout, exactValues),
+                stderr: redactProcessOutput(stderr, exactValues),
+            });
         });
     });
 }
-function selectedControlModes(mode) {
+export function resolveManageProfiles(mode, action, directEnabled) {
     if (mode === "core" || mode === "direct")
-        return [mode];
-    return ["core", "direct"];
+        return { selected: [mode], skipped: [] };
+    if ((action === "start" || action === "restart") && !directEnabled)
+        return { selected: ["core"], skipped: ["direct"] };
+    return { selected: ["core", "direct"], skipped: [] };
+}
+function selectedControlModes(mode, action = "status") {
+    return resolveManageProfiles(mode, action, config.enableDirectProfile === true).selected;
+}
+function skippedControlModes(mode, action) {
+    return resolveManageProfiles(mode, action, config.enableDirectProfile === true).skipped;
+}
+function effectiveManageMode(modes) {
+    return modes.length === 1 ? modes[0] : "all";
 }
 function launcherPathForMode(mode) {
     const launcherName = mode === "direct" ? "Start-PatchWarden-Direct-Tunnel.cmd" : "Start-PatchWarden-Tunnel.cmd";
     return join(projectRoot, "scripts", "launchers", launcherName);
 }
 function findExecutableOnPath(fileName) {
-    const pathValue = process.env.PATH || "";
+    const pathValue = sanitizeTrustedPath(process.env.PATH || "", projectRoot);
     const extensions = process.platform === "win32"
         ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
         : [""];
@@ -77,12 +111,12 @@ function findExecutableOnPath(fileName) {
         if (!entry)
             continue;
         const direct = join(entry, fileName);
-        if (existsSync(direct))
+        if (isRegularFile(direct))
             return direct;
         if (process.platform === "win32" && !extname(fileName)) {
             for (const ext of extensions) {
                 const candidate = join(entry, fileName + ext.toLowerCase());
-                if (existsSync(candidate))
+                if (isRegularFile(candidate))
                     return candidate;
             }
         }
@@ -92,69 +126,302 @@ function findExecutableOnPath(fileName) {
 function findTunnelClientExecutable() {
     if (process.env.PATCHWARDEN_CONTROL_FORCE_MISSING_TUNNEL_CLIENT === "1")
         return null;
-    const explicit = process.env.TUNNEL_CLIENT_EXE || process.env.PATCHWARDEN_TUNNEL_CLIENT_EXE;
-    if (explicit && existsSync(explicit))
+    const configured = config.tunnelClientPath;
+    if (configured && isRegularFile(configured))
+        return configured;
+    const explicit = process.env.PATCHWARDEN_TUNNEL_CLIENT_EXE || process.env.TUNNEL_CLIENT_EXE;
+    if (explicit && isRegularFile(explicit))
         return explicit;
     const fromPath = findExecutableOnPath("tunnel-client.exe") ?? findExecutableOnPath("tunnel-client");
     if (fromPath)
         return fromPath;
     const candidates = [
-        DEFAULT_TUNNEL_CLIENT_EXE,
-        process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "patchwarden", "tunnel-client.exe") : null,
+        process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "PatchWarden", "tunnel-client.exe") : null,
         process.env.APPDATA ? join(process.env.APPDATA, "tunnel-client", "tunnel-client.exe") : null,
         join(homedir(), "tunnel-client", "tunnel-client.exe"),
     ].filter((v) => typeof v === "string" && v.length > 0);
     for (const candidate of candidates) {
-        if (existsSync(candidate))
+        if (isRegularFile(candidate))
             return candidate;
     }
     return null;
 }
+export function buildManageEnvironment() {
+    const agentEnvironmentNames = [...new Set(Object.values(config.agents)
+            .flatMap((agent) => agent.envAllowlist ?? []))];
+    const env = buildChildEnvironment({
+        cwd: projectRoot,
+        allowedNames: [...MANAGE_ALLOWED_ENVIRONMENT, ...agentEnvironmentNames],
+        blockedNames: [config.http?.ownerTokenEnv || "PATCHWARDEN_OWNER_TOKEN"],
+    });
+    const lifecycleNames = new Set(MANAGE_ALLOWED_ENVIRONMENT.map((name) => name.toUpperCase()));
+    const providerOnlyNames = agentEnvironmentNames.filter((name) => !lifecycleNames.has(name.toUpperCase()));
+    env.PATCHWARDEN_AGENT_ENV_ALLOWLIST = providerOnlyNames.join(";");
+    const tunnelClient = findTunnelClientExecutable();
+    if (tunnelClient) {
+        env.PATCHWARDEN_TUNNEL_CLIENT_EXE = tunnelClient;
+        env.TUNNEL_CLIENT_EXE = tunnelClient;
+    }
+    const proxy = config.tunnelProxy;
+    const core = proxy?.core || { mode: "environment" };
+    const direct = proxy?.scope === "separate" ? proxy.direct : core;
+    env.PATCHWARDEN_TUNNEL_PROXY_MODE = core.mode;
+    env.PATCHWARDEN_TUNNEL_PROXY_URL = core.mode === "manual" ? core.url || "" : "";
+    env.PATCHWARDEN_DIRECT_PROXY_MODE = direct.mode;
+    env.PATCHWARDEN_DIRECT_PROXY_URL = direct.mode === "manual" ? direct.url || "" : "";
+    return env;
+}
 // Re-exported so the status route can surface tunnel-client availability in
 // /api/status without duplicating the discovery logic.
 export { findTunnelClientExecutable };
+function profilePathForMode(mode) {
+    if (!process.env.APPDATA)
+        return null;
+    return join(process.env.APPDATA, "tunnel-client", mode === "direct" ? "patchwarden-direct.yaml" : "patchwarden.yaml");
+}
+function credentialPath() {
+    return process.env.APPDATA ? join(process.env.APPDATA, "patchwarden", "control-plane-api-key.dpapi") : null;
+}
 function preflightManageAction(action, mode) {
     if (action !== "start" && action !== "restart")
         return null;
-    const missingLaunchers = selectedControlModes(mode)
+    const selectedModes = selectedControlModes(mode, action);
+    const missingLaunchers = selectedModes
         .map((m) => ({ mode: m, path: launcherPathForMode(m) }))
         .filter((entry) => !existsSync(entry.path));
     const tunnelClient = findTunnelClientExecutable();
+    const missingProfiles = selectedModes
+        .map((m) => ({ mode: m, path: profilePathForMode(m) }))
+        .filter((entry) => !entry.path || !existsSync(entry.path));
+    const savedCredential = credentialPath();
     const missing = [];
     if (!tunnelClient)
         missing.push("tunnel-client.exe");
     for (const entry of missingLaunchers)
         missing.push(`${entry.mode} launcher`);
+    for (const entry of missingProfiles)
+        missing.push(`${entry.mode} profile`);
+    if (!savedCredential || !existsSync(savedCredential))
+        missing.push("tunnel runtime credential");
     if (missing.length === 0)
         return null;
+    const reasonCode = !tunnelClient
+        ? "tunnel_client_missing"
+        : missingLaunchers.length > 0
+            ? "launcher_missing"
+            : missingProfiles.length > 0
+                ? "tunnel_profile_missing"
+                : "tunnel_credential_missing";
     return {
         status: 409,
         body: {
             ok: false,
             action,
             mode,
+            reason_code: reasonCode,
             error: "Control Center preflight failed. Start/restart from the Web UI is non-interactive, so required runtime dependencies must be available before launching.",
             missing,
             next_steps: [
-                "Install tunnel-client.exe or set TUNNEL_CLIENT_EXE / PATCHWARDEN_TUNNEL_CLIENT_EXE to its full path.",
-                `Default checked path: ${DEFAULT_TUNNEL_CLIENT_EXE}`,
-                "Verify the launcher files under scripts/launchers are present.",
-                "Then retry from PatchWarden Control Center or PatchWarden-Control-Tray.cmd.",
+                "在桌面设置中自动检测或选择 tunnel-client.exe，也可设置 PATCHWARDEN_TUNNEL_CLIENT_EXE。",
+                "在桌面设置中配置 Tunnel ID 和专用 runtime API key，并完成 doctor 验证。",
+                "确认 scripts/launchers 下的启动器存在，然后重试。",
             ],
         },
     };
 }
+function preflightDirectProfile(action, mode) {
+    if ((action !== "start" && action !== "restart") || mode !== "direct")
+        return null;
+    if (config.enableDirectProfile === true)
+        return null;
+    return {
+        status: 409,
+        body: {
+            ok: false,
+            action,
+            mode,
+            reason_code: "direct_profile_disabled",
+            error: "Direct profile 尚未启用。请先在桌面设置中启用 Direct，再启动对应隧道。",
+            next_steps: ["打开 设置 -> MCP 与隧道", "启用 Direct profile 并保存", "重新启动 Direct"],
+        },
+    };
+}
+function readRuntimeState(mode, fileName) {
+    try {
+        return JSON.parse(readFileSync(join(getRuntimeRoot(mode === "direct"), fileName), "utf8").replace(/^\uFEFF/, ""));
+    }
+    catch {
+        return null;
+    }
+}
+function readRuntimeLog(mode, fileName) {
+    try {
+        const value = readFileSync(join(getRuntimeRoot(mode === "direct"), fileName), "utf8");
+        return value.length > 64_000 ? value.slice(-64_000) : value;
+    }
+    catch {
+        return "";
+    }
+}
+export function classifySupervisorFailure(diagnosticText) {
+    if (/unsupported_country_region_territory|unsupported.{0,30}(country|region|territory)/i.test(diagnosticText))
+        return "unsupported_region";
+    if (/\b(401|403)\b|unauthori[sz]ed|invalid.{0,30}(api.?key|credential)|api.?key.{0,30}(invalid|missing)/i.test(diagnosticText))
+        return "auth_failed";
+    if (/proxy|ECONNREFUSED|ENETUNREACH|ETIMEDOUT|could not resolve|name resolution|connection (failed|refused)/i.test(diagnosticText))
+        return "proxy_unreachable";
+    if (/tool manifest preflight|tool_manifest_(check_failed|invalid)|mcp-manifest-check/i.test(diagnosticText))
+        return "tool_manifest_check_failed";
+    if (/spawn EPERM|access (is )?denied|permission denied/i.test(diagnosticText))
+        return "supervisor_permission_denied";
+    if (/watcher.{0,40}(failed|unhealthy|missing|exited)/i.test(diagnosticText))
+        return "watcher_unhealthy";
+    if (/profile.{0,30}(missing|invalid)|config.{0,30}(missing|invalid)|launcher.{0,30}(missing|not found)/i.test(diagnosticText))
+        return "config_error";
+    return "supervisor_exited";
+}
+function processIsAlive(pid) {
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function inspectSupervisor(mode, startedAt) {
+    const state = readRuntimeState(mode, "supervisor-status.json");
+    const checkedAt = typeof state?.checked_at === "string" ? Date.parse(state.checked_at) : 0;
+    const fresh = Number.isFinite(checkedAt) && checkedAt >= startedAt - 2000;
+    if (!fresh)
+        return { terminal: false, reasonCode: null };
+    const explicitlyFailed = state?.status === "failed";
+    if (!explicitlyFailed && processIsAlive(state?.pid))
+        return { terminal: false, reasonCode: null };
+    const diagnostics = `${readRuntimeLog(mode, "supervisor.stderr.log")}\n${readRuntimeLog(mode, "supervisor.stdout.log")}`;
+    const recordedReason = typeof state?.reason_code === "string" ? state.reason_code : null;
+    return { terminal: true, reasonCode: recordedReason || classifySupervisorFailure(diagnostics) };
+}
+async function probeReady(baseUrl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1500);
+    try {
+        const response = await fetch(`${baseUrl}/readyz`, { signal: controller.signal, cache: "no-store" });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function inspectStartup(mode, startedAt) {
+    const tunnel = readRuntimeState(mode, "tunnel-status.json");
+    const checkedAt = typeof tunnel?.checked_at === "string" ? Date.parse(tunnel.checked_at) : 0;
+    const fresh = Number.isFinite(checkedAt) && checkedAt >= startedAt - 2000;
+    const endpointReady = await probeReady(mode === "direct" ? DIRECT_BASE_URL : CORE_BASE_URL);
+    const watcher = mode === "core" ? readRuntimeState(mode, "watcher-status.json") : null;
+    const watcherReady = mode === "direct" || watcher?.status === "healthy";
+    const ready = endpointReady && tunnel?.ready !== false && watcherReady;
+    const terminalStatuses = new Set(["failed", "error", "stopped", "restart_limit_reached"]);
+    const tunnelTerminal = fresh && terminalStatuses.has(String(tunnel?.status || "")) && tunnel?.reason_code !== "stopped_by_manager";
+    const supervisor = inspectSupervisor(mode, startedAt);
+    const terminal = tunnelTerminal || supervisor.terminal;
+    const reasonCode = tunnelTerminal
+        ? (typeof tunnel?.reason_code === "string" ? tunnel.reason_code : "startup_failed")
+        : supervisor.reasonCode;
+    return {
+        mode,
+        ready,
+        endpoint_ready: endpointReady,
+        watcher_ready: watcherReady,
+        status: tunnel?.status || "starting",
+        reason_code: reasonCode,
+        error: tunnel?.last_error || null,
+        terminal,
+    };
+}
+async function waitForStartup(modes, startedAt) {
+    const configured = Number(process.env.PATCHWARDEN_CONTROL_START_TIMEOUT_MS || "30000");
+    const timeoutMs = Number.isFinite(configured) ? Math.min(Math.max(configured, 1000), 120000) : 30000;
+    const deadline = Date.now() + timeoutMs;
+    let profiles = [];
+    while (Date.now() < deadline) {
+        profiles = await Promise.all(modes.map((mode) => inspectStartup(mode, startedAt)));
+        if (profiles.every((profile) => profile.ready === true))
+            return { ok: true, profiles };
+        const failed = profiles.find((profile) => profile.terminal === true);
+        if (failed) {
+            const reasonCode = typeof failed.reason_code === "string" ? failed.reason_code : "supervisor_exited";
+            return { ok: false, profiles, reasonCode };
+        }
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 500));
+    }
+    profiles = await Promise.all(modes.map((mode) => inspectStartup(mode, startedAt)));
+    return { ok: false, profiles, reasonCode: "startup_timeout" };
+}
 export async function handleManageAction(res, action, mode) {
     try {
+        const directPreflight = preflightDirectProfile(action, mode);
+        if (directPreflight) {
+            recordEvent("manage." + mode + "." + action + ".profile_disabled", { reason_code: "direct_profile_disabled" });
+            sendJson(res, directPreflight.status, directPreflight.body);
+            return;
+        }
+        const selectedModes = selectedControlModes(mode, action);
+        const skippedModes = skippedControlModes(mode, action);
+        const managedMode = effectiveManageMode(selectedModes);
         const preflight = preflightManageAction(action, mode);
         if (preflight) {
             recordEvent("manage." + mode + "." + action + ".preflight_failed", {
                 missing: preflight.body.missing,
             });
-            sendJson(res, preflight.status, preflight.body);
+            sendJson(res, preflight.status, {
+                ...preflight.body,
+                started_profiles: [],
+                skipped_profiles: skippedModes,
+            });
             return;
         }
-        const result = await runManageAction(action, mode);
+        const startedAt = Date.now();
+        const result = await runManageAction(action, managedMode);
+        if (result.exitCode !== 0) {
+            recordEvent("manage." + mode + "." + action, { exit_code: result.exitCode, ok: false });
+            sendJson(res, 500, {
+                ok: false,
+                action,
+                mode,
+                started_profiles: [],
+                skipped_profiles: skippedModes,
+                reason_code: "manager_failed",
+                error: result.stderr.trim() || result.stdout.trim() || `manage-patchwarden.ps1 exited with code ${result.exitCode}`,
+            });
+            return;
+        }
+        if (action === "start" || action === "restart") {
+            const startup = await waitForStartup(selectedModes, startedAt);
+            if (!startup.ok) {
+                const timeout = startup.reasonCode === "startup_timeout";
+                recordEvent("manage." + mode + "." + action + ".not_ready", { reason_code: startup.reasonCode, profiles: startup.profiles });
+                sendJson(res, timeout ? 504 : 502, {
+                    ok: false,
+                    action,
+                    mode,
+                    started_profiles: selectedModes,
+                    skipped_profiles: skippedModes,
+                    reason_code: startup.reasonCode,
+                    error: timeout
+                        ? "启动命令已执行，但服务未在等待时间内通过就绪检查。"
+                        : "隧道 supervisor 在服务就绪前退出。",
+                    profiles: startup.profiles,
+                    next_steps: ["检查设置中的 tunnel-client 与代理", "运行健康检查", "查看本次 Core / Direct 日志"],
+                });
+                return;
+            }
+        }
         recordEvent("manage." + mode + "." + action, {
             exit_code: result.exitCode,
             ok: result.exitCode === 0,
@@ -164,6 +431,10 @@ export async function handleManageAction(res, action, mode) {
             exitCode: result.exitCode,
             stdout: result.stdout,
             stderr: result.stderr,
+            verified: action === "start" || action === "restart",
+            started_profiles: action === "start" || action === "restart" ? selectedModes : [],
+            skipped_profiles: skippedModes,
+            reason_code: skippedModes.length > 0 ? "direct_profile_disabled" : null,
         });
     }
     catch (err) {
@@ -174,27 +445,43 @@ export async function handleManageAction(res, action, mode) {
 export function handleOpenLogsFolder(res) {
     try {
         const target = getRuntimeRoot(false);
-        let cmd;
-        if (process.platform === "win32") {
-            cmd = "explorer.exe";
-        }
-        else if (process.platform === "darwin") {
-            cmd = "open";
-        }
-        else {
-            cmd = "xdg-open";
-        }
-        try {
-            const child = spawn(cmd, [target], { detached: true, stdio: "ignore" });
-            child.on("error", () => { });
-            child.unref();
-        }
-        catch {
-            /* ignore */
-        }
+        launchFileManager(target, projectRoot);
         sendJson(res, 200, { ok: true, path: target });
     }
     catch (err) {
         sendJson(res, 500, { error: errorMessage(err) });
     }
 }
+function appendBoundedManageOutput(current, next) {
+    if (current.length >= MAX_MANAGE_OUTPUT_CHARS)
+        return current;
+    return current + next.slice(0, MAX_MANAGE_OUTPUT_CHARS - current.length);
+}
+function manageSensitiveValues(env) {
+    const agentEnvironmentValues = Object.values(config.agents)
+        .flatMap((agent) => agent.envAllowlist ?? [])
+        .map((name) => findEnvironmentValue(env, name));
+    const values = [
+        env.HTTP_PROXY,
+        env.HTTPS_PROXY,
+        env.ALL_PROXY,
+        env.PATCHWARDEN_TUNNEL_PROXY_URL,
+        env.PATCHWARDEN_DIRECT_PROXY_URL,
+        ...agentEnvironmentValues,
+    ].filter((value) => typeof value === "string" && Buffer.byteLength(value, "utf-8") >= 8);
+    return [...new Set(values)].sort((left, right) => right.length - left.length);
+}
+function findEnvironmentValue(env, name) {
+    if (process.platform !== "win32")
+        return env[name];
+    const match = Object.keys(env).find((key) => key.toUpperCase() === name.toUpperCase());
+    return match ? env[match] : undefined;
+}
+function isRegularFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/control/routes/sessions.d.ts

@@ -1,5 +1,13 @@
 import { type ServerResponse } from "node:http";
-export declare function handleDirectSessions(res: ServerResponse): void;
+export interface DirectSessionFilters {
+    state?: "active" | "archive" | "finalized" | "audited" | "expired";
+    repo_path?: string;
+    date_from?: string;
+    date_to?: string;
+    limit?: number;
+    cursor?: string;
+}
+export declare function handleDirectSessions(res: ServerResponse, filters?: DirectSessionFilters): void;
 export declare function handleDirectSessionDetail(res: ServerResponse, sessionId: string): void;
 export declare function handleDirectSessionSafeSummary(res: ServerResponse, sessionId: string): void;
 /**

package/dist/control/routes/sessions.js

@@ -9,9 +9,9 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { getDirectSessionsDir } from "../../config.js";
-import { safeAuditDirectSession, safeDirectSummary, safeFinalizeDirectSession } from "../../tools/safeViews.js";
+import { safeAuditDirectSession, safeDirectSummary, safeFinalizeDirectSession } from "../../tools/diagnostics/safeViews.js";
 import { fileMtimeIso, isValidDirectSessionId, readHiddenDirectSessionIds, recordEvent, writeHiddenDirectSessionIds, } from "../runtime.js";
-import { config, errorMessage, readJsonFileSafe, readTextFileSafe, sendJson } from "../shared.js";
+import { config, errorMessage, guardControlPath, readJsonFileSafe, readTextFileSafe, sendJson } from "../shared.js";
 function readDirectSessionSummary(sessionDir, sessionId) {
     const sessionFile = join(sessionDir, "session.json");
     if (!existsSync(sessionFile))
@@ -64,12 +64,12 @@ function readDirectSessionSummary(sessionDir, sessionId) {
         title: typeof data.title === "string" ? data.title : "",
     };
 }
-export function handleDirectSessions(res) {
+export function handleDirectSessions(res, filters) {
     try {
         const sessionsDir = getDirectSessionsDir(config);
         if (!existsSync(sessionsDir)) {
             // Directory missing -> empty list, never 500.
-            sendJson(res, 200, { sessions: [], total: 0, reason: null });
+            sendJson(res, 200, emptyDirectSessionResponse(filters));
             return;
         }
         let entries = [];
@@ -77,7 +77,7 @@ export function handleDirectSessions(res) {
             entries = readdirSync(sessionsDir, { withFileTypes: true }).filter((e) => e.isDirectory());
         }
         catch (err) {
-            sendJson(res, 200, { sessions: [], total: 0, reason: errorMessage(err) });
+            sendJson(res, 200, { ...emptyDirectSessionResponse(filters), reason: errorMessage(err) });
             return;
         }
         // Filter out sessions hidden from the dashboard via POST .../hide.
@@ -86,31 +86,98 @@ export function handleDirectSessions(res) {
         for (const entry of entries) {
             if (hiddenIds.has(entry.name))
                 continue;
-            const summary = readDirectSessionSummary(join(sessionsDir, entry.name), entry.name);
+            const sessionDir = guardControlPath(join(sessionsDir, entry.name), config.directSessionsDir);
+            if (!sessionDir)
+                continue;
+            const summary = readDirectSessionSummary(sessionDir, entry.name);
             if (summary)
                 summaries.push(summary);
         }
-        // Sort by created_at descending.
+        // Sort by created_at descending, then apply archive filters and pagination.
         summaries.sort((a, b) => b.created_at.localeCompare(a.created_at));
-        sendJson(res, 200, { sessions: summaries, total: summaries.length, reason: null });
+        const now = Date.now();
+        let filtered = summaries;
+        if (filters?.state) {
+            filtered = filtered.filter((session) => {
+                const expired = Boolean(session.expires_at) && Date.parse(session.expires_at) < now;
+                if (filters.state === "archive")
+                    return session.finalized || session.audited || expired;
+                if (filters.state === "expired")
+                    return expired;
+                if (filters.state === "audited")
+                    return session.audited && !expired;
+                if (filters.state === "finalized")
+                    return session.finalized && !session.audited && !expired;
+                return !session.finalized && !expired;
+            });
+        }
+        if (filters?.repo_path)
+            filtered = filtered.filter((session) => session.repo_path === filters.repo_path);
+        if (filters?.date_from || filters?.date_to) {
+            const from = filters.date_from ? Date.parse(`${filters.date_from}T00:00:00`) : Number.NEGATIVE_INFINITY;
+            const to = filters.date_to ? Date.parse(`${filters.date_to}T23:59:59`) : Number.POSITIVE_INFINITY;
+            filtered = filtered.filter((session) => {
+                const timestamp = Date.parse(session.created_at);
+                return Number.isFinite(timestamp) && timestamp >= from && timestamp <= to;
+            });
+        }
+        const limit = Math.max(10, Math.min(filters?.limit || 30, 100));
+        const offset = filters?.cursor && /^\d+$/.test(filters.cursor) ? Number(filters.cursor) : 0;
+        const sessions = filtered.slice(offset, offset + limit);
+        const nextCursor = offset + sessions.length < filtered.length ? String(offset + sessions.length) : null;
+        const repos = [...new Set(summaries.map((session) => session.repo_path).filter(Boolean))].sort();
+        sendJson(res, 200, {
+            sessions,
+            total: filtered.length,
+            returned: sessions.length,
+            nextCursor,
+            next_cursor: nextCursor,
+            filters: {
+                applied: {
+                    state: filters?.state || null,
+                    repo_path: filters?.repo_path || null,
+                    date_from: filters?.date_from || null,
+                    date_to: filters?.date_to || null,
+                },
+                options: { repos, states: ["active", "archive", "finalized", "audited", "expired"] },
+            },
+            direct_profile_enabled: config.enableDirectProfile === true,
+            reason: null,
+        });
     }
     catch (err) {
-        sendJson(res, 200, { sessions: [], total: 0, reason: errorMessage(err) });
+        sendJson(res, 200, { ...emptyDirectSessionResponse(filters), reason: errorMessage(err) });
     }
 }
+function emptyDirectSessionResponse(filters) {
+    return {
+        sessions: [],
+        total: 0,
+        returned: 0,
+        nextCursor: null,
+        next_cursor: null,
+        filters: {
+            applied: {
+                state: filters?.state || null,
+                repo_path: filters?.repo_path || null,
+                date_from: filters?.date_from || null,
+                date_to: filters?.date_to || null,
+            },
+            options: { repos: [], states: ["active", "archive", "finalized", "audited", "expired"] },
+        },
+        direct_profile_enabled: config.enableDirectProfile === true,
+        reason: null,
+    };
+}
 export function handleDirectSessionDetail(res, sessionId) {
     try {
-        if (sessionId === "." ||
-            sessionId === ".." ||
-            sessionId.includes("/") ||
-            sessionId.includes("\\") ||
-            sessionId.includes("\0")) {
+        if (!isValidDirectSessionId(sessionId)) {
             sendJson(res, 400, { error: "Invalid session id" });
             return;
         }
         const sessionsDir = getDirectSessionsDir(config);
-        const sessionDir = join(sessionsDir, sessionId);
-        if (!existsSync(sessionDir) || !statSync(sessionDir).isDirectory()) {
+        const sessionDir = guardControlPath(join(sessionsDir, sessionId), config.directSessionsDir);
+        if (!sessionDir || !existsSync(sessionDir) || !statSync(sessionDir).isDirectory()) {
             sendJson(res, 404, { error: "Direct session not found" });
             return;
         }
@@ -132,11 +199,7 @@ export function handleDirectSessionDetail(res, sessionId) {
 }
 export function handleDirectSessionSafeSummary(res, sessionId) {
     try {
-        if (sessionId === "." ||
-            sessionId === ".." ||
-            sessionId.includes("/") ||
-            sessionId.includes("\\") ||
-            sessionId.includes("\0")) {
+        if (!isValidDirectSessionId(sessionId)) {
             sendJson(res, 400, { error: "Invalid session id" });
             return;
         }