patchwarden 1.5.0 → 1.5.1

package/src/control/middleware/auth.ts

@@ -0,0 +1,17 @@
+/**
+ * Control Center auth middleware — control token validation.
+ *
+ * POST routes are gated behind an in-memory control token generated at boot.
+ * The token is exposed read-only via GET /control-token.json (handled by the
+ * server router) so the local dashboard can read it, but every mutating
+ * action must pass through `checkControlToken` first.
+ */
+import { type IncomingMessage } from "node:http";
+import { controlToken } from "../shared.js";
+
+export function checkControlToken(req: IncomingMessage): boolean {
+  const header = req.headers["x-patchwarden-control-token"];
+  const provided = Array.isArray(header) ? header[0] : header;
+  if (typeof provided !== "string" || provided.length === 0) return false;
+  return provided === controlToken;
+}

package/src/control/middleware/static.ts

@@ -0,0 +1,71 @@
+/**
+ * Control Center static file middleware.
+ *
+ * Serves the bundled `ui/` directory (dashboard pages, partials, vendor
+ * assets, css) with path-traversal protection, plus the inline SVG favicon.
+ * Content types are mapped from `CONTENT_TYPES` in shared.ts.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve } from "node:path";
+import { type ServerResponse } from "node:http";
+import {
+  CONTENT_TYPES,
+  CONTROL_CENTER_FAVICON,
+  errorMessage,
+  sendJson,
+  uiRoot,
+} from "../shared.js";
+
+export function serveStatic(res: ServerResponse, urlPath: string): void {
+  let candidate = "";
+  try {
+    const normalized = urlPath.startsWith("/") ? urlPath.slice(1) : urlPath;
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(normalized);
+    } catch {
+      sendJson(res, 400, { error: "Invalid path encoding" });
+      return;
+    }
+    if (decoded.includes("\0")) {
+      sendJson(res, 400, { error: "Invalid path" });
+      return;
+    }
+    const segments = decoded.split("/").filter(Boolean);
+    if (segments.some((s) => s === "..")) {
+      sendJson(res, 403, { error: "Forbidden" });
+      return;
+    }
+    candidate = resolve(uiRoot, ...segments);
+    const rel = relative(uiRoot, candidate);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+      sendJson(res, 403, { error: "Forbidden" });
+      return;
+    }
+  } catch (err) {
+    sendJson(res, 500, { error: errorMessage(err) });
+    return;
+  }
+  try {
+    if (!existsSync(candidate) || !statSync(candidate).isFile()) {
+      sendJson(res, 404, { error: "Not found" });
+      return;
+    }
+    const ext = extname(candidate).toLowerCase();
+    const contentType = CONTENT_TYPES[ext] || "application/octet-stream";
+    const content = readFileSync(candidate);
+    res.writeHead(200, { "Content-Type": contentType });
+    res.end(content);
+  } catch (err) {
+    sendJson(res, 500, { error: errorMessage(err) });
+  }
+}
+
+export function serveFavicon(res: ServerResponse): void {
+  res.writeHead(200, {
+    "Content-Type": "image/svg+xml; charset=utf-8",
+    "Cache-Control": "public, max-age=86400",
+    "X-Content-Type-Options": "nosniff",
+  });
+  res.end(CONTROL_CENTER_FAVICON);
+}

package/src/control/routes/audit.ts

@@ -0,0 +1,321 @@
+/**
+ * Control Center routes — audit aggregation, warnings, and log tails.
+ *
+ * `handleAudit` joins independent-review.md + audit.json across tasks and
+ * direct sessions. `handleWarnings` buckets audit/stale/verification warnings
+ * by type. `handleLogs` returns redacted stdout/stderr tails for core, direct,
+ * watcher, and control-center log categories.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { type ServerResponse } from "node:http";
+import { type TaskEntry, listTasks } from "../../tools/listTasks.js";
+import { type WatcherStatusSnapshot } from "../../watcherStatus.js";
+import { redactSensitiveContent } from "../../security/contentRedaction.js";
+import { getDirectSessionsDir, getTasksDir } from "../../config.js";
+import {
+  classifyStaleTask,
+  fileMtimeIso,
+  parseReviewVerdict,
+  readWatcherStatusSafe,
+} from "../runtime.js";
+import {
+  config,
+  errorMessage,
+  findLatestLog,
+  getControlCenterLogDir,
+  getRuntimeRoot,
+  readFileTail,
+  readJsonFileSafe,
+  readTextFileSafe,
+  sendJson,
+} from "../shared.js";
+
+export type LogCategory = "core" | "direct" | "watcher" | "control-center";
+
+export function handleLogs(res: ServerResponse, category: LogCategory, tailLines: number): void {
+  try {
+    let dir: string;
+    let stdoutPath: string;
+    let stderrPath: string;
+    let stdoutExists: boolean;
+    let stderrExists: boolean;
+
+    if (category === "control-center") {
+      dir = getControlCenterLogDir();
+      stdoutPath = join(dir, "control-center.stdout.log");
+      stderrPath = join(dir, "control-center.stderr.log");
+      stdoutExists = existsSync(stdoutPath);
+      stderrExists = existsSync(stderrPath);
+    } else if (category === "watcher") {
+      dir = getRuntimeRoot(false);
+      const sp = findLatestLog(dir, /^watcher-.*\.stdout\.log$/);
+      const ep = findLatestLog(dir, /^watcher-.*\.stderr\.log$/);
+      stdoutPath = sp ?? "";
+      stderrPath = ep ?? "";
+      stdoutExists = sp !== null;
+      stderrExists = ep !== null;
+    } else {
+      // core | direct -> tunnel client logs in the matching runtime dir
+      dir = getRuntimeRoot(category === "direct");
+      stdoutPath = join(dir, "tunnel-client.stdout.log");
+      stderrPath = join(dir, "tunnel-client.stderr.log");
+      stdoutExists = existsSync(stdoutPath);
+      stderrExists = existsSync(stderrPath);
+    }
+
+    if (!stdoutExists && !stderrExists) {
+      sendJson(res, 200, {
+        stdout: "",
+        stderr: "",
+        category,
+        tail: tailLines,
+        reason: "log file not found",
+      });
+      return;
+    }
+
+    const stdoutRaw = stdoutExists ? readFileTail(stdoutPath, tailLines) : "";
+    const stderrRaw = stderrExists ? readFileTail(stderrPath, tailLines) : "";
+    const stdout = redactSensitiveContent(stdoutRaw).content;
+    const stderr = redactSensitiveContent(stderrRaw).content;
+    sendJson(res, 200, { stdout, stderr, category, tail: tailLines, reason: null });
+  } catch (err) {
+    sendJson(res, 200, { stdout: "", stderr: "", category, tail: tailLines, reason: errorMessage(err) });
+  }
+}
+
+export function handleAudit(res: ServerResponse): void {
+  try {
+    const audits: Array<Record<string, unknown>> = [];
+
+    // 1. tasks/*/independent-review.md (written by audit_task — the primary audit artifact)
+    // 2. tasks/*/audit.json (legacy/explicit JSON audit, if present)
+    const tasksDir = getTasksDir(config);
+    if (existsSync(tasksDir)) {
+      let taskEntries: import("node:fs").Dirent[] = [];
+      try {
+        taskEntries = readdirSync(tasksDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+      } catch {
+        taskEntries = [];
+      }
+      for (const entry of taskEntries) {
+        const taskDir = join(tasksDir, entry.name);
+
+        // independent-review.md
+        const reviewFile = join(taskDir, "independent-review.md");
+        if (existsSync(reviewFile)) {
+          const content = readTextFileSafe(reviewFile) ?? "";
+          audits.push({
+            task_id: entry.name,
+            source: "independent-review.md",
+            verdict: parseReviewVerdict(content),
+            checked_at: fileMtimeIso(reviewFile),
+            content_excerpt: content.slice(0, 500),
+          });
+        }
+
+        // audit.json (explicit JSON audit if present)
+        const auditFile = join(taskDir, "audit.json");
+        if (existsSync(auditFile)) {
+          const data = readJsonFileSafe<Record<string, unknown>>(auditFile);
+          if (data) {
+            audits.push({
+              task_id: entry.name,
+              source: "audit.json",
+              checked_at: data.checked_at ?? fileMtimeIso(auditFile),
+              ...data,
+            });
+          }
+        }
+      }
+    }
+
+    // 3. direct-sessions/*/audit.json (written by Direct audit_session)
+    const sessionsDir = getDirectSessionsDir(config);
+    if (existsSync(sessionsDir)) {
+      let sessionEntries: import("node:fs").Dirent[] = [];
+      try {
+        sessionEntries = readdirSync(sessionsDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+      } catch {
+        sessionEntries = [];
+      }
+      for (const entry of sessionEntries) {
+        const auditFile = join(sessionsDir, entry.name, "audit.json");
+        if (!existsSync(auditFile)) continue;
+        const data = readJsonFileSafe<Record<string, unknown>>(auditFile);
+        if (data) {
+          audits.push({
+            source: "direct-session",
+            session_id: data.session_id ?? entry.name,
+            checked_at: fileMtimeIso(auditFile),
+            ...data,
+          });
+        }
+      }
+    }
+
+    // Sort by checked_at descending (missing timestamps sort last).
+    audits.sort((a, b) => {
+      const ac = String(a.checked_at ?? "");
+      const bc = String(b.checked_at ?? "");
+      return bc.localeCompare(ac);
+    });
+    const limited = audits.slice(0, 50);
+    sendJson(res, 200, { audits: limited, total: limited.length });
+  } catch (err) {
+    sendJson(res, 200, { audits: [], reason: errorMessage(err) });
+  }
+}
+
+// ── Warnings aggregation ─────────────────────────────────────────
+
+interface WarningEntry {
+  type: string;
+  severity: "error" | "warning" | "info";
+  affected_tasks_count: number;
+  affected_tasks: string[];
+  likely_false_positive: boolean;
+  needs_fix: boolean;
+  blocked: boolean;
+  recommended_action: string;
+}
+
+/**
+ * Aggregate warnings from multiple sources:
+ *  - audit.json warnings/fail_checks/possible_false_positives/manual_verification_required
+ *  - stale task classification (heartbeat stale, collecting_artifacts stale, etc.)
+ *  - task status=failed_verification
+ *
+ * Each warning type is grouped into a bucket with affected task IDs. The
+ * handler is fault-tolerant: any per-task read failure is skipped, and a
+ * top-level failure returns an empty warnings array (never 500).
+ */
+export function handleWarnings(res: ServerResponse): void {
+  try {
+    const buckets: Record<string, Set<string>> = {
+      unrecorded_command_execution: new Set(),
+      artifact_hygiene: new Set(),
+      scope_changes: new Set(),
+      release_publish_claim: new Set(),
+      manual_verification_required: new Set(),
+      stale_task: new Set(),
+      failed_verification: new Set(),
+    };
+
+    const tasksDir = getTasksDir(config);
+    let taskList: TaskEntry[] = [];
+    let watcher: WatcherStatusSnapshot;
+    try {
+      const result = listTasks({ limit: 100 });
+      taskList = result.tasks;
+      watcher = result.watcher;
+    } catch (err) {
+      watcher = readWatcherStatusSafe();
+    }
+
+    const now = Date.now();
+
+    for (const task of taskList) {
+      const taskId = task.task_id;
+
+      // 1. Read audit.json for warning strings
+      const auditFile = join(tasksDir, taskId, "audit.json");
+      const audit = readJsonFileSafe<Record<string, unknown>>(auditFile);
+      if (audit) {
+        const warningTexts: string[] = [];
+        const collectStrings = (field: unknown) => {
+          if (Array.isArray(field)) {
+            for (const w of field) {
+              if (typeof w === "string") {
+                warningTexts.push(w);
+              } else if (w && typeof w === "object") {
+                const obj = w as Record<string, unknown>;
+                if (typeof obj.message === "string") warningTexts.push(obj.message);
+                else if (typeof obj.description === "string") warningTexts.push(obj.description);
+                else if (typeof obj.warning === "string") warningTexts.push(obj.warning);
+                else warningTexts.push(JSON.stringify(obj));
+              }
+            }
+          } else if (typeof field === "string") {
+            warningTexts.push(field);
+          }
+        };
+        collectStrings(audit.warnings);
+        collectStrings(audit.fail_checks);
+        collectStrings(audit.possible_false_positives);
+
+        for (const text of warningTexts) {
+          const lower = text.toLowerCase();
+          if (lower.includes("unrecorded") || lower.includes("command execution")) {
+            buckets.unrecorded_command_execution.add(taskId);
+          }
+          if (lower.includes("artifact") || lower.includes("hygiene")) {
+            buckets.artifact_hygiene.add(taskId);
+          }
+          if (lower.includes("scope") || lower.includes("out_of_scope")) {
+            buckets.scope_changes.add(taskId);
+          }
+          if (lower.includes("release") || lower.includes("publish")) {
+            buckets.release_publish_claim.add(taskId);
+          }
+        }
+
+        // manual_verification_required flag
+        if (audit.manual_verification_required === true) {
+          buckets.manual_verification_required.add(taskId);
+        }
+      }
+
+      // 2. Stale tasks
+      try {
+        const cls = classifyStaleTask(task, watcher, now);
+        if (cls.is_stale) {
+          buckets.stale_task.add(taskId);
+        }
+      } catch {
+        // skip stale classification failure
+      }
+
+      // 3. Failed verification
+      if (task.status === "failed_verification") {
+        buckets.failed_verification.add(taskId);
+      }
+    }
+
+    const warnings: WarningEntry[] = [];
+    const addWarning = (
+      type: string,
+      severity: "error" | "warning" | "info",
+      likelyFalsePositive: boolean,
+      needsFix: boolean,
+      blocked: boolean,
+      recommendedAction: string
+    ) => {
+      const tasks = buckets[type];
+      if (tasks.size === 0) return;
+      warnings.push({
+        type,
+        severity,
+        affected_tasks_count: tasks.size,
+        affected_tasks: Array.from(tasks),
+        likely_false_positive: likelyFalsePositive,
+        needs_fix: needsFix,
+        blocked,
+        recommended_action: recommendedAction,
+      });
+    };
+
+    addWarning("failed_verification", "error", false, true, false, "Re-run verification or fix the failing checks before retrying.");
+    addWarning("stale_task", "warning", false, false, false, "Reconcile or recreate stale tasks.");
+    addWarning("manual_verification_required", "warning", false, false, false, "Review the audit findings and manually verify the changes.");
+    addWarning("unrecorded_command_execution", "info", false, true, false, "Investigate unrecorded command executions; ensure watcher captures all commands.");
+    addWarning("release_publish_claim", "info", false, false, true, "Verify the release/publish claim against actual release artifacts before proceeding.");
+    addWarning("artifact_hygiene", "info", true, false, false, "Review artifact hygiene warnings; many are likely false positives.");
+    addWarning("scope_changes", "info", true, false, false, "Review scope changes; verify they are intentional before accepting.");
+
+    sendJson(res, 200, { warnings, total: warnings.length });
+  } catch (err) {
+    sendJson(res, 200, { warnings: [], total: 0, error: errorMessage(err) });
+  }
+}

