agent-dealer 0.2.0 → 1.0.0

package/bundle/server/dist/runners/stream-json.js

@@ -1,5 +1,4 @@
 import fs from "node:fs";
-import { OutboundDraftBlock, outboundMessageMatchesSummary, PlanTriageBlock } from "@agent-dealer/shared";
 export function parseNdjson(raw) {
     const events = [];
     for (const line of raw.split("\n")) {
@@ -20,10 +19,6 @@ export function parseNdjsonFile(logPath) {
         return [];
     return parseNdjson(fs.readFileSync(logPath, "utf8"));
 }
-function stripMarkdownFences(text) {
-    const m = text.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/);
-    return m ? m[1].trim() : text.trim();
-}
 export function extractSessionId(events) {
     for (const e of events) {
         if (e.type === "system" && typeof e.session_id === "string")
@@ -31,14 +26,6 @@ export function extractSessionId(events) {
     }
     return undefined;
 }
-export function extractResultIsError(events) {
-    for (let i = events.length - 1; i >= 0; i--) {
-        const e = events[i];
-        if (e.type === "result")
-            return Boolean(e.is_error);
-    }
-    return false;
-}
 export function extractResultText(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const e = events[i];
@@ -59,60 +46,6 @@ export function extractResultText(events) {
     }
     return undefined;
 }
-export function extractPlanMarkdown(events) {
-    const raw = extractResultText(events) ?? "";
-    return stripMarkdownFences(raw);
-}
-const TRIAGE_FALLBACK = {
-    verdict: "needs_review",
-    rationale: "Agent did not return a valid triage block",
-    questions: [],
-    parseFallback: true,
-};
-/** Parse the trailing fenced json triage block from plan markdown (PRD F1.2). */
-export function extractPlanTriage(planMarkdown) {
-    const blocks = [...planMarkdown.matchAll(/```json\s*\n([\s\S]*?)\n```/g)];
-    const last = blocks[blocks.length - 1];
-    if (!last)
-        return { markdown: planMarkdown.trim(), ...TRIAGE_FALLBACK };
-    const strippedMarkdown = (planMarkdown.slice(0, last.index) + planMarkdown.slice(last.index + last[0].length)).trim();
-    try {
-        const parsed = PlanTriageBlock.parse(JSON.parse(last[1]));
-        return {
-            markdown: strippedMarkdown,
-            verdict: parsed.verdict,
-            rationale: parsed.rationale,
-            questions: parsed.questions,
-            parseFallback: false,
-        };
-    }
-    catch {
-        return { markdown: strippedMarkdown, ...TRIAGE_FALLBACK };
-    }
-}
-/** Parse the trailing fenced json outbound draft block from execute result (PRD F2.2). */
-export function extractOutboundDraft(resultMarkdown) {
-    const blocks = [...resultMarkdown.matchAll(/```json\s*\n([\s\S]*?)\n```/g)];
-    const last = blocks[blocks.length - 1];
-    if (!last) {
-        return { markdown: resultMarkdown.trim(), hadJsonBlock: false, invalid: false, mismatch: false };
-    }
-    const strippedMarkdown = (resultMarkdown.slice(0, last.index) + resultMarkdown.slice(last.index + last[0].length)).trim();
-    try {
-        const parsed = OutboundDraftBlock.parse(JSON.parse(last[1]));
-        const mismatch = !outboundMessageMatchesSummary(parsed.toolCall, parsed.summary.body, parsed.actionType);
-        return {
-            markdown: strippedMarkdown,
-            draft: parsed,
-            hadJsonBlock: true,
-            invalid: false,
-            mismatch,
-        };
-    }
-    catch {
-        return { markdown: strippedMarkdown, hadJsonBlock: true, invalid: true, mismatch: false };
-    }
-}
 export function extractUsage(events, phase, runtime) {
     const result = events.find((e) => e.type === "result");
     const init = events.find((e) => e.type === "system");
@@ -132,77 +65,3 @@ export function extractUsage(events, phase, runtime) {
         numTurns: typeof result?.num_turns === "number" ? result.num_turns : undefined,
     };
 }
-function appendAssistantText(entries, text) {
-    const trimmed = text.trim();
-    if (!trimmed)
-        return;
-    const last = entries[entries.length - 1];
-    if (last?.type === "assistant") {
-        last.text = `${last.text}${text}`.slice(-4000);
-    }
-    else {
-        entries.push({ type: "assistant", text: trimmed.slice(0, 4000) });
-    }
-}
-export function buildStreamTrace(events, maxEntries = 80) {
-    const entries = [];
-    for (const e of events) {
-        const t = String(e.type ?? "");
-        if (t === "system" && e.subtype === "init") {
-            entries.push({
-                type: "system",
-                text: `session ${String(e.session_id ?? "?").slice(0, 8)} · model ${String(e.model ?? "?")}`,
-            });
-        }
-        if (t === "thinking") {
-            const delta = typeof e.text === "string" ? e.text : "";
-            if (e.subtype === "completed") {
-                entries.push({ type: "thinking", text: "(reasoning complete)" });
-            }
-            else if (delta) {
-                const last = entries[entries.length - 1];
-                if (last?.type === "thinking" && last.text !== "(reasoning complete)") {
-                    last.text = `${last.text}${delta}`.slice(-2000);
-                }
-                else {
-                    entries.push({ type: "thinking", text: delta.slice(0, 2000) });
-                }
-            }
-        }
-        if (t === "assistant") {
-            const msg = e.message;
-            if (msg?.content) {
-                for (const block of msg.content) {
-                    if (block.type === "thinking" && block.thinking) {
-                        entries.push({ type: "thinking", text: block.thinking.slice(0, 2000) });
-                    }
-                    else if (block.type === "text" && block.text) {
-                        appendAssistantText(entries, block.text);
-                    }
-                    else if (block.type === "tool_use" && block.name) {
-                        entries.push({ type: "tool", text: `invoke ${block.name}`, toolName: block.name });
-                    }
-                }
-            }
-        }
-        if (t === "tool_call") {
-            const name = String(e.name ?? e.tool_name ?? "tool");
-            entries.push({ type: "tool", text: `invoke ${name}`, toolName: name });
-        }
-        if (t === "rate_limit_event") {
-            const info = e.rate_limit_info;
-            entries.push({
-                type: "rate_limit",
-                text: `rate limit ${info?.status ?? "?"} (${info?.rateLimitType ?? "?"})`,
-            });
-        }
-        if (t === "result") {
-            const preview = typeof e.result === "string" ? e.result.slice(0, 500) : "";
-            entries.push({
-                type: "result",
-                text: preview || (e.is_error ? "error" : "done"),
-            });
-        }
-    }
-    return entries.slice(-maxEntries);
-}

package/bundle/server/dist/runners/usage-cap.js

@@ -0,0 +1,242 @@
+// packages/server/src/runners/usage-cap.ts
+//
+// NOT-111: detect hard usage-cap signals from CLI NDJSON logs and persist runtime_availability.
+// NOT-117: Cursor/Codex text fallback must not scan assistant/tool file contents (false
+// positives like "infra-attempt limit reached" in source); successful sessions never open a
+// deferral from body text alone.
+import fs from "node:fs";
+import { usageCapFallbackCooldownMs } from "../coordinator/usage-cap-config.js";
+import { recordRuntimeAvailability } from "../repository/runtime-availability.js";
+import { parseCodexJsonl } from "./codex-jsonl.js";
+import { parseNdjson } from "./stream-json.js";
+/** Structured / result-error prose — no bare "limit reached" (NOT-117). */
+const CAP_ERROR_RE = /\b(rate\s*limit(?:ed)?|usage\s*limit|quota\s*exceeded|billing_error|subscription\s*limit)\b/i;
+/**
+ * Text-only fallback (stderr / error result). Requires rate|usage|quota|subscription
+ * near "limit", or an explicit billing/quota phrase — never bare "limit reached".
+ */
+const CAP_FALLBACK_RE = /\b((?:rate|usage|quota|subscription)\s+limits?(?:\s+\w+){0,4}\s+reached|(?:rate|usage)\s*limit(?:ed)?|quota\s+exceeded|billing_error|subscription\s+limit)\b/i;
+function parseResetsAt(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return null;
+    const ms = raw > 1e12 ? raw : raw * 1000;
+    const d = new Date(ms);
+    return Number.isFinite(d.getTime()) ? d : null;
+}
+function fallbackUntil(nowMs = Date.now()) {
+    return new Date(nowMs + usageCapFallbackCooldownMs()).toISOString();
+}
+function capReason(runtime, detail) {
+    return `${runtime} usage capped — ${detail}`;
+}
+function isHardCapRateLimitInfo(info) {
+    if (info.status === "rejected")
+        return true;
+    if (info.overageStatus === "rejected")
+        return true;
+    return false;
+}
+function signalFromRateLimitInfo(runtime, info, evidence, nowMs) {
+    if (!isHardCapRateLimitInfo(info))
+        return null;
+    const reset = parseResetsAt(info.resetsAt) ??
+        parseResetsAt(info.overageResetsAt) ??
+        parseResetsAt(info.overage_resets_at) ??
+        parseResetsAt(info.resets_at);
+    const unavailableUntil = reset && reset.getTime() > nowMs ? reset.toISOString() : fallbackUntil(nowMs);
+    const limitType = String(info.rateLimitType ?? info.rate_limit_type ?? "plan");
+    return {
+        unavailableUntil,
+        reason: capReason(runtime, `${limitType} limit rejected`),
+        evidence: { ...evidence, rate_limit_info: info },
+    };
+}
+function signalFromApiRetry(e, runtime, nowMs) {
+    if (e.type !== "system")
+        return null;
+    const subtype = String(e.subtype ?? "");
+    if (subtype !== "api_retry" && subtype !== "error")
+        return null;
+    const err = String(e.error ?? "");
+    // Hard cap only — transient api_retry rate_limit is not an account cap (NOT-111).
+    if (err !== "billing_error")
+        return null;
+    return {
+        unavailableUntil: fallbackUntil(nowMs),
+        reason: capReason(runtime, err.replace("_", " ")),
+        evidence: { event: e },
+    };
+}
+function signalFromResultError(e, runtime, nowMs) {
+    if (e.type !== "result" || !e.is_error)
+        return null;
+    const text = typeof e.result === "string" ? e.result : "";
+    if (!CAP_ERROR_RE.test(text))
+        return null;
+    return {
+        unavailableUntil: fallbackUntil(nowMs),
+        reason: capReason(runtime, "session ended with cap error"),
+        evidence: { result: text.slice(0, 500) },
+    };
+}
+/** Parse Claude/Cursor-shaped NDJSON events for a hard cap (rate_limit_event preferred over result error). */
+export function extractUsageCapFromEvents(events, runtime, nowMs = Date.now()) {
+    let fromRateLimit = null;
+    let fromResult = null;
+    for (const e of events) {
+        if (e.type === "rate_limit_event") {
+            const info = e.rate_limit_info;
+            if (info && typeof info === "object") {
+                const sig = signalFromRateLimitInfo(runtime, info, { event: e }, nowMs);
+                if (sig)
+                    fromRateLimit = sig;
+            }
+        }
+        const api = signalFromApiRetry(e, runtime, nowMs);
+        if (api)
+            fromRateLimit = api;
+        const res = signalFromResultError(e, runtime, nowMs);
+        if (res)
+            fromResult = res;
+    }
+    return fromRateLimit ?? fromResult;
+}
+function codexCapFromEvents(events, runtime, nowMs) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.type === "turn.failed") {
+            const err = e.error;
+            let msg = "";
+            if (typeof err === "string")
+                msg = err;
+            else if (err && typeof err === "object") {
+                msg = String(err.message ?? "");
+            }
+            if (CAP_ERROR_RE.test(msg)) {
+                return {
+                    unavailableUntil: fallbackUntil(nowMs),
+                    reason: capReason(runtime, msg.slice(0, 120) || "turn failed"),
+                    evidence: { turn_failed: err },
+                };
+            }
+        }
+        if (e.type === "error" && typeof e.message === "string" && CAP_ERROR_RE.test(e.message)) {
+            return {
+                unavailableUntil: fallbackUntil(nowMs),
+                reason: capReason(runtime, e.message.slice(0, 120)),
+                evidence: { error: e.message },
+            };
+        }
+    }
+    return null;
+}
+function parseEventsForRuntime(raw, runtime) {
+    if (runtime === "codex_local")
+        return parseCodexJsonl(raw);
+    return parseNdjson(raw);
+}
+/**
+ * True when the stream ended successfully — used to skip Codex/Cursor text fallback
+ * (NOT-117). Cursor/Claude use a non-error `result`; Codex native JSONL uses
+ * `turn.completed` (never emits `type: "result"` until normalizeCodexEvents).
+ */
+function sessionEndedSuccessfully(events, runtime) {
+    if (runtime === "codex_local") {
+        for (let i = events.length - 1; i >= 0; i--) {
+            const e = events[i];
+            if (e.type === "turn.failed")
+                return false;
+            if (e.type === "error")
+                return false;
+            if (e.type === "turn.completed")
+                return true;
+        }
+        return false;
+    }
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.type === "result")
+            return !e.is_error;
+    }
+    return false;
+}
+/**
+ * Text fallback haystack: stderr trailer + error-result strings only — never assistant /
+ * tool / file-read bodies (NOT-117 false-positive source).
+ */
+function textFallbackHaystack(raw, events) {
+    const stderr = raw.includes("\n--- stderr ---\n") ? raw.split("\n--- stderr ---\n")[1] ?? "" : "";
+    const resultBits = [];
+    for (const e of events) {
+        if (e.type === "result" && e.is_error && typeof e.result === "string") {
+            resultBits.push(e.result);
+        }
+    }
+    return `${resultBits.join("\n")}\n${stderr}`;
+}
+/** Detect from an in-memory NDJSON string (unit tests). */
+export function detectUsageCapFromNdjson(raw, runtime, nowMs = Date.now()) {
+    const events = parseEventsForRuntime(raw, runtime);
+    if (runtime === "codex_local")
+        return codexCapFromEvents(events, runtime, nowMs);
+    return extractUsageCapFromEvents(events, runtime, nowMs);
+}
+/**
+ * Full-log detection including Cursor/Codex text fallback (unit tests that need the
+ * NOT-117 path without writing a temp file).
+ */
+export function detectUsageCapFromRawLog(raw, runtime, nowMs = Date.now()) {
+    const events = parseEventsForRuntime(raw, runtime);
+    const fromEvents = runtime === "codex_local"
+        ? codexCapFromEvents(events, runtime, nowMs)
+        : extractUsageCapFromEvents(events, runtime, nowMs);
+    if (fromEvents)
+        return fromEvents;
+    if (runtime === "codex_local" || runtime === "cursor_local") {
+        // Successful sessions must not open a usage-cap deferral from log body text (NOT-117).
+        if (sessionEndedSuccessfully(events, runtime))
+            return null;
+        const haystack = textFallbackHaystack(raw, events);
+        if (CAP_FALLBACK_RE.test(haystack)) {
+            return {
+                unavailableUntil: fallbackUntil(nowMs),
+                reason: capReason(runtime, "stderr/log matched usage-cap pattern"),
+                evidence: { matched: haystack.slice(0, 300) },
+            };
+        }
+    }
+    return null;
+}
+export function detectUsageCapFromLog(logPath, runtime, nowMs = Date.now()) {
+    if (!fs.existsSync(logPath))
+        return null;
+    return detectUsageCapFromRawLog(fs.readFileSync(logPath, "utf8"), runtime, nowMs);
+}
+/** Persist a cap row when detected; returns the detection or null. */
+export function recordUsageCapFromLog(logPath, runtime, nowMs = Date.now()) {
+    const cap = detectUsageCapFromLog(logPath, runtime, nowMs);
+    if (!cap)
+        return null;
+    recordRuntimeAvailability({
+        runtime,
+        unavailableUntil: cap.unavailableUntil,
+        reason: cap.reason,
+        evidence: cap.evidence,
+    });
+    return cap;
+}
+/** Convenience for callers that already parsed events (e.g. stream-json tests). */
+export function recordUsageCapFromEvents(events, runtime, nowMs = Date.now()) {
+    const cap = runtime === "codex_local"
+        ? codexCapFromEvents(events, runtime, nowMs)
+        : extractUsageCapFromEvents(events, runtime, nowMs);
+    if (!cap)
+        return null;
+    recordRuntimeAvailability({
+        runtime,
+        unavailableUntil: cap.unavailableUntil,
+        reason: cap.reason,
+        evidence: cap.evidence,
+    });
+    return cap;
+}

