patchwarden 1.5.0 → 1.6.1

package/src/httpServer.ts

@@ -16,52 +16,68 @@
  */
 
 import { createServer, IncomingMessage, ServerResponse } from "node:http";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { loadConfig, getTasksDir } from "./config.js";
 import { registerTools } from "./tools/registry.js";
-import { healthCheck } from "./tools/healthCheck.js";
+import { healthCheck } from "./tools/diagnostics/healthCheck.js";
 import { getToolCatalogSnapshot } from "./tools/registry.js";
 import { PATCHWARDEN_VERSION } from "./version.js";
+import { logger } from "./logging.js";
+import { firstHeaderValue, timingSafeStringEqual } from "./security/secretComparison.js";
+import { redactSensitiveContent } from "./security/contentRedaction.js";
+import { atomicWriteJsonFileSync } from "./utils/atomicFile.js";
+import { mutateTaskStatus } from "./runner/taskStatusStore.js";
+import { isTrustedLoopbackHostHeader } from "./security/loopbackHost.js";
 
 // ── Bootstrap ─────────────────────────────────────────────────────
 
 const config = loadConfig();
 const port = parseInt(process.env.PATCHWARDEN_HTTP_PORT || "") ||
-  (config as any).httpPort ||
+  config.httpPort ||
   7331;
 const host = "127.0.0.1";
 
-console.error(`[patchwarden-http] Workspace: ${config.workspaceRoot}`);
-console.error(`[patchwarden-http] Listening:  http://${host}:${port}/mcp`);
-console.error(`[patchwarden-http] ⚠️  Bound to 127.0.0.1 only — not exposed to network`);
+logger.info(`[patchwarden-http] Workspace: ${config.workspaceRoot}`);
+logger.info(`[patchwarden-http] Listening:  http://${host}:${port}/mcp`);
+logger.info(`[patchwarden-http] ⚠️  Bound to 127.0.0.1 only — not exposed to network`);
 
 // ── Owner token (optional) ────────────────────────────────────────
 
-const httpCfg = (config as any).http || {};
+const httpCfg = config.http || {};
 const ownerTokenEnv = httpCfg.ownerTokenEnv || "PATCHWARDEN_OWNER_TOKEN";
 const ownerToken = process.env[ownerTokenEnv] || "";
