patchwarden 0.4.0

package/src/tools/getTaskSummary.ts

@@ -0,0 +1,307 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig, getTasksDir } from "../config.js";
+import { guardReadPath } from "../security/pathGuard.js";
+import { getTaskStatus } from "./getTaskStatus.js";
+import { redactSensitiveValue } from "../security/contentRedaction.js";
+
+const TERMINAL_STATUSES = new Set([
+  "done",
+  "failed",
+  "failed_verification",
+  "failed_scope_violation",
+  "failed_policy_violation",
+  "canceled",
+]);
+
+export interface TaskSummaryOutput {
+  task_id: string;
+  status: string;
+  terminal: boolean;
+  acceptance_status: "pending" | "ready_for_review" | "needs_review" | "failed";
+  acceptance_reviewed_at: string | null;
+  acceptance_reviewer: string | null;
+  phase: string;
+  agent: string;
+  workspace_root: string;
+  repo_path: string;
+  resolved_repo_path: string;
+  changed_files: unknown[];
+  out_of_scope_changes: unknown[];
+  workspace_dirty_before: boolean;
+  workspace_dirty_after: boolean;
+  verify_status: string;
+  verify_commands: unknown[];
+  last_heartbeat_at: string;
+  current_command: string | null;
+  elapsed_ms: number;
+  summary: string;
+  test_summary: string;
+  diff_available: boolean;
+  diff_truncated: boolean;
+  result_available: boolean;
+  result_json_available: boolean;
+  verify_available: boolean;
+  test_log_available: boolean;
+  warnings: string[];
+  errors: string[];
+  artifacts: Record<string, boolean>;
+  plan_source: string;
+  template: string | null;
+  change_policy: string;
+  failure_reason: string | null;
+  failed_command: string | null;
+  suggested_next_action: string;
+  safe_followup_prompt: string | null;
+  verification_summary: {
+    status: string;
+    command_count: number;
+    passed_commands: number;
+    failed_commands: number;
+    skipped_commands: number;
+    headline: string;
+  };
+  failed_command_detail: {
+    command: string;
+    exit_code: number | null;
+    stderr_tail: string;
+    duration_ms: number;
+  } | null;
+  log_tails: {
+    stdout: string;
+    stderr: string;
+    test: string;
+    verify: string;
+  };
+  redacted: boolean;
+  redaction_categories: string[];
+  watcher: unknown;
+  pending_reason: string | null;
+  execution_blocked: boolean;
+}
+
+export function getTaskSummary(taskId: string): TaskSummaryOutput {
+  const config = getConfig();
+  const taskDir = resolve(getTasksDir(config), taskId);
+  const statusFile = join(taskDir, "status.json");
+  guardReadPath(statusFile, config.workspaceRoot, config.tasksDir);
+  const status = getTaskStatus(taskId) as any;
+  const resultRead = tryReadJson(join(taskDir, "result.json"));
+  const verifyRead = tryReadJson(join(taskDir, "verify.json"));
+  const result = resultRead.data;
+  const verify = verifyRead.data;
+  const terminal = TERMINAL_STATUSES.has(String(status.status));
+  const outOfScope = asArray(result.out_of_scope_changes ?? status.out_of_scope_changes);
+  const verifyStatus = String(verify.status ?? result.verify_status ?? result.verify?.status ?? status.verify_status ?? "not_available");
+  const errors = [status.error, ...asArray(result.errors), ...asArray(result.known_issues)]
+    .filter((value): value is string => typeof value === "string" && value.trim() !== "");
+  const warnings = asArray(result.warnings).filter((value): value is string => typeof value === "string");
+  const artifacts = Object.fromEntries([
+    "result.md",
+    "result.json",
+    "diff.patch",
+    "git.diff",
+    "test.log",
+    "verify.log",
+    "verify.json",
+    "changed-files.json",
+    "file-stats.json",
+    "rollback_scope_violation_plan.md",
+  ].map((name) => [name, existsSync(join(taskDir, name))]));
+
+  for (const required of ["result.md", "result.json", "diff.patch", "file-stats.json", "test.log", "verify.json"]) {
+    if (!artifacts[required]) warnings.push(`${required} is missing.`);
+  }
+  if (resultRead.error) warnings.push(`result.json could not be parsed; using status.json/result.md fallback: ${resultRead.error}`);
+  if (verifyRead.error) warnings.push(`verify.json could not be parsed; using status.json fallback: ${verifyRead.error}`);
+
+  let acceptanceStatus: TaskSummaryOutput["acceptance_status"] = "pending";
+  let acceptanceReviewedAt: string | null = null;
+  let acceptanceReviewer: string | null = null;
+
+  // Check for explicit human acceptance (takes precedence over computed status)
+  const acceptanceFile = join(taskDir, "acceptance.json");
+  if (existsSync(acceptanceFile)) {
+    try {
+      const acceptance = JSON.parse(readFileSync(acceptanceFile, "utf-8"));
+      if (acceptance.status === "accepted") {
+        acceptanceStatus = "ready_for_review";
+        acceptanceReviewedAt = acceptance.reviewed_at || null;
+        acceptanceReviewer = acceptance.reviewer || null;
+      } else if (acceptance.status === "rejected") {
+        acceptanceStatus = "failed";
+        acceptanceReviewedAt = acceptance.reviewed_at || null;
+        acceptanceReviewer = acceptance.reviewer || null;
+        if (acceptance.notes) {
+          warnings.push(`Task was rejected by ${acceptance.reviewer || "human"} at ${acceptance.reviewed_at || "unknown time"}: ${acceptance.notes}`);
+        }
+      }
+    } catch {
+      warnings.push("acceptance.json exists but could not be parsed.");
+    }
+  } else if (terminal) {
+    if (status.status !== "done" || outOfScope.length > 0 || verifyStatus === "failed") {
+      acceptanceStatus = "failed";
+    } else if (verifyStatus === "passed") {
+      acceptanceStatus = "ready_for_review";
+    } else {
+      acceptanceStatus = "needs_review";
+      warnings.push("No passing verify_commands evidence is available; manual review is required.");
+    }
+  }
+
+  const startedAt = Date.parse(String(status.started_at || status.created_at || ""));
+  const finishedAt = Date.parse(String(status.finished_at || ""));
+  const elapsedMs = Number.isFinite(startedAt)
+    ? Math.max(0, (Number.isFinite(finishedAt) ? finishedAt : Date.now()) - startedAt)
+    : 0;
+  const changedFiles = asArray(result.changed_files ?? status.changed_files);
+  const verifyCommands = asArray(verify.commands ?? result.verify_commands ?? result.verify?.commands);
+  const testLogSummary = summarizeTestLog(join(taskDir, "test.log"));
+  const verificationSummary = buildVerificationSummary(verifyStatus, verifyCommands, testLogSummary);
+
+  // Extract failed command detail from verify records
+  const failedVerify = (verifyCommands as any[]).find((cmd: any) =>
+    ["failed", "timed_out", "canceled"].includes(cmd?.status)
+  );
+  const failedCommandDetail = failedVerify ? {
+    command: String(failedVerify.command || ""),
+    exit_code: failedVerify.exit_code ?? null,
+    stderr_tail: String(failedVerify.stderr_tail || "").slice(0, 500),
+    duration_ms: Number(failedVerify.duration_ms || 0),
+  } : null;
+
+  // Collect log tails (last 5 lines of each log)
+  const logTails = {
+    stdout: readLogTail(join(taskDir, "stdout.log"), 5),
+    stderr: readLogTail(join(taskDir, "stderr.log"), 5),
+    test: readLogTail(join(taskDir, "test.log"), 5),
+    verify: readLogTail(join(taskDir, "verify.log"), 5),
+  };
+
+  const output = {
+    task_id: taskId,
+    status: String(status.status || "unknown"),
+    terminal,
+    acceptance_status: acceptanceStatus,
+    acceptance_reviewed_at: acceptanceReviewedAt,
+    acceptance_reviewer: acceptanceReviewer,
+    phase: String(status.phase || "unknown"),
+    agent: String(status.agent || result.agent || ""),
+    workspace_root: String(status.workspace_root || result.workspace_root || config.workspaceRoot),
+    repo_path: String(status.repo_path || result.repo_path || ""),
+    resolved_repo_path: String(status.resolved_repo_path || result.resolved_repo_path || ""),
+    changed_files: changedFiles,
+    out_of_scope_changes: outOfScope,
+    workspace_dirty_before: Boolean(status.workspace_dirty_before ?? result.workspace_dirty_before),
+    workspace_dirty_after: Boolean(status.workspace_dirty_after ?? status.workspace_dirty ?? result.workspace_dirty_after),
+    verify_status: verifyStatus,
+    verify_commands: verifyCommands,
+    last_heartbeat_at: String(status.last_heartbeat_at || status.updated_at || ""),
+    current_command: status.current_command ?? null,
+    elapsed_ms: elapsedMs,
+    summary: String(result.summary || readResultFallback(join(taskDir, "result.md")) || status.error || `Task is ${status.status || "unknown"}.`),
+    test_summary: verificationSummary.headline,
+    diff_available: Boolean(
+      (status.diff_available ?? (changedFiles.length > 0)) &&
+      (artifacts["diff.patch"] || artifacts["git.diff"])
+    ),
+    diff_truncated: Boolean(status.diff_truncated || result.warnings?.some?.((warning: string) => warning.includes("diff.patch was truncated"))),
+    result_available: artifacts["result.md"],
+    result_json_available: artifacts["result.json"],
+    verify_available: artifacts["verify.json"],
+    test_log_available: artifacts["test.log"],
+    warnings: [...new Set(warnings)],
+    errors: [...new Set(errors)],
+    artifacts,
+    plan_source: String(status.plan_source || result.plan_source || "saved"),
+    template: status.template || result.template || null,
+    change_policy: String(status.change_policy || result.change_policy || "repo_scoped_changes"),
+    failure_reason: result.failure_reason || status.error || null,
+    failed_command: result.failed_command || null,
+    suggested_next_action: String(result.suggested_next_action || (terminal ? "audit_task" : status.execution_blocked ? "health_check" : "wait_for_task")),
+    safe_followup_prompt: result.safe_followup_prompt || null,
+    verification_summary: verificationSummary,
+    failed_command_detail: failedCommandDetail,
+    log_tails: logTails,
+    watcher: status.watcher,
+    pending_reason: status.pending_reason || null,
+    execution_blocked: Boolean(status.execution_blocked),
+  };
+  const safe = redactSensitiveValue(output);
+  return {
+    ...safe.value,
+    redacted: safe.redacted,
+    redaction_categories: safe.redaction_categories,
+  } as TaskSummaryOutput;
+}
+
+function tryReadJson(path: string): { data: Record<string, any>; error?: string } {
+  if (!existsSync(path)) return { data: {} };
+  try {
+    return { data: JSON.parse(readFileSync(path, "utf-8")) };
+  } catch (error) {
+    return { data: {}, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function asArray(value: unknown): any[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function summarizeTestLog(path: string): string {
+  if (!existsSync(path)) return "test.log missing";
+  const text = readFileSync(path, "utf-8");
+  const exit = text.match(/Exit\s*code:\s*([^\r\n]+)/i)?.[1]?.trim();
+  return exit ? `Exit code: ${exit}` : text.trim().slice(0, 500) || "test.log empty";
+}
+
+function readResultFallback(path: string): string {
+  if (!existsSync(path)) return "";
+  const text = readFileSync(path, "utf-8");
+  return text.match(/## Summary\s+([\s\S]*?)(?:\n## |\n---|$)/i)?.[1]?.trim().slice(0, 1000) || "";
+}
+
+function buildVerificationSummary(status: string, commands: any[], testLogSummary: string) {
+  const passed = commands.filter((command) => command?.status === "passed").length;
+  const failed = commands.filter((command) => ["failed", "timed_out", "canceled"].includes(command?.status)).length;
+  const skipped = commands.filter((command) => command?.status === "skipped").length;
+  const evidenceText = [
+    ...commands.flatMap((command) => [command?.stdout_tail, command?.stderr_tail]),
+    testLogSummary,
+  ].filter((value): value is string => typeof value === "string").join("\n");
+  const headline = extractTestHeadline(evidenceText)
+    || (commands.length > 0 ? `${passed}/${commands.length} verification commands passed` : testLogSummary);
+  return {
+    status,
+    command_count: commands.length,
+    passed_commands: passed,
+    failed_commands: failed,
+    skipped_commands: skipped,
+    headline,
+  };
+}
+
+function extractTestHeadline(text: string): string {
+  const patterns = [
+    /\b\d+\s+passed(?:,\s*\d+\s+failed)?\b/i,
+    /\b\d+\s+tests?\s+passed\b/i,
+    /\btests?:\s*\d+\s+passed(?:,\s*\d+\s+failed)?\b/i,
+  ];
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (match) return match[0];
+  }
+  return "";
+}
+
+function readLogTail(path: string, lines: number): string {
+  if (!existsSync(path)) return "(file not found)";
+  try {
+    const raw = readFileSync(path, "utf-8");
+    if (raw.length === 0) return "(empty)";
+    return raw.split("\n").slice(-lines).join("\n");
+  } catch {
+    return "(unreadable)";
+  }
+}

package/src/tools/healthCheck.ts

@@ -0,0 +1,234 @@
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { getConfig, getTasksDir, resolveWorkspaceRoot } from "../config.js";
+import { listAgents } from "./listAgents.js";
+import { redactSensitiveContent, redactSensitiveValue } from "../security/contentRedaction.js";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
+import type { ToolCatalogSnapshot } from "./toolCatalog.js";
+import { CHATGPT_CORE_TOOL_NAMES, resolveToolProfile } from "./toolCatalog.js";
+import { readWatcherStatus } from "../watcherStatus.js";
+import { listTasks } from "./listTasks.js";
+
+const SERVER_STARTED_AT = Date.now();
+
+export interface HealthCheckInput {
+  detail?: "standard" | "self_diagnostic";
+}
+
+export function healthCheck(catalog?: ToolCatalogSnapshot, input: HealthCheckInput = {}) {
+  const config = getConfig();
+  const workspaceRoot = resolveWorkspaceRoot(config);
+  const tasksDir = getTasksDir(config);
+  const watcher = {
+    ...readWatcherStatus(config),
+    supervisor: readWatcherSupervisorStatus(),
+  };
+
+  const agents = listAgents();
+  const workspace = directoryStatus(workspaceRoot, false);
+  const tasks = directoryStatus(tasksDir, true, workspaceRoot);
+  const tunnel = readTunnelStatus();
+
+  // Profile consistency: verify catalog matches the active profile
+  const profileErrors: string[] = [];
+  let profileConsistent = true;
+  if (catalog) {
+    const activeProfile = resolveToolProfile(config.toolProfile);
+    const expectedNames = activeProfile === "chatgpt_core"
+      ? [...CHATGPT_CORE_TOOL_NAMES]
+      : null; // full profile: all tools are accepted
+    if (expectedNames) {
+      const catalogNames = new Set(catalog.tool_names);
+      for (const name of expectedNames) {
+        if (!catalogNames.has(name)) {
+          profileErrors.push(`Expected tool "${name}" is missing from the active ${activeProfile} profile catalog.`);
+          profileConsistent = false;
+        }
+      }
+      if (catalog.tool_count !== expectedNames.length) {
+        profileErrors.push(
+          `Profile ${activeProfile} expects ${expectedNames.length} tools but catalog reports ${catalog.tool_count}. This can cause tools to appear in the list but fail when called.`
+        );
+        profileConsistent = false;
+      }
+    }
+  } else {
+    profileErrors.push("No tool catalog snapshot available; profile consistency cannot be verified.");
+    profileConsistent = false;
+  }
+
+  const mismatchReport = [...profileErrors];
+  let tunnelCatalogComparison = "unavailable";
+  if (catalog && typeof tunnel.tool_profile === "string" && tunnel.tool_profile) {
+    if (tunnel.tool_profile !== catalog.tool_profile) {
+      tunnelCatalogComparison = "different_profile";
+    } else if (typeof tunnel.tool_manifest_sha256 === "string" && tunnel.tool_manifest_sha256) {
+      tunnelCatalogComparison = tunnel.tool_manifest_sha256 === catalog.tool_manifest_sha256 ? "match" : "mismatch";
+      if (tunnelCatalogComparison === "mismatch") {
+        mismatchReport.push("The active MCP catalog hash differs from the tunnel startup manifest. Restart the owned tunnel process.");
+      }
+    }
+  }
+
+  const agentReady = agents.agents.every((agent) => agent.available);
+  const catalogConsistent = profileConsistent && mismatchReport.length === 0;
+  const status = watcher.available && workspace.available && tasks.available && agentReady && catalogConsistent
+    ? "healthy"
+    : "degraded";
+  return {
+    status,
+    server_version: catalog?.server_version || PATCHWARDEN_VERSION,
+    schema_epoch: catalog?.schema_epoch || TOOL_SCHEMA_EPOCH,
+    tool_profile: catalog?.tool_profile || "unknown",
+    tool_count: catalog?.tool_count ?? null,
+    tool_names: catalog?.tool_names || [],
+    tool_manifest_sha256: catalog?.tool_manifest_sha256 || null,
+    profile_consistent: profileConsistent,
+    profile_errors: profileErrors,
+    catalog_consistent: catalogConsistent,
+    mismatch_report: mismatchReport,
+    tunnel_catalog_comparison: tunnelCatalogComparison,
+    connector_visibility: {
+      status: "not_observable_server_side",
+      verification: "Refresh or reconnect the Connector and verify tools/list from a new ChatGPT conversation.",
+      refresh_steps: [
+        "1. Run Check-PatchWarden-Health.cmd to confirm tool_profile=chatgpt_core, tool_count=16, and catalog_consistent=true.",
+        "2. In ChatGPT Platform, refresh or reconnect the Connector (do not reuse an old session).",
+        "3. Open a NEW ChatGPT conversation (old conversations retain their cached tool catalog).",
+        "4. Call health_check in the new conversation; verify tool_manifest_sha256 matches the local report.",
+      ],
+    },
+    mcp_server: {
+      available: true,
+      pid: process.pid,
+      uptime_seconds: Math.round((Date.now() - SERVER_STARTED_AT) / 1000),
+      checked_at: new Date().toISOString(),
+    },
+    watcher,
+    workspace_root: workspace,
+    tasks_dir: tasks,
+    tunnel,
+    agents: agents.agents,
+    agent_status: Object.fromEntries(agents.agents.map((agent) => [agent.name, agent.available ? "ok" : "missing"])),
+    ...(input.detail === "self_diagnostic" ? { self_diagnostic: buildSelfDiagnostic(config) } : {}),
+    last_error: tunnel.last_error || (!watcher.available ? watcher.reason : null) || mismatchReport[0] || null,
+  };
+}
+
+function buildSelfDiagnostic(config: ReturnType<typeof getConfig>) {
+  const recent = listTasks({ limit: 20 });
+  const failures = recent.tasks
+    .filter((task) => task.status.startsWith("failed") || task.status === "canceled")
+    .slice(0, 10)
+    .map((task) => ({
+      task_id: task.task_id,
+      status: task.status,
+      phase: task.phase,
+      pending_reason: task.pending_reason,
+      error: task.error,
+    }));
+  const diagnostic = {
+    mode: "self_diagnostic",
+    allowed_test_commands_count: config.allowedTestCommands.length,
+    allowed_test_commands: [...config.allowedTestCommands],
+    configured_agents: Object.keys(config.agents),
+    recent_tasks_returned: recent.tasks.length,
+    recent_failures: failures,
+  };
+  const safe = redactSensitiveValue(diagnostic);
+  return {
+    ...safe.value,
+    redacted: safe.redacted,
+    redaction_categories: safe.redaction_categories,
+  };
+}
+
+function readWatcherSupervisorStatus(): Record<string, unknown> {
+  const runtimeRoot = process.platform === "win32" && process.env.LOCALAPPDATA
+    ? join(process.env.LOCALAPPDATA, "patchwarden", "runtime")
+    : join(homedir(), ".patchwarden", "runtime");
+  const path = join(runtimeRoot, "watcher-status.json");
+  if (!existsSync(path)) return { observed: false, managed: false };
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8").replace(/^\uFEFF/, ""));
+    return {
+      observed: true,
+      managed: Boolean(raw.managed),
+      status: safeText(raw.status, 40) || "unknown",
+      pid: Number.isInteger(Number(raw.pid)) ? Number(raw.pid) : null,
+      instance_id: safeText(raw.instance_id, 100) || null,
+      restart_attempts: Number.isInteger(Number(raw.restart_attempts)) ? Number(raw.restart_attempts) : 0,
+      last_error: safeText(raw.last_error, 500) || null,
+      checked_at: safeText(raw.checked_at, 80) || null,
+    };
+  } catch {
+    return { observed: true, managed: false, status: "invalid_status_file" };
+  }
+}
+
+function directoryStatus(path: string, allowCreatable: boolean, createRoot?: string) {
+  if (!existsSync(path)) {
+    if (allowCreatable) {
+      const parent = createRoot || dirname(path);
+      try {
+        accessSync(parent, constants.R_OK | constants.W_OK);
+        return { available: true, path, readable: false, writable: true, reason: "Directory will be created on first use." };
+      } catch {}
+    }
+    return { available: false, path, readable: false, writable: false, reason: "Directory does not exist." };
+  }
+  let readable = false;
+  let writable = false;
+  try { accessSync(path, constants.R_OK); readable = true; } catch {}
+  try { accessSync(path, constants.W_OK); writable = true; } catch {}
+  return {
+    available: readable && writable,
+    path,
+    readable,
+    writable,
+    reason: readable && writable ? null : "Directory is not readable and writable by the current process.",
+  };
+}
+
+function readTunnelStatus(): Record<string, unknown> & { last_error: string | null } {
+  const runtimeRoot = process.platform === "win32" && process.env.LOCALAPPDATA
+    ? join(process.env.LOCALAPPDATA, "patchwarden", "runtime")
+    : join(homedir(), ".patchwarden", "runtime");
+  const statusFile = join(runtimeRoot, "tunnel-status.json");
+  if (!existsSync(statusFile)) {
+    return { observed: false, status: "not_observed", last_error: null };
+  }
+  try {
+    const text = readFileSync(statusFile, "utf-8");
+    const raw = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    const allowed = {
+      observed: true,
+      status: safeText(raw.status, 40) || "unknown",
+      reason_code: safeText(raw.reason_code, 80) || null,
+      ready: Boolean(raw.ready),
+      attempt: Number.isFinite(Number(raw.attempt)) ? Number(raw.attempt) : null,
+      pid: Number.isInteger(Number(raw.pid)) ? Number(raw.pid) : null,
+      checked_at: safeText(raw.checked_at, 80) || null,
+      next_retry_at: safeText(raw.next_retry_at, 80) || null,
+      last_error: safeText(raw.last_error, 500) || null,
+      server_version: safeText(raw.server_version, 40) || null,
+      schema_epoch: safeText(raw.schema_epoch, 80) || null,
+      tool_profile: safeText(raw.tool_profile, 40) || null,
+      tool_count: Number.isInteger(Number(raw.tool_count)) ? Number(raw.tool_count) : null,
+      tool_names: Array.isArray(raw.tool_names)
+        ? raw.tool_names.filter((name: unknown) => typeof name === "string").slice(0, 100)
+        : [],
+      tool_manifest_sha256: safeText(raw.tool_manifest_sha256, 80) || null,
+      core_tools_ready: Boolean(raw.core_tools_ready),
+    };
+    const redacted = redactSensitiveContent(JSON.stringify(allowed));
+    return JSON.parse(redacted.content);
+  } catch {
+    return { observed: true, status: "invalid_status_file", last_error: "Tunnel status file is unreadable." };
+  }
+}
+
+function safeText(value: unknown, maxLength: number): string {
+  return typeof value === "string" ? value.replace(/[\r\n]+/g, " ").slice(0, maxLength) : "";
+}

package/src/tools/killTask.ts

@@ -0,0 +1,5 @@
+import { requestTaskTermination } from "./cancelTask.js";
+
+export function killTask(taskId: string) {
+  return requestTaskTermination(taskId, true);
+}

package/src/tools/listAgents.ts

@@ -0,0 +1,54 @@
+import { existsSync, statSync } from "node:fs";
+import { basename, delimiter, extname, isAbsolute, join } from "node:path";
+import { getConfig } from "../config.js";
+
+export interface AgentAvailability {
+  name: string;
+  configured: true;
+  available: boolean;
+  command: string;
+  reason: string | null;
+  checked_at: string;
+}
+
+export function listAgents(): { agents: AgentAvailability[]; total: number } {
+  const config = getConfig();
+  const checkedAt = new Date().toISOString();
+  const agents = Object.entries(config.agents)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, agent]) => {
+      const available = commandExists(agent.command);
+      return {
+        name,
+        configured: true as const,
+        available,
+        command: basename(agent.command),
+        reason: available ? null : "Configured executable was not found on disk or PATH.",
+        checked_at: checkedAt,
+      };
+    });
+  return { agents, total: agents.length };
+}
+
+function commandExists(command: string): boolean {
+  if (isAbsolute(command) || command.includes("/") || command.includes("\\")) {
+    return isFile(command);
+  }
+
+  const pathEntries = (process.env.PATH || "").split(delimiter).filter(Boolean);
+  const extensions = process.platform === "win32"
+    ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+  const candidates = extname(command)
+    ? pathEntries.map((entry) => join(entry, command))
+    : pathEntries.flatMap((entry) => extensions.map((extension) => join(entry, `${command}${extension}`)));
+  return candidates.some(isFile);
+}
+
+function isFile(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}