package/bundle/server/dist/runners/usage-cap.test.js

@@ -0,0 +1,97 @@
+import { test, before, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-cap-home-"));
+process.env.USAGE_CAP_FALLBACK_COOLDOWN_MS = "1800000";
+const fixtureDir = path.dirname(fileURLToPath(import.meta.url));
+const claudeFixture = fs.readFileSync(path.join(fixtureDir, "fixtures/claude-rate-limit-rejected.ndjson"), "utf8");
+const { migrate } = await import("../db/index.js");
+const { recordUsageCapFromEvents, detectUsageCapFromNdjson, detectUsageCapFromRawLog, detectUsageCapFromLog, extractUsageCapFromEvents, } = await import("./usage-cap.js");
+const { parseNdjson } = await import("./stream-json.js");
+const { runtimeAvailability, clearAllRuntimeAvailability, } = await import("../repository/runtime-availability.js");
+before(() => migrate());
+beforeEach(() => clearAllRuntimeAvailability());
+test("Claude rate_limit_event rejected writes runtime_availability with resetsAt", () => {
+    const nowMs = Date.parse("2026-01-01T00:00:00.000Z");
+    const events = parseNdjson(claudeFixture);
+    const cap = recordUsageCapFromEvents(events, "claude_code", nowMs);
+    assert.ok(cap);
+    assert.equal(cap.unavailableUntil, new Date(1784283600 * 1000).toISOString());
+    const avail = runtimeAvailability("claude_code", nowMs);
+    assert.equal(avail.available, false);
+    if (!avail.available) {
+        assert.equal(avail.until, cap.unavailableUntil);
+    }
+});
+test("allowed_warning rate_limit_event is ignored (hard cap only)", () => {
+    const raw = [
+        '{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning","resetsAt":1784283600,"rateLimitType":"five_hour"}}',
+    ].join("\n");
+    const cap = detectUsageCapFromNdjson(raw, "claude_code");
+    assert.equal(cap, null);
+});
+test("missing reset time uses fallback cooldown", () => {
+    const nowMs = Date.parse("2026-06-01T12:00:00.000Z");
+    const raw = '{"type":"rate_limit_event","rate_limit_info":{"status":"rejected","rateLimitType":"five_hour","overageStatus":"rejected"}}';
+    const cap = detectUsageCapFromNdjson(raw, "claude_code", nowMs);
+    assert.ok(cap);
+    assert.equal(cap.unavailableUntil, new Date(nowMs + 1_800_000).toISOString());
+});
+test("result error without prior event uses fallback cooldown", () => {
+    const nowMs = Date.parse("2026-06-01T12:00:00.000Z");
+    const events = parseNdjson('{"type":"result","is_error":true,"result":"Rate limit exceeded for this account."}');
+    const cap = extractUsageCapFromEvents(events, "claude_code", nowMs);
+    assert.ok(cap);
+    assert.equal(cap.unavailableUntil, new Date(nowMs + 1_800_000).toISOString());
+});
+test("NOT-117: successful Cursor NDJSON with source text 'infra-attempt limit reached' does not detect or record availability", () => {
+    const fixture = fs.readFileSync(path.join(fixtureDir, "fixtures/cursor-success-with-infra-attempt-limit-text.ndjson"), "utf8");
+    const cap = detectUsageCapFromRawLog(fixture, "cursor_local");
+    assert.equal(cap, null);
+    const logPath = path.join(process.env.AGENT_DEALER_HOME, "cursor-false-positive.ndjson");
+    fs.writeFileSync(logPath, fixture);
+    assert.equal(detectUsageCapFromLog(logPath, "cursor_local"), null);
+    assert.equal(runtimeAvailability("cursor_local").available, true);
+});
+test("NOT-117: Cursor billing_error and usage-limit result errors still detect", () => {
+    const billing = fs.readFileSync(path.join(fixtureDir, "fixtures/cursor-billing-error.ndjson"), "utf8");
+    const usage = fs.readFileSync(path.join(fixtureDir, "fixtures/cursor-result-usage-limit.ndjson"), "utf8");
+    assert.ok(detectUsageCapFromRawLog(billing, "cursor_local"));
+    assert.ok(detectUsageCapFromRawLog(usage, "cursor_local"));
+    const rejected = [
+        '{"type":"rate_limit_event","rate_limit_info":{"status":"rejected","resetsAt":1784283600,"rateLimitType":"five_hour"}}',
+    ].join("\n");
+    assert.ok(detectUsageCapFromRawLog(rejected, "cursor_local"));
+});
+test("NOT-117: Cursor stderr trailer with usage limit still detects; bare 'limit reached' in stderr does not", () => {
+    const withUsage = '{"type":"result","is_error":true,"result":"failed"}\n--- stderr ---\nError: usage limit reached for this account\n';
+    assert.ok(detectUsageCapFromRawLog(withUsage, "cursor_local"));
+    const bare = '{"type":"result","is_error":true,"result":"failed"}\n--- stderr ---\nError: infra-attempt limit reached\n';
+    assert.equal(detectUsageCapFromRawLog(bare, "cursor_local"), null);
+});
+test("NOT-117: successful session ignores stderr usage-cap-like prose (structured path already empty)", () => {
+    const raw = '{"type":"result","is_error":false,"result":"done"}\n--- stderr ---\nwarning: usage limit reached\n';
+    assert.equal(detectUsageCapFromRawLog(raw, "cursor_local"), null);
+});
+test("NOT-117: successful Codex turn.completed skips text fallback even when stderr has usage-limit prose", () => {
+    const raw = [
+        '{"type":"thread.started","thread_id":"t1"}',
+        '{"type":"item.completed","item":{"type":"agent_message","text":"Done implementing."}}',
+        '{"type":"turn.completed","usage":{"input_tokens":10,"output_tokens":5}}',
+        "",
+        "--- stderr ---",
+        "npm warn: your usage limit reached for deprecated flag foo (unrelated to billing)",
+    ].join("\n");
+    assert.equal(detectUsageCapFromRawLog(raw, "codex_local"), null);
+    const failed = [
+        '{"type":"thread.started","thread_id":"t1"}',
+        '{"type":"turn.failed","error":{"message":"Rate limit exceeded"}}',
+        "",
+        "--- stderr ---",
+        "noise",
+    ].join("\n");
+    assert.ok(detectUsageCapFromRawLog(failed, "codex_local"));
+});

package/bundle/server/dist/server-liveness.js

@@ -0,0 +1,37 @@
+// packages/server/src/server-liveness.ts
+//
+// A liveness marker the server writes for *itself*, directly from its own entrypoint
+// (index.ts), independent of how it was launched. This exists because the only prior
+// liveness signal — packages/cli/src/runtime-state.ts's run.json — is written solely by
+// the packaged CLI's daemon supervisor (`agent-dealer start`). The documented `npm run
+// dev` and `npm run start` paths invoke this package's entrypoint directly and never go
+// through that supervisor, so a check that only looked at run.json (as
+// db/migrate-to-issues.ts's isServiceRunning() originally did) silently reported "not
+// running" for the two most common ways this app is actually launched during development
+// and self-hosted production use — the migration script's core safety promise ("refuses
+// to run against a live service") was a no-op for those paths. Writing this file from the
+// server's own main(), before it touches the database, makes the guard hold in every
+// launch mode: dev, `npm start`, and the CLI daemon (which runs this exact same entrypoint
+// as a spawned child).
+//
+// Thin wrapper over pid-marker.ts's generic exclusive-claim primitive — see that module
+// for why the claim/release semantics are ownership-aware rather than a plain overwrite,
+// and for why the migration script (db/migrate-to-issues.ts) claims this *same* file for
+// the duration of a cutover.
+import path from "node:path";
+import { getDataDir } from "./db/index.js";
+import { claimPidMarker, releasePidMarker } from "./pid-marker.js";
+export function serverPidFilePath() {
+    return path.join(getDataDir(), "server.pid");
+}
+/** Claims the marker for this server process. A false return means a different, live
+ * process already owns this AGENT_DEALER_HOME — the caller (index.ts) must treat that as
+ * fatal and refuse to start, not merely warn and continue, or this server would run
+ * fully unmonitored: untracked by the marker, invisible to isServiceRunning(), and free
+ * to write to the same database a migration might concurrently believe is safe to touch. */
+export function writeServerPidFile(port) {
+    return claimPidMarker(serverPidFilePath(), { port });
+}
+export function removeServerPidFile() {
+    releasePidMarker(serverPidFilePath());
+}

package/bundle/server/dist/server-liveness.test.js

@@ -0,0 +1,82 @@
+// packages/server/src/server-liveness.test.ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+/** A genuinely alive, same-user child pid — safe to signal, unlike e.g. pid 1 (which is
+ * alive but throws EPERM rather than ESRCH for an unprivileged process.kill probe). */
+function spawnLiveChild() {
+    const child = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { stdio: "ignore" });
+    return { pid: child.pid, kill: () => child.kill("SIGKILL") };
+}
+function freshHome() {
+    process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-server-liveness-"));
+}
+const { writeServerPidFile, removeServerPidFile, serverPidFilePath } = await import("./server-liveness.js");
+test("writeServerPidFile claims the marker when none exists", () => {
+    freshHome();
+    const claimed = writeServerPidFile(3221);
+    assert.equal(claimed, true);
+    const state = JSON.parse(fs.readFileSync(serverPidFilePath(), "utf8"));
+    assert.equal(state.pid, process.pid);
+    assert.equal(state.port, 3221);
+});
+test("writeServerPidFile refuses to clobber a marker owned by a different, live pid", () => {
+    freshHome();
+    const other = spawnLiveChild();
+    try {
+        const filePath = serverPidFilePath();
+        fs.writeFileSync(filePath, JSON.stringify({ pid: other.pid, port: 9999, startedAt: "x" }));
+        const claimed = writeServerPidFile(3221);
+        assert.equal(claimed, false);
+        const state = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        assert.equal(state.pid, other.pid, "the other live owner's marker must be untouched");
+    }
+    finally {
+        other.kill();
+    }
+});
+test("writeServerPidFile reclaims a stale marker (dead pid)", () => {
+    freshHome();
+    const filePath = serverPidFilePath();
+    fs.writeFileSync(filePath, JSON.stringify({ pid: 999999, port: 9999, startedAt: "x" }));
+    const claimed = writeServerPidFile(3221);
+    assert.equal(claimed, true);
+    const state = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    assert.equal(state.pid, process.pid);
+});
+test("writeServerPidFile reclaims an unreadable/corrupt marker", () => {
+    freshHome();
+    const filePath = serverPidFilePath();
+    fs.writeFileSync(filePath, "not json");
+    const claimed = writeServerPidFile(3221);
+    assert.equal(claimed, true);
+    const state = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    assert.equal(state.pid, process.pid);
+});
+test("removeServerPidFile only removes a marker that currently names this process", () => {
+    freshHome();
+    const other = spawnLiveChild();
+    try {
+        const filePath = serverPidFilePath();
+        fs.writeFileSync(filePath, JSON.stringify({ pid: other.pid, port: 9999, startedAt: "x" }));
+        removeServerPidFile(); // this process never owned it — a loser's cleanup, essentially
+        assert.ok(fs.existsSync(filePath), "a marker owned by a different pid must survive removeServerPidFile()");
+        assert.equal(JSON.parse(fs.readFileSync(filePath, "utf8")).pid, other.pid);
+    }
+    finally {
+        other.kill();
+    }
+});
+test("removeServerPidFile removes a marker this process does own", () => {
+    freshHome();
+    writeServerPidFile(3221);
+    removeServerPidFile();
+    assert.equal(fs.existsSync(serverPidFilePath()), false);
+});
+test("removeServerPidFile on an absent file is a no-op", () => {
+    freshHome();
+    assert.doesNotThrow(() => removeServerPidFile());
+});