+const MAX_ADMIN_BODY_BYTES = 64 * 1024;
+const MAX_ACCEPTANCE_NOTES_CHARS = 10_000;
+const REVIEWABLE_TASK_STATUSES = new Set([
+  "done_by_agent",
+  "done",
+  "accepted",
+  "rejected",
+  "needs_fix",
+  "blocked",
+]);
 
 if (ownerToken) {
-  console.error(`[patchwarden-http] 🔒 Owner token required (env: ${ownerTokenEnv})`);
+  logger.info(`[patchwarden-http] 🔒 Owner token required (env: ${ownerTokenEnv})`);
 } else {
-  console.error(`[patchwarden-http] ⚠️  No owner token set — all local requests accepted`);
+  logger.info(`[patchwarden-http] ⚠️  No owner token set — all local requests accepted`);
 }
 
 function checkOwnerToken(req: IncomingMessage): boolean {
   if (!ownerToken) return true; // no token configured — allow all
 
-  const authHeader = req.headers["authorization"] || "";
-  const customHeader = req.headers["x-patchwarden-token"] || "";
+  const authHeader = firstHeaderValue(req.headers["authorization"]);
+  const customHeader = firstHeaderValue(req.headers["x-patchwarden-token"]);
 
   if (authHeader.startsWith("Bearer ")) {
-    return authHeader.slice(7) === ownerToken;
+    return timingSafeStringEqual(authHeader.slice(7), ownerToken);
   }
 
-  if (typeof customHeader === "string" && customHeader.length > 0) {
-    return customHeader === ownerToken;
+  if (customHeader.length > 0) {
+    return timingSafeStringEqual(customHeader, ownerToken);
   }
 
   return false;
@@ -81,11 +97,22 @@ function handleAcceptance(taskId: string, status: "accepted" | "rejected", body:
     throw Object.assign(new Error(`Task "${taskId}" not found.`), { statusCode: 404 });
   }
   let notes = "";
-  try {
-    const parsed = JSON.parse(body || "{}");
-    notes = String(parsed.notes || parsed.reason || "");
-  } catch {
-    // no body or invalid JSON — notes stays empty
+  if (body.trim()) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      throw httpError(400, "Acceptance body must be valid JSON.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw httpError(400, "Acceptance body must be a JSON object.");
+    }
+    const record = parsed as Record<string, unknown>;
+    const rawNotes = record.notes ?? record.reason ?? "";
+    if (typeof rawNotes !== "string") {
+      throw httpError(400, "Acceptance notes or reason must be a string.");
+    }
+    notes = redactSensitiveContent(rawNotes).content.slice(0, MAX_ACCEPTANCE_NOTES_CHARS);
   }
   const acceptance = {
     status,
@@ -93,23 +120,69 @@ function handleAcceptance(taskId: string, status: "accepted" | "rejected", body:
     reviewer: "human",
     notes,
   };
-  writeFileSync(filePath, JSON.stringify(acceptance, null, 2), "utf-8");
-
-  // Also update the task's status.json with acceptance_status
+  // Commit the review artifact and status annotation while holding the same
+  // status lock used by the runner, cancel, and audit paths.
   const statusFile = join(taskDir, "status.json");
-  if (existsSync(statusFile)) {
-    try {
-      const current = JSON.parse(readFileSync(statusFile, "utf-8"));
-      current.acceptance_status = status;
-      current.acceptance_reviewed_at = acceptance.reviewed_at;
-      writeFileSync(statusFile, JSON.stringify(current, null, 2), "utf-8");
-    } catch {
-      // status.json update is best-effort
-    }
+  if (!existsSync(statusFile)) {
+    throw httpError(409, `Task "${taskId}" has no status.json to review.`);
   }
+  mutateTaskStatus(statusFile, (current) => {
+    if (!REVIEWABLE_TASK_STATUSES.has(String(current.status || ""))) {
+      throw httpError(409, `Task "${taskId}" is not in a reviewable terminal state.`);
+    }
+    atomicWriteJsonFileSync(filePath, acceptance);
+    const next = {
+      ...current,
+      acceptance_status: status,
+      acceptance_reviewed_at: acceptance.reviewed_at,
+      updated_at: new Date().toISOString(),
+    };
+    return { next, result: next };
+  });
   return acceptance;
 }
 
+function httpError(statusCode: number, message: string): Error & { statusCode: number } {
+  return Object.assign(new Error(message), { statusCode });
+}
+
+function readBoundedRequestBody(req: IncomingMessage, maxBytes: number): Promise<string> {
+  const declaredLength = Number(firstHeaderValue(req.headers["content-length"]));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    req.resume();
+    return Promise.reject(httpError(413, `Request body exceeds ${maxBytes} bytes.`));
+  }
+  return new Promise((resolveBody, rejectBody) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    let settled = false;
+    req.on("data", (chunk: Buffer | string) => {
+      if (settled) return;
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      total += buffer.length;
+      if (total > maxBytes) {
+        settled = true;
+        req.resume();
+        rejectBody(httpError(413, `Request body exceeds ${maxBytes} bytes.`));
+        return;
+      }
+      chunks.push(buffer);
+    });
+    req.on("end", () => {
+      if (!settled) {
+        settled = true;
+        resolveBody(Buffer.concat(chunks).toString("utf-8"));
+      }
+    });
+    req.on("error", (error) => {
+      if (!settled) {
+        settled = true;
+        rejectBody(error);
+      }
+    });
+  });
+}
+
 function readAcceptance(taskId: string): object {
   const filePath = getAcceptancePath(taskId);
   if (!existsSync(filePath)) {
@@ -142,7 +215,9 @@ async function handleMcpRequest(req: IncomingMessage, res: ServerResponse): Prom
     await mcpServer.connect(transport);
     await transport.handleRequest(req, res);
   } catch (err) {
-    console.error("[patchwarden-http] Request error:", err);
+    logger.error("[patchwarden-http] Request error", {
+      error: err instanceof Error ? err.message : String(err),
+    });
     if (!res.headersSent) {
       res.writeHead(500, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ error: "Internal server error" }));
@@ -178,6 +253,16 @@ function parseAdminUrl(url: string) {
 // ── HTTP server ───────────────────────────────────────────────────
 
 const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+  if (!isTrustedLoopbackHostHeader(req.headers.host, port)) {
+    res.writeHead(421, {
+      "Content-Type": "application/json; charset=utf-8",
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+    });
+    res.end(JSON.stringify({ error: "Untrusted Host header" }));
+    return;
+  }
+
   // Health check endpoints
   if (req.method === "GET" && (req.url === "/healthz" || req.url === "/readyz")) {
     const health = healthCheck(getToolCatalogSnapshot());
@@ -203,9 +288,7 @@ const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse
         return;
       }
       if ((admin.action === "accept" || admin.action === "reject") && req.method === "POST") {
-        const chunks: Buffer[] = [];
-        for await (const chunk of req) { chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); }
-        const body = Buffer.concat(chunks).toString("utf-8");
+        const body = await readBoundedRequestBody(req, MAX_ADMIN_BODY_BYTES);
         const acceptance = handleAcceptance(admin.taskId, admin.action === "accept" ? "accepted" : "rejected", body);
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(JSON.stringify(acceptance, null, 2));
@@ -213,10 +296,13 @@ const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse
       }
       res.writeHead(405, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ error: "Method not allowed for this admin endpoint." }));