package/src/control/routes/evidence.ts

@@ -0,0 +1,107 @@
+/**
+ * Control Center routes — evidence packs (/api/evidence-packs/*).
+ *
+ * Lists exported evidence packs (bounded to 50), reads a single pack detail,
+ * and exports a pack for a lineage on demand. The export endpoint is a POST
+ * route gated by the control token in the server router.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { type ServerResponse } from "node:http";
+import {
+  exportTaskEvidencePack,
+  listEvidencePacks,
+  readEvidencePack,
+  type SafeEvidencePack,
+} from "../../tools/evidencePack.js";
+import { errorMessage, sendJson, config } from "../shared.js";
+
+function augmentEvidencePackSummary(pack: SafeEvidencePack): SafeEvidencePack & {
+  export_status: "exported" | "pending";
+  evidence_json_exists: boolean;
+  evidence_md_exists: boolean;
+  exported_at: string;
+} {
+  const jsonExists = existsSync(pack.files.json);
+  const mdExists = existsSync(pack.files.markdown);
+  return {
+    ...pack,
+    export_status: jsonExists ? "exported" : "pending",
+    evidence_json_exists: jsonExists,
+    evidence_md_exists: mdExists,
+    exported_at: pack.generated_at,
+  };
+}
+
+export function handleEvidencePacks(res: ServerResponse): void {
+  try {
+    const list = listEvidencePacks({ max_items: 50 });
+    const packs = list.evidence_packs.map((pack) => augmentEvidencePackSummary(pack));
+    // Detect lineages that exist but have no exported evidence pack yet, so the
+    // dashboard can show an "Export evidence pack" action for the most recent one.
+    const lineagesRoot = join(config.workspaceRoot, ".patchwarden", "lineages");
+    let lineageCount = 0;
+    const exportedIds = new Set(packs.map((p) => p.lineage_id));
+    const pendingLineageIds: string[] = [];
+    if (existsSync(lineagesRoot)) {
+      const dirs = readdirSync(lineagesRoot, { withFileTypes: true }).filter((e) => e.isDirectory());
+      lineageCount = dirs.length;
+      for (const dir of dirs) {
+        if (!exportedIds.has(dir.name)) pendingLineageIds.push(dir.name);
+      }
+    }
+    sendJson(res, 200, {
+      evidence_packs: packs,
+      total: packs.length,
+      truncated: list.truncated,
+      has_lineages: lineageCount > 0,
+      lineage_count: lineageCount,
+      pending_lineage_ids: pendingLineageIds.slice(0, 20),
+      reason: null,
+    });
+  } catch (err) {
+    sendJson(res, 200, { evidence_packs: [], total: 0, reason: errorMessage(err) });
+  }
+}
+
+export function handleEvidencePackDetail(res: ServerResponse, lineageId: string): void {
+  try {
+    if (!/^[A-Za-z0-9_-]+$/.test(lineageId)) {
+      sendJson(res, 400, { error: "Invalid lineage id" });
+      return;
+    }
+    const pack = readEvidencePack(lineageId);
+    if (!pack) {
+      sendJson(res, 404, { error: "Evidence pack not found" });
+      return;
+    }
+    sendJson(res, 200, augmentEvidencePackSummary(pack));
+  } catch (err) {
+    sendJson(res, 200, { lineage_id: lineageId, error: errorMessage(err), bounded: true });
+  }
+}
+
+export function handleEvidencePackExport(res: ServerResponse, lineageId: string): void {
+  try {
+    if (!/^[A-Za-z0-9_-]+$/.test(lineageId)) {
+      sendJson(res, 400, { error: "Invalid lineage id" });
+      return;
+    }
+    // Check lineage exists.
+    const lineageFile = join(config.workspaceRoot, ".patchwarden", "lineages", lineageId, "lineage.json");
+    if (!existsSync(lineageFile)) {
+      sendJson(res, 404, { error: "Lineage not found" });
+      return;
+    }
+    // Check if already exported.
+    const evidenceJsonPath = join(config.workspaceRoot, ".patchwarden", "evidence-packs", lineageId, "evidence.json");
+    if (existsSync(evidenceJsonPath)) {
+      sendJson(res, 200, { ok: true, already_exported: true, lineage_id: lineageId });
+      return;
+    }
+    const pack = exportTaskEvidencePack({ lineage_id: lineageId });
+    sendJson(res, 200, { ok: true, exported: true, lineage_id: lineageId, evidence_pack_id: pack.evidence_pack_id });
+  } catch (err) {
+    sendJson(res, 200, { ok: false, lineage_id: lineageId, error: errorMessage(err) });
+  }
+}

package/src/control/routes/lineage.ts

@@ -0,0 +1,92 @@
+/**
+ * Control Center routes — task lineage (/api/lineages/*).
+ *
+ * Lists all lineages under .patchwarden/lineages (bounded to 50, most recently
+ * updated first) and serves a single lineage detail. Each record is projected
+ * through `toSafeTaskLineage` so full artifact content is bounded.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { type ServerResponse } from "node:http";
+import { toSafeTaskLineage, type SafeTaskLineage, type TaskLineageRecord } from "../../tools/taskLineage.js";
+import { config, errorMessage, readJsonFileSafeUnder, sendJson } from "../shared.js";
+
+interface LineageSummary {
+  iterations: number;
+  main_task_count: number;
+  fix_task_count: number;
+  cleanup_task_count: number;
+  direct_verification: {
+    session_id: string;
+    status: string;
+    audit_decision: string;
+    command_count: number;
+    passed_commands: number;
+    failed_commands: number;
+  } | null;
+  warnings_count: number;
+}
+
+function augmentLineageSummary(safe: SafeTaskLineage, record: TaskLineageRecord): SafeTaskLineage & LineageSummary {
+  const directSessions = safe.tasks.direct_sessions;
+  const firstDirect = directSessions.length > 0 ? directSessions[0] : null;
+  const directVerification = firstDirect
+    ? {
+        session_id: firstDirect.session_id,
+        status: firstDirect.status || "unknown",
+        audit_decision: firstDirect.audit_decision || "not_run",
+        command_count: firstDirect.command_count ?? 0,
+        passed_commands: firstDirect.passed_commands ?? 0,
+        failed_commands: firstDirect.failed_commands ?? 0,
+      }
+    : null;
+  return {
+    ...safe,
+    iterations: record.rounds.length,
+    main_task_count: record.main_task ? 1 : 0,
+    fix_task_count: record.fix_tasks.length,
+    cleanup_task_count: record.cleanup_tasks.length,
+    direct_verification: directVerification,
+    warnings_count: record.warnings.length,
+  };
+}
+
+export function handleLineages(res: ServerResponse): void {
+  try {
+    const root = join(config.workspaceRoot, ".patchwarden", "lineages");
+    if (!existsSync(root)) {
+      sendJson(res, 200, { lineages: [], total: 0, reason: null });
+      return;
+    }
+    const lineages = readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => readJsonFileSafeUnder<TaskLineageRecord>(root, join(entry.name, "lineage.json")))
+      .filter((entry): entry is TaskLineageRecord => entry !== null)
+      .map((entry) => augmentLineageSummary(toSafeTaskLineage(entry, 6), entry))
+      .sort((a, b) => b.updated_at.localeCompare(a.updated_at))
+      .slice(0, 50);
+    sendJson(res, 200, { lineages, total: lineages.length, reason: null });
+  } catch (err) {
+    sendJson(res, 200, { lineages: [], total: 0, reason: errorMessage(err) });
+  }
+}
+
+export function handleLineageDetail(res: ServerResponse, lineageId: string): void {
+  try {
+    if (!/^[A-Za-z0-9_-]+$/.test(lineageId)) {
+      sendJson(res, 400, { error: "Invalid lineage id" });
+      return;
+    }
+    const data = readJsonFileSafeUnder<TaskLineageRecord>(
+      join(config.workspaceRoot, ".patchwarden", "lineages"),
+      join(lineageId, "lineage.json")
+    );
+    if (!data) {
+      sendJson(res, 404, { error: "Lineage not found" });
+      return;
+    }
+    sendJson(res, 200, augmentLineageSummary(toSafeTaskLineage(data, 20), data));
+  } catch (err) {
+    sendJson(res, 200, { lineage_id: lineageId, error: errorMessage(err) });
+  }
+}

package/src/control/routes/policy.ts

@@ -0,0 +1,81 @@
+/**
+ * Control Center routes — project policy + release status.
+ *
+ * Read-only wrappers around `getProjectPolicySummary` that surface release
+ * readiness, blocked commands, and version consistency for the dashboard's
+ * release panel. Never performs remote writes (`remote_write_performed` is
+ * always false).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { type ServerResponse } from "node:http";
+import { getProjectPolicySummary } from "../../policy/projectPolicy.js";
+import { errorMessage, sendJson } from "../shared.js";
+
+export function handleProjectPolicy(res: ServerResponse, repoPath: string): void {
+  try {
+    sendJson(res, 200, getProjectPolicySummary(repoPath || "."));
+  } catch (err) {
+    sendJson(res, 200, {
+      repo_path: repoPath || ".",
+      valid: false,
+      issues: [{ code: "policy_unavailable", severity: "error", field: "repo_path", message: errorMessage(err) }],
+    });
+  }
+}
+
+export function handleReleaseStatus(res: ServerResponse, repoPath: string): void {
+  try {
+    const policy = getProjectPolicySummary(repoPath || ".");
+    const readiness = policy.release_readiness;
+    const requiredCommands = readiness.required_commands.map((c) => ({
+      command: c.command,
+      allowed: c.allowed,
+      blocked_reason: c.allowed ? null : (c.reason || "not_allowed"),
+    }));
+    const commandsBlockedCount = requiredCommands.filter((c) => !c.allowed).length;
+    const hasPackageJson = existsSync(join(policy.resolved_repo_path, "package.json"));
+    const versionSource = hasPackageJson
+      ? "package.json"
+      : (repoPath || ".") === "."
+        ? "workspace_root"
+        : "unknown";
+
+    let readyState: string;
+    if (!policy.valid || commandsBlockedCount > 0) {
+      readyState = "blocked";
+    } else if (readiness.version === null) {
+      readyState = "unknown";
+    } else if (readiness.version_consistent === true) {
+      readyState = "ready";
+    } else {
+      readyState = "blocked";
+    }
+
+    sendJson(res, 200, {
+      repo_path: repoPath || ".",
+      resolved_repo_path: policy.resolved_repo_path,
+      policy_valid: policy.valid,
+      policy_issue_count: policy.issues.length,
+      policy_issues: policy.issues.slice(0, 10),
+      release_readiness: readiness,
+      package_name: readiness.package_name,
+      version_source: versionSource,
+      version_consistent: readiness.version_consistent,
+      required_commands: requiredCommands,
+      commands_blocked_count: commandsBlockedCount,
+      ready_state: readyState,
+      next_action: policy.valid && readiness.version_consistent !== false
+        ? "Run release_check via create_task template, or run_task_loop with template=release_check."
+        : "Fix project-policy or version consistency issues before release preparation.",
+      remote_write_performed: false,
+    });
+  } catch (err) {
+    sendJson(res, 200, {
+      repo_path: repoPath || ".",
+      policy_valid: false,
+      error: errorMessage(err),
+      remote_write_performed: false,
+    });
+  }
+}