package/bundle/server/dist/static-ui.test.js

@@ -0,0 +1,44 @@
+// packages/server/src/static-ui.test.ts
+// NOT-142: packaged Fastify must SPA-fallback client routes so reload/deep-link work.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import Fastify from "fastify";
+const uiDist = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-static-ui-"));
+fs.writeFileSync(path.join(uiDist, "index.html"), "<!doctype html><html><body>agent-dealer-spa</body></html>\n");
+process.env.AGENT_DEALER_UI_DIST = uiDist;
+const { registerStaticUi } = await import("./static-ui.js");
+after(() => {
+    fs.rmSync(uiDist, { recursive: true, force: true });
+    delete process.env.AGENT_DEALER_UI_DIST;
+});
+async function buildApp() {
+    const app = Fastify();
+    app.get("/health", async () => ({ ok: true }));
+    app.get("/api/ping", async () => ({ ok: true }));
+    await registerStaticUi(app);
+    return app;
+}
+test("NOT-142: unknown non-API paths serve index.html for SPA deep links", async () => {
+    const app = await buildApp();
+    for (const url of ["/issues", "/issues/abc-123", "/agents", "/typo-path"]) {
+        const res = await app.inject({ method: "GET", url });
+        assert.equal(res.statusCode, 200, url);
+        assert.match(res.body, /agent-dealer-spa/, url);
+    }
+    await app.close();
+});
+test("NOT-142: /api/* and /health keep not-found/health semantics (no SPA catch-all)", async () => {
+    const app = await buildApp();
+    const health = await app.inject({ method: "GET", url: "/health" });
+    assert.equal(health.statusCode, 200);
+    assert.deepEqual(health.json(), { ok: true });
+    const apiOk = await app.inject({ method: "GET", url: "/api/ping" });
+    assert.equal(apiOk.statusCode, 200);
+    const apiMissing = await app.inject({ method: "GET", url: "/api/does-not-exist" });
+    assert.equal(apiMissing.statusCode, 404);
+    assert.deepEqual(apiMissing.json(), { error: "Not found" });
+    await app.close();
+});