-    } catch (err: any) {
-      const statusCode = err.statusCode || 500;
+    } catch (err: unknown) {
+      const statusCode = err && typeof err === "object" && "statusCode" in err
+        ? Number((err as { statusCode?: unknown }).statusCode) || 500
+        : 500;
+      const message = err instanceof Error ? err.message : "Internal server error";
       res.writeHead(statusCode, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: err.message || "Internal server error" }));
+      res.end(JSON.stringify({ error: message }));
     }
     return;
   }
@@ -253,22 +339,22 @@ const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse
 
 httpServer.on("error", (err: NodeJS.ErrnoException) => {
   if (err.code === "EADDRINUSE") {
-    console.error(`[patchwarden-http] Fatal: port ${port} is already in use on ${host}.`);
-    console.error("[patchwarden-http] Stop the other PatchWarden HTTP instance or change httpPort in patchwarden.config.json.");
+    logger.fatal(`[patchwarden-http] Fatal: port ${port} is already in use on ${host}.`);
+    logger.fatal("[patchwarden-http] Stop the other PatchWarden HTTP instance or change httpPort in patchwarden.config.json.");
   } else {
-    console.error(`[patchwarden-http] Fatal: ${err.message}`);
+    logger.fatal(`[patchwarden-http] Fatal: ${err.message}`);
   }
   process.exit(1);
 });
 
 httpServer.listen(port, host, () => {
-  console.error(`[patchwarden-http] ✅ Ready`);
-  console.error(`[patchwarden-http] Admin:    http://${host}:${port}/admin/tasks/:id/accept`);
+  logger.info(`[patchwarden-http] ✅ Ready`);
+  logger.info(`[patchwarden-http] Admin:    http://${host}:${port}/admin/tasks/:id/accept`);
 });
 
 // Graceful shutdown
 process.on("SIGINT", () => {
-  console.error("[patchwarden-http] Shutting down...");
+  logger.info("[patchwarden-http] Shutting down...");
   httpServer.close(() => process.exit(0));
 });
 

