patchwarden 1.5.1 → 1.6.1

package/src/control/routes/sessions.ts

@@ -10,7 +10,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { type ServerResponse } from "node:http";
 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,
@@ -18,7 +18,7 @@ import {
   recordEvent,
   writeHiddenDirectSessionIds,
 } from "../runtime.js";
-import { config, errorMessage, readJsonFileSafe, readTextFileSafe, sendJson } from "../shared.js";
+import { config, errorMessage, guardControlPath, readJsonFileSafe, readTextFileSafe, sendJson } from "../shared.js";
 
 interface DirectSessionSummary {
   session_id: string;
@@ -91,19 +91,28 @@ function readDirectSessionSummary(sessionDir: string, sessionId: string): Direct
   };
 }
 
-export 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 function handleDirectSessions(res: ServerResponse, filters?: DirectSessionFilters): void {
   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: import("node:fs").Dirent[] = [];
     try {
       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.
@@ -111,32 +120,92 @@ export function handleDirectSessions(res: ServerResponse): void {
     const summaries: DirectSessionSummary[] = [];
     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?: DirectSessionFilters): Record<string, unknown> {
+  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: ServerResponse, sessionId: string): void {
   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;
     }
@@ -158,13 +227,7 @@ export function handleDirectSessionDetail(res: ServerResponse, sessionId: string
 
 export function handleDirectSessionSafeSummary(res: ServerResponse, sessionId: string): void {
   try {
-    if (
-      sessionId === "." ||
-      sessionId === ".." ||
-      sessionId.includes("/") ||
-      sessionId.includes("\\") ||
-      sessionId.includes("\0")
-    ) {
+    if (!isValidDirectSessionId(sessionId)) {
       sendJson(res, 400, { error: "Invalid session id" });
       return;
     }

package/src/control/routes/status.ts

@@ -9,8 +9,8 @@
  */
 import { existsSync } from "node:fs";
 import { type ServerResponse } from "node:http";
-import { type AgentAvailability } from "../../tools/listAgents.js";
-import { type TaskEntry } from "../../tools/listTasks.js";
+import { type AgentAvailability } from "../../tools/workspace/listAgents.js";
+import { type TaskEntry } from "../../tools/tasks/listTasks.js";
 import { type WatcherStatusSnapshot } from "../../watcherStatus.js";
 import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../../version.js";
 import { redactSensitiveValue } from "../../security/contentRedaction.js";
@@ -33,9 +33,9 @@ import {
 import { findTunnelClientExecutable } from "./process.js";
 import {
   config,
+  configIdentitySha256,
   controlCenterStatusPath,
   CORE_BASE_URL,
-  DEFAULT_TUNNEL_CLIENT_EXE,
   DIRECT_BASE_URL,
   errorMessage,
   readJsonFileSafe,
@@ -59,9 +59,78 @@ interface StatusSnapshotForSuggestions {
   tunnel: { core: Record<string, unknown>; direct: Record<string, unknown> };
   agents: AgentAvailability[];
   tasks: StatusTasks;
+  direct_profile_enabled: boolean;
 }
 
-function buildSuggestions(s: StatusSnapshotForSuggestions): Suggestion[] {
+export interface ExperienceStatus {
+  readiness: "ready" | "needs_action" | "blocked";
+  live_checks: Array<{
+    key: string;
+    label: string;
+    state: "ready" | "needs_action" | "blocked" | "optional";
+    detail: string;
+  }>;
+  historical_summary: {
+    stale_tasks: number;
+    failed_tasks: number;
+    note: string;
+  };
+}
+
+/**
+ * Keep current readiness separate from historical evidence. A month-old failed
+ * task is useful for audit, but must not make a configured local bridge look
+ * unavailable on the first screen.
+ */
+export function buildExperienceStatus(snapshot: StatusSnapshotForSuggestions): ExperienceStatus {
+  const coreReady = snapshot.core.available && snapshot.tunnel.core.ready === true;
+  const watcherReady = snapshot.watcher.status === "healthy";
+  const agentsReady = snapshot.agents.some((agent) => agent.available);
+  const directEnabled = snapshot.direct_profile_enabled;
+  const directReady = snapshot.direct.available && snapshot.tunnel.direct.ready === true;
+  const staleTasks = snapshot.tasks.stale;
+  const failedTasks = snapshot.tasks.tasks.filter((task) => String((task as TaskEntry).status || "").includes("failed")).length;
+
+  const live_checks: ExperienceStatus["live_checks"] = [
+    { key: "workspace_agents", label: "工作区与 Agent", state: agentsReady ? "ready" : "blocked", detail: agentsReady ? "工作区内至少有一个可用 Agent" : "需要配置工作区或可用 Agent" },
+    { key: "core", label: "Core 服务", state: coreReady ? "ready" : "needs_action", detail: coreReady ? "Core 与 Tunnel 已就绪" : "启动 Core 后会继续检查 Tunnel 与 Watcher" },
+    { key: "watcher", label: "任务监视器", state: watcherReady ? "ready" : "needs_action", detail: watcherReady ? "Watcher 心跳正常" : "Core 启动后 Watcher 将处理排队任务" },
+    { key: "direct", label: "Direct 编辑", state: directEnabled ? (directReady ? "ready" : "needs_action") : "optional", detail: directEnabled ? (directReady ? "Direct 已就绪" : "已启用但尚未就绪") : "可选高级能力，未启用不会影响 Core" },
+  ];
+
+  const readiness: ExperienceStatus["readiness"] = !agentsReady
+    ? "blocked"
+    : coreReady && watcherReady && (!directEnabled || directReady)
+      ? "ready"
+      : "needs_action";
+
+  return {
+    readiness,
+    live_checks,
+    historical_summary: {
+      stale_tasks: staleTasks,
+      failed_tasks: failedTasks,
+      note: "历史任务与审计记录不会影响当前实时就绪状态。",
+    },
+  };
+}
+
+export function reconcileTunnelStatus(
+  status: Record<string, unknown>,
+  health: RuntimeHealth,
+): Record<string, unknown> {
+  if (!health.available) return status;
+  return {
+    ...status,
+    observed: true,
+    status: "running",
+    ready: true,
+    reason_code: "health_endpoint_ready",
+    health_observed: true,
+  };
+}
+
+export function buildSuggestions(s: StatusSnapshotForSuggestions): Suggestion[] {
   const out: Suggestion[] = [];
 
   if (!s.core.available) {
@@ -72,7 +141,7 @@ function buildSuggestions(s: StatusSnapshotForSuggestions): Suggestion[] {
       action: "/api/core/start",
     });
   }
-  if (!s.direct.available) {
+  if (s.direct_profile_enabled && !s.direct.available) {
     out.push({
       code: "direct_stopped",
       severity: "warning",
@@ -81,12 +150,12 @@ function buildSuggestions(s: StatusSnapshotForSuggestions): Suggestion[] {
     });
   }
 
-  if (s.watcher.status === "stale" || s.watcher.status === "unreadable") {
+  if (s.watcher.status === "degraded" || s.watcher.status === "stale" || s.watcher.status === "unreadable") {
     out.push({
       code: "watcher_stale",
       severity: "error",
-      message: "Watcher 处于 " + s.watcher.status + " 状态，建议 Restart All",
-      action: "/api/restart-all",
+      message: "Watcher 处于 " + s.watcher.status + " 状态，建议重启 Core",
+      action: "/api/core/restart",
     });
   }
 
@@ -101,12 +170,12 @@ function buildSuggestions(s: StatusSnapshotForSuggestions): Suggestion[] {
 
   const coreTunnelReady = !!(s.tunnel.core && s.tunnel.core.ready);
   const directTunnelReady = !!(s.tunnel.direct && s.tunnel.direct.ready);
-  if (!coreTunnelReady || !directTunnelReady) {
+  if (!coreTunnelReady || (s.direct_profile_enabled && !directTunnelReady)) {
     out.push({
       code: "tunnel_not_ready",
       severity: "warning",
-      message: "Tunnel 未就绪，建议重启 profile 或检查代理",
-      action: "/api/restart-all",
+      message: "Tunnel 未就绪，建议启动 profile 或检查代理",
+      action: "/api/start-all",
     });
   }
 
@@ -115,7 +184,7 @@ function buildSuggestions(s: StatusSnapshotForSuggestions): Suggestion[] {
     out.push({
       code: "agent_missing",
       severity: "info",
-      message: "Agent 未就绪：" + missingAgents.map((a) => a.name).join(", ") + "（请检查 opencode/claude 路径）",
+      message: "Agent 未就绪：" + missingAgents.map((a) => a.name).join(", ") + "（请检查对应 CLI 安装与路径）",
     });
   }
 
@@ -169,7 +238,7 @@ function diffAndRecordEvents(prev: StatusSnapshotDigest, curr: StatusSnapshotDig
 
 export async function handleStatus(res: ServerResponse): Promise<void> {
   try {
-    const [coreHealth, directHealth, watcher, tunnelCore, tunnelDirect, toolsCore, toolsDirect, agents, workspaceRoot, tasks] = await Promise.all([
+    const [coreHealth, directHealth, watcher, tunnelCoreRaw, tunnelDirectRaw, toolsCore, toolsDirect, agents, workspaceRoot, tasks] = await Promise.all([
       probeRuntimeHealth(CORE_BASE_URL).catch((err): RuntimeHealth => ({
         available: false,
         reason: errorMessage(err),
@@ -191,6 +260,8 @@ export async function handleStatus(res: ServerResponse): Promise<void> {
       Promise.resolve(resolveWorkspaceRootSafe()),
       Promise.resolve(listTasksForStatus()),
     ]);
+    const tunnelCore = reconcileTunnelStatus(tunnelCoreRaw, coreHealth);
+    const tunnelDirect = reconcileTunnelStatus(tunnelDirectRaw, directHealth);
     const snapshotForSuggestions: StatusSnapshotForSuggestions = {
       core: coreHealth,
       direct: directHealth,
@@ -198,8 +269,10 @@ export async function handleStatus(res: ServerResponse): Promise<void> {
       tunnel: { core: tunnelCore, direct: tunnelDirect },
       agents,
       tasks,
+      direct_profile_enabled: config.enableDirectProfile === true,
     };
     const suggestions = buildSuggestions(snapshotForSuggestions);
+    const experience = buildExperienceStatus(snapshotForSuggestions);
     const tunnelClientExe = findTunnelClientExecutable();
 
     // Diff against the previous poll to record observed state-change events.
@@ -221,11 +294,13 @@ export async function handleStatus(res: ServerResponse): Promise<void> {
       workspace_root: workspaceRoot,
       tasks,
       suggestions,
+      experience,
+      direct_profile_enabled: config.enableDirectProfile === true,
       setup: {
         tunnel_client: {
           available: tunnelClientExe !== null,
           path: tunnelClientExe,
-          default_path: DEFAULT_TUNNEL_CLIENT_EXE,
+          source: config.tunnelClientPath && tunnelClientExe === config.tunnelClientPath ? "config" : "detected",
         },
         workspace_root: workspaceRoot,
         watcher: {
@@ -270,11 +345,15 @@ export function handleTunnelUiUrl(res: ServerResponse): void {
   });
 }
 
-export function handleDiagnostics(res: ServerResponse): void {
+export async function handleDiagnostics(res: ServerResponse): Promise<void> {
   try {
     const watcher = readWatcherStatusSafe();
-    const tunnelCore = readTunnelStatus(false);
-    const tunnelDirect = readTunnelStatus(true);
+    const [coreHealth, directHealth] = await Promise.all([
+      probeRuntimeHealth(CORE_BASE_URL),
+      probeRuntimeHealth(DIRECT_BASE_URL),
+    ]);
+    const tunnelCore = reconcileTunnelStatus(readTunnelStatus(false), coreHealth);
+    const tunnelDirect = reconcileTunnelStatus(readTunnelStatus(true), directHealth);
     const toolsCore = readToolManifest(false);
     const toolsDirect = readToolManifest(true);
     const agents = listAgentsSafe();
@@ -314,6 +393,7 @@ export function handleDiagnostics(res: ServerResponse): void {
       workspace_root: workspaceRoot,
       recent_failures: recentFailures,
       direct_profile_enabled: config.enableDirectProfile ?? false,
+      config_identity_sha256: configIdentitySha256,
     };
 
     // Redact any sensitive content that may have leaked into string fields.

package/src/control/routes/taskActions.ts

@@ -7,24 +7,25 @@
  * dashboard. None of them delete task files; they annotate or launch external
  * viewers.
  */
-import { existsSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { spawn } from "node:child_process";
 import { type ServerResponse } from "node:http";
-import { type TaskEntry } from "../../tools/listTasks.js";
-import type { AcceptanceStatus } from "../../tools/createTask.js";
-import { auditTask } from "../../tools/auditTask.js";
+import { auditTask } from "../../tools/diagnostics/auditTask.js";
 import { getTasksDir } from "../../config.js";
 import {
   classifyStaleTask,
   isValidTaskId,
   readHiddenStaleIds,
+  reconstructTaskEntry,
   readWatcherStatusSafe,
   recordEvent,
   TERMINAL_TASK_STATUSES,
   writeHiddenStaleIds,
 } from "../runtime.js";
-import { config, errorMessage, readJsonFileSafe, sendJson } from "../shared.js";
+import { launchFileManager } from "../fileManager.js";
+import { config, errorMessage, guardControlPath, readJsonFileSafe, sendJson } from "../shared.js";
+import { atomicWriteJsonFileSync } from "../../utils/atomicFile.js";
+import { mutateTaskStatus } from "../../runner/taskStatusStore.js";
 
 /**
  * Reconcile a stale task. Does NOT delete the task. Reads the task files,
@@ -39,8 +40,8 @@ export function handleReconcile(res: ServerResponse, taskId: string): void {
       return;
     }
     const tasksDir = getTasksDir(config);
-    const taskDir = join(tasksDir, taskId);
-    if (!existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+    const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+    if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
       sendJson(res, 404, { error: "Task not found" });
       return;
     }
@@ -51,33 +52,7 @@ export function handleReconcile(res: ServerResponse, taskId: string): void {
     const runtimeData = readJsonFileSafe<Record<string, unknown>>(runtimePath) ?? {};
 
     const watcher = readWatcherStatusSafe();
-    const VALID_ACCEPTANCE = ["pending", "accepted", "rejected", "needs_fix", "blocked"];
-    const taskStatus = String(statusData.status || "pending");
-    const taskAcceptanceStatus = taskStatus === "done_by_agent"
-      ? (typeof statusData.acceptance_status === "string" && VALID_ACCEPTANCE.includes(statusData.acceptance_status) ? (statusData.acceptance_status as AcceptanceStatus) : "pending" as AcceptanceStatus)
-      : null;
-    const taskEntry: TaskEntry = {
-      task_id: taskId,
-      plan_id: String(statusData.plan_id || ""),
-      title: "",
-      agent: String(statusData.agent || ""),
-      status: taskStatus as TaskEntry["status"],
-      phase: String(runtimeData.phase || statusData.phase || "queued") as TaskEntry["phase"],
-      acceptance_status: taskAcceptanceStatus,
-      created_at: String(statusData.created_at || ""),
-      updated_at: String(statusData.updated_at || ""),
-      workspace_root: String(statusData.workspace_root || config.workspaceRoot),
-      repo_path: String(statusData.repo_path || "."),
-      resolved_repo_path: String(statusData.resolved_repo_path || statusData.repo_path || config.workspaceRoot),
-      test_command: String(statusData.test_command || ""),
-      verify_commands: Array.isArray(statusData.verify_commands) ? (statusData.verify_commands as string[]) : [],
-      error: statusData.error ? String(statusData.error) : null,
-      last_heartbeat_at: String(runtimeData.last_heartbeat_at || statusData.last_heartbeat_at || statusData.updated_at || ""),
-      current_command: runtimeData.current_command === undefined ? null : String(runtimeData.current_command || "") || null,
-      timeout_seconds: Number(statusData.timeout_seconds) || config.defaultTaskTimeoutSeconds,
-      pending_reason: null,
-      watcher_status: watcher.status,
-    };
+    const taskEntry = reconstructTaskEntry(taskId, statusData, runtimeData, watcher);
 
     const cls = classifyStaleTask(taskEntry, watcher);
     const isTerminal = TERMINAL_TASK_STATUSES.has(taskEntry.status);
@@ -123,7 +98,7 @@ export function handleReconcile(res: ServerResponse, taskId: string): void {
 
     // Write the reconcile record artifact.
     try {
-      writeFileSync(join(taskDir, "reconcile.json"), JSON.stringify(reconcileRecord, null, 2), "utf-8");
+      atomicWriteJsonFileSync(join(taskDir, "reconcile.json"), reconcileRecord);
     } catch (writeErr) {
       sendJson(res, 500, { error: `Failed to write reconcile record: ${errorMessage(writeErr)}` });
       return;
@@ -131,13 +106,18 @@ export function handleReconcile(res: ServerResponse, taskId: string): void {
 
     // Annotate status.json with reconcile metadata (do not mutate status enum).
     if (safe) {
-      const annotated = {
-        ...statusData,
+      const annotation = {
         reconcile_state: decision === "marked_archived" ? "archived" : "stale",
         reconciled_at: reconciledAt,
       };
       try {
-        writeFileSync(statusPath, JSON.stringify(annotated, null, 2), "utf-8");
+        mutateTaskStatus(statusPath, (current) => {
+          if (current.status !== taskEntry.status) {
+            throw new Error("Task status changed while reconcile was being evaluated; retry.");
+          }
+          const next = { ...current, ...annotation, updated_at: new Date().toISOString() };
+          return { next, result: next };
+        });
       } catch (writeErr) {
         sendJson(res, 500, { error: `Failed to annotate status.json: ${errorMessage(writeErr)}` });
         return;
@@ -169,8 +149,8 @@ export function handleTaskAudit(res: ServerResponse, taskId: string): void {
       return;
     }
     const tasksDir = getTasksDir(config);
-    const taskDir = join(tasksDir, taskId);
-    if (!existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+    const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+    if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
       sendJson(res, 404, { error: "Task not found" });
       return;
     }
@@ -198,26 +178,12 @@ export function handleOpenTaskFolder(res: ServerResponse, taskId: string): void
       return;
     }
     const tasksDir = getTasksDir(config);
-    const taskDir = join(tasksDir, taskId);
-    if (!existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+    const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+    if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
       sendJson(res, 404, { error: "Task not found" });
       return;
     }
-    let cmd: string;
-    if (process.platform === "win32") {
-      cmd = "explorer.exe";
-    } else if (process.platform === "darwin") {
-      cmd = "open";
-    } else {
-      cmd = "xdg-open";
-    }
-    try {
-      const child = spawn(cmd, [taskDir], { detached: true, stdio: "ignore" });
-      child.on("error", () => { /* ignore spawn errors */ });
-      child.unref();
-    } catch {
-      /* ignore */
-    }
+    launchFileManager(taskDir, tasksDir);
     sendJson(res, 200, { ok: true, path: taskDir });
   } catch (err) {
     sendJson(res, 500, { error: errorMessage(err) });