ashlr-plugin 1.36.4 → 1.37.1

package/servers/_llm-providers/cloud.ts

@@ -20,6 +20,8 @@ import { readFile, stat } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
 import type { LlmProvider, LlmSummarizeResult } from "./types.ts";
+import { safeKeyedFetch } from "../_gateway-target.ts";
+import { redactedBody } from "../_redact-keys.ts";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -132,7 +134,7 @@ export const cloudProvider: LlmProvider = {
 
     let res: Response;
     try {
-      res = await fetch(url, {
+      res = await safeKeyedFetch(url, {
         method: "POST",
         signal: ctl.signal,
         headers: {
@@ -152,11 +154,11 @@ export const cloudProvider: LlmProvider = {
 
     // 429 — rate limit (per-minute bucket) OR daily cap exhausted
     if (res.status === 429) {
-      const body = await res.text().catch(() => "");
+      const body = await redactedBody(res, [token]);
       const retryHeader = res.headers.get("retry-after");
       const retryAfterSecs = retryHeader ? parseInt(retryHeader, 10) : undefined;
       throw new CloudRateLimitError(
-        `Cloud LLM rate limit: ${body.slice(0, 200)}`,
+        `Cloud LLM rate limit: ${body}`,
         429,
         Number.isFinite(retryAfterSecs) ? retryAfterSecs : undefined,
       );
@@ -164,13 +166,13 @@ export const cloudProvider: LlmProvider = {
 
     // 5xx — backend error; let dispatcher fall through to onnx/local/snipCompact
     if (res.status >= 500) {
-      const body = await res.text().catch(() => "");
-      throw new Error(`Cloud LLM error ${res.status}: ${body.slice(0, 200)}`);
+      const body = await redactedBody(res, [token]);
+      throw new Error(`Cloud LLM error ${res.status}: ${body}`);
     }
 
     if (!res.ok) {
-      const body = await res.text().catch(() => "");
-      throw new Error(`Cloud LLM error ${res.status}: ${body.slice(0, 200)}`);
+      const body = await redactedBody(res, [token]);
+      throw new Error(`Cloud LLM error ${res.status}: ${body}`);
     }
 
     const latencyMs = Date.now() - t0;

package/servers/_llm-providers/index.ts

@@ -34,9 +34,10 @@ import { bumpSummarization } from "../_stats.ts";
 import { costForLLM } from "../_pricing.ts";
 import { anthropicProvider, _resetAnthropicAvailabilityCache } from "./anthropic.ts";
 import { onnxProvider } from "./onnx.ts";
-import { localProvider, _resetLocalAvailabilityCache } from "./local.ts";
+import { DEFAULT_LOCAL_LLM_URL, localProvider, _resetLocalAvailabilityCache } from "./local.ts";
 import { cloudProvider, _resetCloudAvailabilityCache } from "./cloud.ts";
 import type { LlmProvider, ProviderName } from "./types.ts";
+import { safeKeyedFetch, safeTargetLabel } from "../_gateway-target.ts";
 
 export type { LlmProvider, ProviderName };
 export { _resetAnthropicAvailabilityCache, _resetLocalAvailabilityCache, _resetCloudAvailabilityCache };
@@ -277,15 +278,16 @@ export async function summarizeIfLarge(
   if (summary == null) {
     await logEvent("tool_fallback", { tool: opts.toolName, reason: "llm-unreachable" });
     // Per v1.22 review: when the SELECTED provider is local AND it failed,
-    // surface a one-line stderr warning that names the URL the user
-    // configured. Without this, a typo in ASHLR_LLM_URL silently degrades
+    // surface a one-line stderr warning that names the endpoint the user
+    // configured (scheme://host:port only, so credentials, path and query
+    // in ASHLR_LLM_URL never reach stderr). Without this, a typo in ASHLR_LLM_URL silently degrades
     // every summarization to truncation with the only signal buried inside
     // tool output. Only logged once per process to avoid spam.
     if (provider.name === "local" && !_localUnreachableWarned) {
       _localUnreachableWarned = true;
-      const url = process.env.ASHLR_LLM_URL ?? "http://localhost:1234/v1";
+      const url = process.env.ASHLR_LLM_URL ?? DEFAULT_LOCAL_LLM_URL;
       process.stderr.write(
-        `[ashlr] WARN: local LLM at ${url} unreachable; falling back to truncation. ` +
+        `[ashlr] WARN: local LLM at ${safeTargetLabel(url)} unreachable; falling back to truncation. ` +
         `Verify the endpoint, or unset ASHLR_LLM_URL to let auto-selection prefer Anthropic.\n`,
       );
     }
@@ -315,7 +317,7 @@ async function callLegacyEndpoint(rawText: string, opts: SummarizeOpts): Promise
   const ctl = new AbortController();
   const t = setTimeout(() => ctl.abort(), timeoutMs);
   try {
-    const res = await fetch(`${url}/chat/completions`, {
+    const res = await safeKeyedFetch(`${url}/chat/completions`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
       signal: ctl.signal,

package/servers/_llm-providers/local.ts

@@ -2,7 +2,7 @@
  * Local LLM provider — LM Studio / Ollama via OpenAI-compat API.
  *
  * Preserves the existing _summarize.ts local-LLM logic verbatim:
- *   - ASHLR_LLM_URL (default: http://localhost:1234/v1)
+ *   - ASHLR_LLM_URL (default: http://127.0.0.1:1234/v1)
  *   - ASHLR_LLM_KEY (default: "local-llm")
  *   - ASHLR_LLM_MODEL (default: "qwen/qwen3-coder-30b@8bit")
  *
@@ -11,16 +11,20 @@
  */
 
 import type { LlmProvider, LlmSummarizeResult } from "./types.ts";
+import { safeKeyedFetch } from "../_gateway-target.ts";
+
+export const DEFAULT_LOCAL_LLM_URL = "http://127.0.0.1:1234/v1";
 
 function localEndpoint(): string {
   // Mirror the llmEndpoint() logic from the old _summarize.ts — pro-token
   // auto-routing uses the ashlr cloud; explicit ASHLR_LLM_URL wins; default
-  // is LM Studio at localhost:1234.
+  // is LM Studio at 127.0.0.1:1234 (an IP literal: keyed calls follow the
+  // default-path gateway rules, which do not accept `localhost` by name).
   if (process.env.ASHLR_PRO_TOKEN && !process.env.ASHLR_LLM_URL) {
     const base = process.env.ASHLR_API_URL ?? "https://api.ashlr.ai";
     return `${base}/llm`;
   }
-  return process.env.ASHLR_LLM_URL ?? "http://localhost:1234/v1";
+  return process.env.ASHLR_LLM_URL ?? DEFAULT_LOCAL_LLM_URL;
 }
 
 // Availability cache: { available, expiresAt }
@@ -46,7 +50,7 @@ export const localProvider: LlmProvider = {
     const t = setTimeout(() => ctl.abort(), 2_000);
 
     try {
-      const res = await fetch(`${url}/models`, {
+      const res = await safeKeyedFetch(`${url}/models`, {
         signal: ctl.signal,
         headers: { Authorization: `Bearer ${process.env.ASHLR_LLM_KEY ?? "local-llm"}` },
       });
@@ -81,7 +85,7 @@ export const localProvider: LlmProvider = {
     const t0 = Date.now();
     let res: Response;
     try {
-      res = await fetch(`${url}/chat/completions`, {
+      res = await safeKeyedFetch(`${url}/chat/completions`, {
         method: "POST",
         signal: ctl.signal,
         headers: {

package/servers/_mcp-host.ts

@@ -21,6 +21,8 @@
  *   Cline (cline_mcp_settings.json)           → "cline"
  *   Claude Desktop (claude_desktop_config.json) → "claude-desktop"
  *   Codex CLI (~/.codex/config.toml)          → "codex-cli"
+ *   Gemini CLI (~/.gemini/settings.json)      → "gemini-cli"
+ *   Cursor (.cursor/mcp.json)                 → "cursor"
  *   Anything else                              → "generic"
  *
  * Backwards compat: when unset, we infer "claude-code" so existing installs
@@ -33,6 +35,8 @@ export type McpHost =
   | "cline"
   | "claude-desktop"
   | "codex-cli"
+  | "gemini-cli"
+  | "cursor"
   | "generic";
 
 const KNOWN_HOSTS: ReadonlySet<McpHost> = new Set([
@@ -40,6 +44,8 @@ const KNOWN_HOSTS: ReadonlySet<McpHost> = new Set([
   "cline",
   "claude-desktop",
   "codex-cli",
+  "gemini-cli",
+  "cursor",
   "generic",
 ]);
 

package/servers/_miss-tracker.ts

@@ -0,0 +1,121 @@
+/**
+ * _miss-tracker.ts: compression miss tracking (self-tuning P1).
+ *
+ * A "miss" is a compressed ashlr__read / ashlr__grep result for a target that
+ * is followed by a native Read / Grep of the same target within
+ * MISS_WINDOW_TURNS turns. That re-read signals the compact output was not
+ * enough. Counts feed the per-repo tuner (P2).
+ *
+ * Privacy: local only. Targets are kept only as an 8-char hash in the
+ * per-session pending file; the persistent stats file holds counts keyed by
+ * ashlr tool and file extension, never paths or content.
+ *
+ * Off switches: ASHLR_TUNING=off or ASHLR_SESSION_LOG=0. Best-effort, never throws.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { extname, join, resolve } from "path";
+
+import { sha8 } from "./_history-tracker";
+
+/** A native re-read within this many turns of a compressed result counts as a miss. */
+export const MISS_WINDOW_TURNS = 3;
+
+const ASHLR_TOOLS: Record<string, "read" | "grep"> = {
+  ashlr__read: "read",
+  ashlr__grep: "grep",
+  "mcp__ashlr-efficiency__ashlr__read": "read",
+  "mcp__ashlr-efficiency__ashlr__grep": "grep",
+  mcp__plugin_ashlr_ashlr__ashlr__read: "read",
+  mcp__plugin_ashlr_ashlr__ashlr__grep: "grep",
+};
+const NATIVE_TOOLS: Record<string, "read" | "grep"> = { Read: "read", Grep: "grep" };
+
+export interface MissCounts { compressed: number; misses: number }
+/** stats[tool]["." + ext or "(none)"] */
+export type MissStats = Record<string, Record<string, MissCounts>>;
+
+interface Pending { t: string; tool: string; ext: string; turn: number; missed?: boolean }
+
+export function trackingEnabled(): boolean {
+  return process.env.ASHLR_TUNING !== "off" && process.env.ASHLR_SESSION_LOG !== "0";
+}
+
+export function missStatsPath(homeDir: string): string {
+  return join(homeDir, ".ashlr", "miss-stats.json");
+}
+function pendingPath(homeDir: string, sessionId: string): string {
+  return join(homeDir, ".ashlr", "miss-pending", `${sessionId}.json`);
+}
+
+function readJson<T>(p: string, fallback: T): T {
+  try { return existsSync(p) ? (JSON.parse(readFileSync(p, "utf-8")) as T) : fallback; } catch { return fallback; }
+}
+function writeJson(p: string, v: unknown): void {
+  mkdirSync(join(p, ".."), { recursive: true });
+  writeFileSync(p, JSON.stringify(v), "utf-8");
+}
+
+/** Target path from a Read/Grep or ashlr__read/ashlr__grep tool_input. */
+export function targetOf(input: unknown, cwd: string = process.cwd()): string | null {
+  if (!input || typeof input !== "object") return null;
+  const i = input as Record<string, unknown>;
+  const p = i.file_path ?? i.path;
+  if (typeof p !== "string" || !p.trim()) return null;
+  return resolve(cwd, p);
+}
+
+export function readMissStats(homeDir: string): MissStats {
+  return readJson<MissStats>(missStatsPath(homeDir), {});
+}
+
+/**
+ * Observe one completed tool call. `turn` is the session turn index of this
+ * call. Returns "compressed", "miss", or null (nothing recorded).
+ */
+export function observeToolCall(
+  toolName: string,
+  toolInput: unknown,
+  turn: number,
+  sessionId: string,
+  homeDir: string,
+  cwd: string = process.cwd(),
+): "compressed" | "miss" | null {
+  if (!trackingEnabled()) return null;
+  try {
+    const kind = ASHLR_TOOLS[toolName] ?? NATIVE_TOOLS[toolName];
+    if (!kind) return null;
+    const target = targetOf(toolInput, cwd);
+    if (!target) return null;
+    const t = sha8(target);
+    const pp = pendingPath(homeDir, sessionId);
+    const pending = readJson<Pending[]>(pp, []).filter((e) => turn - e.turn <= MISS_WINDOW_TURNS);
+    const stats = readMissStats(homeDir);
+    const bump = (tool: string, ext: string, key: keyof MissCounts) => {
+      const row = (stats[tool] ??= {});
+      const c = (row[ext] ??= { compressed: 0, misses: 0 });
+      c[key]++;
+    };
+
+    let outcome: "compressed" | "miss" | null = null;
+    if (ASHLR_TOOLS[toolName]) {
+      const tool = `ashlr__${kind}`;
+      const ext = extname(target).toLowerCase() || "(none)";
+      pending.push({ t, tool, ext, turn });
+      bump(tool, ext, "compressed");
+      outcome = "compressed";
+    } else {
+      const hit = pending.find((e) => e.t === t && !e.missed && e.turn < turn);
+      if (hit) {
+        hit.missed = true;
+        bump(hit.tool, hit.ext, "misses");
+        outcome = "miss";
+      }
+    }
+    writeJson(pp, pending);
+    if (outcome) writeJson(missStatsPath(homeDir), stats);
+    return outcome;
+  } catch {
+    return null;
+  }
+}

package/servers/_phantom-exec.ts

@@ -0,0 +1,135 @@
+/**
+ * Value-free detection of a `phantom exec -- <cmd>` session.
+ *
+ * `phantom exec` hands its child fresh `phm_` session tokens in place of real
+ * keys, points the provider SDK base URLs at a local proxy
+ * (`http://127.0.0.1:<port>/<route>/_phantom/<token>/`) and sets
+ * PHANTOM_PROXY_PORT, PHANTOM_PROXY_TOKEN and PHANTOM_SESSION_KEYS. The proxy
+ * swaps the token for the real key on the way out.
+ *
+ * This module only looks at variable NAMES, the `phm_` / `phm:` prefixes and
+ * the base URL host and port. It never resolves a reference, never runs
+ * `phantom reveal`, never returns a key value, and redacts the per-session
+ * proxy token from any URL it reports.
+ */
+
+type Env = Record<string, string | undefined>;
+
+/** Keys the plugin's scripts may send to a provider. */
+export const PROVIDER_KEY_VARS = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"] as const;
+/** Base URL variables `phantom exec` may set for those providers. */
+export const PROVIDER_BASE_URL_VARS = ["ANTHROPIC_BASE_URL", "OPENAI_BASE_URL"] as const;
+
+export type KeyKind = "unset" | "placeholder" | "ref" | "plain";
+
+export interface PhantomExecReport {
+  /** True when PHANTOM_PROXY_PORT is a valid port and PHANTOM_PROXY_TOKEN is present. */
+  inSession: boolean;
+  proxyPort: number | null;
+  /** Per provider key: what kind of value it holds (never the value). */
+  keys: Record<string, KeyKind>;
+  /** Base URLs that point at this session's local proxy, token redacted. */
+  proxiedBaseUrls: Record<string, string>;
+  /** Plain-language warnings, value-free. */
+  warnings: string[];
+}
+
+/** Kind of value held by a key variable, without exposing it. */
+export function keyKind(value: string | undefined): KeyKind {
+  const v = (value ?? "").trim();
+  if (!v) return "unset";
+  if (v.startsWith("phm_")) return "placeholder";
+  if (v.startsWith("phm:")) return "ref";
+  return "plain";
+}
+
+/** Replace the `/_phantom/<token>/` segment so a printed URL carries no token. */
+export function redactProxyUrl(url: string): string {
+  return url.replace(/\/_phantom\/[^/]+/g, "/_phantom/<redacted>");
+}
+
+function validPort(raw: string | undefined): number | null {
+  if (!raw || !/^\d{1,5}$/.test(raw.trim())) return null;
+  const n = Number(raw.trim());
+  return n >= 1 && n <= 65535 ? n : null;
+}
+
+/** True when `url` is a loopback http URL on `port`. */
+function pointsAtProxy(url: string, port: number): boolean {
+  try {
+    const u = new URL(url);
+    const host = u.hostname.replace(/^\[|\]$/g, "");
+    return (
+      u.protocol === "http:" &&
+      (host === "127.0.0.1" || host === "localhost" || host === "::1") &&
+      Number(u.port) === port
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function detectPhantomExec(env: Env = process.env): PhantomExecReport {
+  const proxyPort = validPort(env["PHANTOM_PROXY_PORT"]);
+  const inSession = proxyPort !== null && !!(env["PHANTOM_PROXY_TOKEN"] ?? "").trim();
+  const keys: Record<string, KeyKind> = {};
+  for (const name of PROVIDER_KEY_VARS) keys[name] = keyKind(env[name]);
+  const proxiedBaseUrls: Record<string, string> = {};
+  if (inSession && proxyPort !== null) {
+    for (const name of PROVIDER_BASE_URL_VARS) {
+      const v = (env[name] ?? "").trim();
+      if (v && pointsAtProxy(v, proxyPort)) proxiedBaseUrls[name] = redactProxyUrl(v);
+    }
+  }
+
+  const warnings: string[] = [];
+  const baseFor: Record<string, string> = {
+    ANTHROPIC_API_KEY: "ANTHROPIC_BASE_URL",
+    OPENAI_API_KEY: "OPENAI_BASE_URL",
+  };
+  for (const name of PROVIDER_KEY_VARS) {
+    const kind = keys[name];
+    if (kind === "ref") {
+      warnings.push(
+        `${name} is a phm: reference. The plugin does not resolve references; run under \`phantom exec -- <cmd>\` so the variable holds a session placeholder routed by the proxy.`,
+      );
+    } else if (kind === "placeholder" && !inSession) {
+      warnings.push(
+        `${name} is a phm_ placeholder but this is not a phantom exec session, so a provider would reject it. Run under \`phantom exec -- <cmd>\`.`,
+      );
+    } else if (kind === "placeholder" && !proxiedBaseUrls[baseFor[name]!]) {
+      warnings.push(
+        `${name} is a phm_ placeholder but ${baseFor[name]} does not point at this session's proxy, so the placeholder would go to the provider directly. Check \`phantom why ${name}\`.`,
+      );
+    }
+  }
+  return { inSession, proxyPort, keys, proxiedBaseUrls, warnings };
+}
+
+/** One-line, value-free summary for doctor and the bench scripts. */
+export function describePhantomExec(r: PhantomExecReport): string {
+  const placeholders = Object.entries(r.keys)
+    .filter(([, k]) => k === "placeholder")
+    .map(([n]) => n);
+  if (!r.inSession) {
+    return placeholders.length || Object.values(r.keys).includes("ref")
+      ? "not a phantom exec session (provider keys hold phm values; see warnings)"
+      : "not a phantom exec session";
+  }
+  const routed = Object.keys(r.proxiedBaseUrls);
+  return `phantom exec session on 127.0.0.1:${r.proxyPort}; placeholders: ${placeholders.join(", ") || "none"}; proxied: ${routed.join(", ") || "none"}`;
+}
+
+/**
+ * Whether a provider key is usable for a live call from this process: a plain
+ * key, or a placeholder inside a phantom exec session whose base URL routes
+ * through the proxy. Unset keys and phm: refs are not usable.
+ */
+export function providerKeyUsable(name: (typeof PROVIDER_KEY_VARS)[number], env: Env = process.env): boolean {
+  const r = detectPhantomExec(env);
+  const kind = r.keys[name];
+  if (kind === "plain") return true;
+  if (kind !== "placeholder") return false;
+  const base = name === "ANTHROPIC_API_KEY" ? "ANTHROPIC_BASE_URL" : "OPENAI_BASE_URL";
+  return r.inSession && !!r.proxiedBaseUrls[base];
+}

package/servers/_phantom-preflight.ts

@@ -0,0 +1,130 @@
+/**
+ * Opt-in Phantom agent preflight for `ashlr doctor`, following phantom-secrets
+ * docs/agent-preflight-contract.md (schema_version 1). It runs
+ * `phantom agent doctor --json --strict`, which reads only project files and
+ * environment variables (no vault, no keychain) and prints a value-free
+ * verdict. `--strict` exits 0 ready, 2 degraded, 1 blocked, 3 could not
+ * evaluate.
+ *
+ * Off unless ASHLR_PHANTOM_PREFLIGHT is set:
+ *   1 / true / on  blocked is a fail; degraded or unknown is a warning
+ *   strict         anything but ready is a fail
+ * A missing phantom, or one without `agent doctor --json`, is only a warning.
+ * Output is the verdict and kebab-case check ids; never names or values.
+ */
+
+import { spawnSync } from "child_process";
+
+export type PreflightMode = "off" | "on" | "strict";
+export type Verdict = "ready" | "degraded" | "blocked" | "unknown";
+export type PreflightRunner = () => {
+	status: number | null;
+	stdout: string;
+	missing: boolean;
+};
+
+export interface PreflightResult {
+	status: "ok" | "warn" | "fail";
+	verdict: Verdict | null;
+	/** Ids of the critical checks (`wrap.blocked_by`). Ids only. */
+	blockedBy: string[];
+	detail: string;
+}
+
+export function preflightMode(
+	env: Record<string, string | undefined> = process.env,
+): PreflightMode {
+	const v = (env["ASHLR_PHANTOM_PREFLIGHT"] ?? "").trim().toLowerCase();
+	if (v === "strict") return "strict";
+	if (v === "1" || v === "true" || v === "on") return "on";
+	return "off";
+}
+
+export const defaultPreflightRunner: PreflightRunner = () => {
+	try {
+		const r = spawnSync("phantom", ["agent", "doctor", "--json", "--strict"], {
+			encoding: "utf8",
+			timeout: 15_000,
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+		// Some Bun versions set `error` on a normal exit, so trust `status` first.
+		const missing =
+			r.status === null &&
+			(r.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+		return { status: r.status ?? null, stdout: r.stdout ?? "", missing };
+	} catch {
+		return { status: null, stdout: "", missing: true };
+	}
+};
+
+const EXIT_CODES = new Set([0, 1, 2, 3]);
+const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const VERDICTS: readonly Verdict[] = [
+	"ready",
+	"degraded",
+	"blocked",
+	"unknown",
+];
+
+function parse(
+	stdout: string,
+): { verdict: Verdict; blockedBy: string[] } | null {
+	try {
+		const doc = JSON.parse(stdout) as {
+			schema_version?: unknown;
+			kind?: unknown;
+			verdict?: unknown;
+			wrap?: { blocked_by?: unknown };
+		};
+		if (doc.kind !== "phantom.agent.preflight" || doc.schema_version !== 1)
+			return null;
+		if (!VERDICTS.includes(doc.verdict as Verdict)) return null;
+		const ids = Array.isArray(doc.wrap?.blocked_by) ? doc.wrap.blocked_by : [];
+		const blockedBy = ids.filter(
+			(id): id is string => typeof id === "string" && ID.test(id),
+		);
+		return { verdict: doc.verdict as Verdict, blockedBy };
+	} catch {
+		return null;
+	}
+}
+
+/** Run the preflight; null when it is off. */
+export function runPhantomPreflight(
+	mode: PreflightMode,
+	run: PreflightRunner = defaultPreflightRunner,
+): PreflightResult | null {
+	if (mode === "off") return null;
+	const r = run();
+	if (r.missing) {
+		return {
+			status: "warn",
+			verdict: null,
+			blockedBy: [],
+			detail: "skipped: phantom is not installed",
+		};
+	}
+	const parsed = parse(r.stdout);
+	if (!parsed || r.status === null || !EXIT_CODES.has(r.status)) {
+		return {
+			status: "warn",
+			verdict: null,
+			blockedBy: [],
+			detail: "skipped: this phantom has no `agent doctor --json` (schema 1)",
+		};
+	}
+	const { verdict, blockedBy } = parsed;
+	const status =
+		verdict === "ready"
+			? "ok"
+			: verdict === "blocked" || mode === "strict"
+				? "fail"
+				: "warn";
+	const ids = blockedBy.length ? ` (${blockedBy.join(", ")})` : "";
+	return {
+		status,
+		verdict,
+		blockedBy,
+		detail: `${verdict}${verdict === "blocked" ? ids : ""}`,
+	};
+}

package/servers/_pid-alive.ts

@@ -0,0 +1,40 @@
+/**
+ * _pid-alive.ts — "is this PID still a running process?"
+ *
+ * `process.kill(pid, 0)` succeeds for a zombie: a process that has exited but
+ * whose parent has not reaped it. Containers whose PID 1 is not an init that
+ * reaps orphans (common for agent sandboxes) keep every orphaned exit as a
+ * zombie, so a kill-only check reports long-dead background jobs and lock
+ * owners as alive forever. On Linux, read the state letter from
+ * /proc/<pid>/stat and treat Z (zombie) and X (dead) as gone.
+ */
+
+import { readFileSync } from "fs";
+
+/**
+ * True when `pid` names a live, non-zombie process. EPERM (the process exists
+ * but belongs to another user) counts as alive.
+ */
+export function pidAlive(pid: number): boolean {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EPERM") return false;
+  }
+  return !isLinuxZombie(pid);
+}
+
+function isLinuxZombie(pid: number): boolean {
+  if (process.platform !== "linux") return false;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // Format: "pid (comm) S ...". comm may contain spaces or parentheses, so
+    // the state is the first field after the last ")".
+    const state = stat.slice(stat.lastIndexOf(")") + 2, stat.lastIndexOf(")") + 3);
+    return state === "Z" || state === "X";
+  } catch {
+    // /proc unreadable (hidepid, exotic mounts): fall back to the kill result.
+    return false;
+  }
+}