package/src/index.ts

@@ -12,11 +12,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { loadConfig } from "./config.js";
 import { registerTools } from "./tools/registry.js";
 import { PATCHWARDEN_VERSION } from "./version.js";
+import { logger } from "./logging.js";
 
 const config = loadConfig();
 
-console.error(`[patchwarden] Workspace: ${config.workspaceRoot}`);
-console.error(`[patchwarden] Transport: stdio`);
+logger.info(`[patchwarden] Workspace: ${config.workspaceRoot}`);
+logger.info("[patchwarden] Transport: stdio");
 
 const server = new Server(
   { name: "patchwarden", version: PATCHWARDEN_VERSION },
@@ -27,8 +28,10 @@ registerTools(server);
 
 const transport = new StdioServerTransport();
 server.connect(transport).catch((err) => {
-  console.error("[patchwarden] Fatal:", err);
+  logger.fatal("[patchwarden] Fatal", {
+    error: err instanceof Error ? err.message : String(err),
+  });
   process.exit(1);
 });
 
-console.error("[patchwarden] MCP server ready on stdio");
+logger.info("[patchwarden] MCP server ready on stdio");

package/src/logging.ts

@@ -1,13 +1,16 @@
 import { createHash } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { redactSensitiveContent } from "./security/contentRedaction.js";
-import { stableJsonStringify } from "./tools/toolRegistry.js";
+import { stableJsonStringify } from "./utils/stableJson.js";
 import { getConfig } from "./config.js";
+import { appendBoundedTextFileSync } from "./utils/boundedFile.js";
+
+const MAX_INVOCATION_LOG_BYTES = 5 * 1024 * 1024;
 
 // ── Types ─────────────────────────────────────────────────────────
 
-export type LogLevel = "info" | "warn" | "error" | "audit";
+export type LogLevel = "info" | "warn" | "error" | "fatal" | "audit";
 
 export interface LogEntry {
   timestamp: string;
@@ -90,6 +93,15 @@ export class Logger {
     emit({ timestamp: new Date().toISOString(), level: "error", message, ...context });
   }
 
+  /**
+   * Emit a fatal-level log entry. Use this immediately before a process
+   * exits with a non-zero status, to record the unrecoverable condition.
+   * Level is higher than `error`.
+   */
+  fatal(message: string, context?: Record<string, unknown>): void {
+    emit({ timestamp: new Date().toISOString(), level: "fatal", message, ...context });
+  }
+
   /**
    * Emit a tool-call audit log entry.
    *
@@ -225,7 +237,11 @@ export function logToolInvocation(
 
     mkdirSync(logsDir, { recursive: true });
     const logFilePath = join(logsDir, "invocation.log");
-    appendFileSync(logFilePath, JSON.stringify(entry) + "\n", "utf8");
+    appendBoundedTextFileSync(
+      logFilePath,
+      JSON.stringify(entry) + "\n",
+      MAX_INVOCATION_LOG_BYTES,
+    );
   } catch (err) {
     // 日志失败不应阻断主流程，仅向 stderr 记录错误
     try {

package/src/policy/projectPolicy.ts

@@ -334,10 +334,13 @@ function pathMatchesPattern(relPath: string, pattern: string): boolean {
 }
 
 function parseGithubRepo(repository: unknown): string | null {
+  const repositoryObject = repository && typeof repository === "object" && !Array.isArray(repository)
+    ? repository as Record<string, unknown>
+    : null;
   const raw = typeof repository === "string"
     ? repository
-    : repository && typeof repository === "object" && typeof (repository as any).url === "string"
-      ? (repository as any).url
+    : typeof repositoryObject?.url === "string"
+      ? repositoryObject.url
       : "";
   const match = raw.match(/github\.com[:/](.+?\/.+?)(?:\.git)?(?:[#?].*)?$/i);
   return match ? match[1] : null;

package/src/release/releaseGate.ts

@@ -15,11 +15,13 @@
  * GITHUB_TOKEN is used as Bearer auth but never logged or returned.
  */
 
-import { execSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { get } from "node:https";
+import { resolveTrustedCommandLine } from "../runner/processSecurity.js";
+import { runSimpleProcessSync } from "../runner/simpleProcess.js";
+import { atomicWriteJsonFileSync } from "../utils/atomicFile.js";
 
 // ── Public types ───────────────────────────────────────────────────
 
@@ -49,7 +51,7 @@ export interface PackedCheckResult extends StageCheckResult {
 
 export interface HttpResponse {
   statusCode: number;
-  data: any;
+  data: unknown;
 }
 
 export type HttpGetFn = (
@@ -86,6 +88,7 @@ const STAGE_ORDER: ReleaseStage[] = [
 
 const LOCAL_TIMEOUT_MS = 300000;
 const REMOTE_TIMEOUT_MS = 10000;
+const MAX_REMOTE_RESPONSE_BYTES = 5 * 1024 * 1024;
 const USER_AGENT = "PatchWarden-ReleaseGate";
 
 const PACK_FORBIDDEN_PATTERNS: RegExp[] = [
@@ -121,6 +124,13 @@ export async function httpsGetJson(
 ): Promise<HttpResponse> {
   const timeout = timeoutMs ?? REMOTE_TIMEOUT_MS;
   return new Promise<HttpResponse>((resolve, reject) => {
+    let settled = false;
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    };
     const timer = setTimeout(() => {
       req.destroy(new Error(`Request timed out after ${timeout}ms`));
     }, timeout);
@@ -135,12 +145,32 @@ export async function httpsGetJson(
         },
       },
       (res) => {
+        const declaredLength = Number(res.headers["content-length"]);
+        if (Number.isFinite(declaredLength) && declaredLength > MAX_REMOTE_RESPONSE_BYTES) {
+          res.destroy();
+          fail(new Error(`Response exceeds ${MAX_REMOTE_RESPONSE_BYTES} bytes`));
+          return;
+        }
         const chunks: Buffer[] = [];
-        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        let totalBytes = 0;
+        let oversized = false;
+        res.on("data", (chunk: Buffer) => {
+          if (oversized) return;
+          totalBytes += chunk.length;
+          if (totalBytes > MAX_REMOTE_RESPONSE_BYTES) {
+            oversized = true;
+            res.destroy();
+            fail(new Error(`Response exceeds ${MAX_REMOTE_RESPONSE_BYTES} bytes`));
+            return;
+          }
+          chunks.push(chunk);
+        });
         res.on("end", () => {
+          if (oversized || settled) return;
+          settled = true;
           clearTimeout(timer);
           const body = Buffer.concat(chunks).toString("utf-8");
-          let data: any = null;
+          let data: unknown = null;
           if (body.length > 0) {
             try {
               data = JSON.parse(body);
@@ -150,12 +180,11 @@ export async function httpsGetJson(
           }
           resolve({ statusCode: res.statusCode ?? 0, data });
         });
+        res.on("aborted", () => fail(new Error("Response was aborted before completion")));
+        res.on("error", fail);
       },
     );
-    req.on("error", (err) => {
-      clearTimeout(timer);
-      reject(err);
-    });
+    req.on("error", fail);
   });
 }
 
@@ -203,12 +232,12 @@ export function checkLocalReady(repoPath: string): StageCheckResult {
   const commands = ["npm.cmd run build", "npm.cmd test", "npm.cmd run doctor:ci"];
   for (const cmdStr of commands) {
     try {
-      execSync(cmdStr, {
-        cwd: repoPath,
-        encoding: "utf-8",
-        timeout: LOCAL_TIMEOUT_MS,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
+      const result = runLocalCommand(repoPath, cmdStr, LOCAL_TIMEOUT_MS);
+      if (result.spawnError) throw new Error(result.spawnError);
+      if (result.timedOut) throw new Error(`Command timed out after ${LOCAL_TIMEOUT_MS}ms`);
+      if (result.exitCode !== 0) {
+        throw Object.assign(new Error(`Command exited with code ${result.exitCode ?? -1}`), { status: result.exitCode ?? -1 });
+      }
     } catch (err) {
       if (err && typeof err === "object" && "status" in err) {
         const code = (err as { status: unknown }).status;
@@ -235,12 +264,11 @@ export function checkLocalReady(repoPath: string): StageCheckResult {
 export function checkPackedReady(repoPath: string): PackedCheckResult {
   let packOutput: string;
   try {
-    packOutput = execSync("npm.cmd pack --dry-run --json", {
-      cwd: repoPath,
-      encoding: "utf-8",
-      timeout: LOCAL_TIMEOUT_MS,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
+    const result = runLocalCommand(repoPath, "npm.cmd pack --dry-run --json", LOCAL_TIMEOUT_MS, 10 * 1024 * 1024);
+    if (result.spawnError) throw new Error(result.spawnError);
+    if (result.timedOut) throw new Error(`npm pack timed out after ${LOCAL_TIMEOUT_MS}ms`);
+    if (result.exitCode !== 0) throw new Error(`npm pack exited with code ${result.exitCode ?? -1}`);
+    packOutput = result.stdout;
   } catch (err) {
     return {
       status: "failed",
@@ -309,7 +337,7 @@ export function checkPackedReady(repoPath: string): PackedCheckResult {
 
   const manifestPath = join(repoPath, "release-artifact-manifest.json");
   try {
-    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+    atomicWriteJsonFileSync(manifestPath, manifest);
   } catch (err) {
     return {
       status: "failed",
@@ -335,6 +363,18 @@ export function checkPackedReady(repoPath: string): PackedCheckResult {
   return { status: "passed", manifestPath };
 }
 
+function runLocalCommand(repoPath: string, commandLine: string, timeoutMs: number, maxStdoutBytes = 512 * 1024) {
+  const invocation = resolveTrustedCommandLine(commandLine, repoPath);
+  return runSimpleProcessSync({
+    command: invocation.command,
+    args: invocation.argsPrefix,
+    cwd: repoPath,
+    timeoutMs,
+    maxStdoutBytes,
+    maxStderrBytes: 512 * 1024,
+  });
+}
+
 /**
  * Stage 3: published_verified
  * Queries the npm registry and confirms the given version exists.
@@ -355,11 +395,12 @@ export async function checkPublishedVerified(
     if (res.statusCode === 404) {
       return { status: "failed", reason: `Package "${packageName}" not found on npm registry` };
     }
-    const data = res.data;
-    if (!data || !data.versions || typeof data.versions !== "object") {
+    const data = asRecord(res.data);
+    const versions = asRecord(data?.versions);
+    if (!versions) {
       return { status: "failed", reason: "npm registry response missing versions object" };
     }
-    if (Object.prototype.hasOwnProperty.call(data.versions, version)) {
+    if (Object.prototype.hasOwnProperty.call(versions, version)) {
       return { status: "passed" };
     }
     return {
@@ -423,12 +464,12 @@ export async function checkCiVerified(
     if (res.statusCode !== 200) {
       return { status: "not_checked", reason: `GitHub API returned ${res.statusCode}` };
     }
-    const data = res.data;
+    const data = asRecord(res.data);
     const runs = Array.isArray(data?.workflow_runs) ? data.workflow_runs : [];
     if (runs.length === 0) {
       return { status: "not_checked", reason: `No CI runs found for branch "${branch}"` };
     }
-    const conclusion = runs[0]?.conclusion;
+    const conclusion = asRecord(runs[0])?.conclusion;
     if (conclusion === "success") {
       return { status: "passed" };
     }
@@ -447,6 +488,12 @@ export async function checkCiVerified(
   }
 }
 
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
 // ── Orchestrator ───────────────────────────────────────────────────
 
 /**