@gr8ful/spf 0.1.0

package/dist/test/agent_cc.test.js

@@ -0,0 +1,95 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { isKnownToolName, CcToolCallTracker } from "../core/agent_cc.js";
+test("isKnownToolName: SPF's lowercase vocabulary maps onto Claude Code's own tool names, ls is known-but-dropped, typos are unknown", () => {
+    for (const name of ["read", "write", "edit", "bash", "grep", "glob"]) {
+        assert.equal(isKnownToolName(name), true, name);
+    }
+    assert.equal(isKnownToolName("find"), true, "find aliases to glob");
+    assert.equal(isKnownToolName("ls"), true, "ls is a known name, just dropped");
+    assert.equal(isKnownToolName("harness_engineering_only"), false);
+    assert.equal(isKnownToolName("bogus"), false);
+});
+// Every message shape below is a real captured line from `claude -p
+// --output-format stream-json --verbose` (v2.1.237), not a guess — see
+// agent_cc.ts's module doc comment for the exact commands run.
+test("CcToolCallTracker: folds a real tool_use + tool_result pair into one record", () => {
+    const tracker = new CcToolCallTracker();
+    assert.equal(tracker.observe({
+        type: "assistant",
+        message: {
+            content: [{ type: "tool_use", id: "toolu_01ABC", name: "Read", input: { file_path: "/private/tmp/cc-probe/test.txt" } }],
+        },
+        timestamp: "2026-08-20T11:40:00.000Z",
+    }), null, "the assistant's tool_use alone produces no record");
+    const record = tracker.observe({
+        type: "user",
+        message: {
+            content: [{ type: "tool_result", tool_use_id: "toolu_01ABC", content: "1\thello world\n2\t" }],
+        },
+        timestamp: "2026-08-20T11:40:00.500Z",
+    });
+    assert.ok(record);
+    assert.equal(record.tool, "Read");
+    assert.equal(record.tool_call_id, "toolu_01ABC");
+    assert.deepEqual(record.args, { file_path: "/private/tmp/cc-probe/test.txt" });
+    assert.equal(record.ok, true);
+    assert.equal(record.label, "Read: /private/tmp/cc-probe/test.txt");
+    assert.equal(record.result_snippet, "1\thello world\n2\t");
+    assert.equal(record.duration_ms, 500);
+});
+test("CcToolCallTracker: a real StructuredOutput call folds like any other tool call, deliberately unfiltered", () => {
+    const tracker = new CcToolCallTracker();
+    tracker.observe({
+        type: "assistant",
+        message: {
+            content: [
+                {
+                    type: "tool_use",
+                    id: "toolu_01MPFgPqyPeEzWfqRE25JLzF",
+                    name: "StructuredOutput",
+                    input: { status: "success", summary: "hello from claude code" },
+                },
+            ],
+        },
+    });
+    const record = tracker.observe({
+        type: "user",
+        message: {
+            content: [{ type: "tool_result", tool_use_id: "toolu_01MPFgPqyPeEzWfqRE25JLzF", content: "Structured output provided successfully" }],
+        },
+    });
+    assert.ok(record);
+    assert.equal(record.tool, "StructuredOutput");
+    assert.equal(record.ok, true);
+    assert.equal(record.result_snippet, "Structured output provided successfully");
+});
+test("CcToolCallTracker: is_error:true on the tool_result folds to ok:false", () => {
+    const tracker = new CcToolCallTracker();
+    tracker.observe({
+        type: "assistant",
+        message: { content: [{ type: "tool_use", id: "toolu_err", name: "Bash", input: { command: "false" } }] },
+    });
+    const record = tracker.observe({
+        type: "user",
+        message: { content: [{ type: "tool_result", tool_use_id: "toolu_err", content: "command failed", is_error: true }] },
+    });
+    assert.ok(record);
+    assert.equal(record.ok, false);
+});
+test("CcToolCallTracker: non-tool message types (system, thinking-only assistant, result) produce no record", () => {
+    const tracker = new CcToolCallTracker();
+    assert.equal(tracker.observe({ type: "system", subtype: "init", cwd: "/tmp", session_id: "s1", tools: [] }), null);
+    assert.equal(tracker.observe({ type: "assistant", message: { content: [{ type: "thinking", thinking: "..." }] } }), null);
+    assert.equal(tracker.observe({ type: "result", subtype: "success", session_id: "s1" }), null);
+});
+test("CcToolCallTracker: a tool_result with no matching tool_use still produces a record (defensive)", () => {
+    const tracker = new CcToolCallTracker();
+    const record = tracker.observe({
+        type: "user",
+        message: { content: [{ type: "tool_result", tool_use_id: "orphan", content: "ok" }] },
+    });
+    assert.ok(record);
+    assert.equal(record.tool, "tool");
+    assert.deepEqual(record.args, {});
+});

package/dist/test/agent_flue.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/agent_flue.test.js

@@ -0,0 +1,83 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { isKnownToolName, resolveModel, ToolCallTracker } from "../core/agent_flue.js";
+test("resolveModel: accepts provider/model-id, rejects anything else", () => {
+    assert.deepEqual(resolveModel("openrouter/google/gemini-3.6-flash"), ["openrouter", "google/gemini-3.6-flash"]);
+    assert.deepEqual(resolveModel("openai/gpt-5.6-terra"), ["openai", "gpt-5.6-terra"]);
+    assert.throws(() => resolveModel("gpt-5.6-terra"), /must be written as provider\/model-id/);
+    assert.throws(() => resolveModel("/gpt-5.6-terra"), /must be written as provider\/model-id/);
+    assert.throws(() => resolveModel("openai/"), /must be written as provider\/model-id/);
+});
+test("isKnownToolName: pi vocabulary maps onto Flue's six builtins, ls is known-but-dropped, typos are unknown", () => {
+    for (const name of ["read", "write", "edit", "bash", "grep", "glob"]) {
+        assert.equal(isKnownToolName(name), true, name);
+    }
+    assert.equal(isKnownToolName("find"), true, "find aliases to glob");
+    assert.equal(isKnownToolName("ls"), true, "ls is a known name, just dropped");
+    assert.equal(isKnownToolName("subagent_create"), false, "harness_engineering-only names are unknown here");
+    assert.equal(isKnownToolName("bogus"), false);
+});
+test("ToolCallTracker: folds tool-input + tool-output into one record", () => {
+    const tracker = new ToolCallTracker();
+    assert.equal(tracker.observe({
+        type: "tool-input",
+        conversationId: "c1",
+        messageId: "m1",
+        toolCallId: "call1",
+        toolName: "bash",
+        input: { command: "ls -la src" },
+        position: { batch: 0, index: 0 },
+    }), null, "tool-input alone produces no record");
+    const record = tracker.observe({
+        type: "tool-output",
+        conversationId: "c1",
+        toolCallId: "call1",
+        output: "src/index.ts\nsrc/core",
+        durationMs: 12,
+        position: { batch: 0, index: 1 },
+    });
+    assert.ok(record);
+    assert.equal(record.tool, "bash");
+    assert.equal(record.tool_call_id, "call1");
+    assert.deepEqual(record.args, { command: "ls -la src" });
+    assert.equal(record.ok, true);
+    assert.equal(record.label, "bash: ls -la src");
+    assert.equal(record.result_snippet, "src/index.ts\nsrc/core");
+    assert.equal(record.duration_ms, 12);
+});
+test("ToolCallTracker: tool-output-error folds to ok:false with the error text as the snippet", () => {
+    const tracker = new ToolCallTracker();
+    tracker.observe({
+        type: "tool-input",
+        conversationId: "c1",
+        messageId: "m1",
+        toolCallId: "call2",
+        toolName: "read",
+        input: { path: "missing.txt" },
+        position: { batch: 0, index: 0 },
+    });
+    const record = tracker.observe({
+        type: "tool-output-error",
+        conversationId: "c1",
+        toolCallId: "call2",
+        errorText: "ENOENT: no such file",
+        position: { batch: 0, index: 1 },
+    });
+    assert.ok(record);
+    assert.equal(record.ok, false);
+    assert.equal(record.result_snippet, "ENOENT: no such file");
+    assert.equal(record.label, "read: missing.txt");
+});
+test("ToolCallTracker: a tool-output with no matching tool-input still produces a record (defensive)", () => {
+    const tracker = new ToolCallTracker();
+    const record = tracker.observe({
+        type: "tool-output",
+        conversationId: "c1",
+        toolCallId: "orphan",
+        output: "ok",
+        position: { batch: 0, index: 0 },
+    });
+    assert.ok(record);
+    assert.equal(record.tool, "tool");
+    assert.deepEqual(record.args, {});
+});

package/dist/test/data_types.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Regression tests for the zod -> Valibot conversion. Not exhaustive schema
+ * tests — these guard the three specific things that conversion could get
+ * wrong: the three-state writes/tools semantics that hard rule 9 depends on,
+ * default-value reference freshness (verified NOT to be a live bug in
+ * valibot 1.4.2 — see the comment below — kept as a tripwire against a
+ * future version regressing it), and toJsonSchema staying convertible now
+ * that it backs the sf_report tool wiring landing in the Flue phase.
+ */
+export {};

package/dist/test/data_types.test.js

@@ -0,0 +1,49 @@
+/**
+ * Regression tests for the zod -> Valibot conversion. Not exhaustive schema
+ * tests — these guard the three specific things that conversion could get
+ * wrong: the three-state writes/tools semantics that hard rule 9 depends on,
+ * default-value reference freshness (verified NOT to be a live bug in
+ * valibot 1.4.2 — see the comment below — kept as a tripwire against a
+ * future version regressing it), and toJsonSchema staying convertible now
+ * that it backs the sf_report tool wiring landing in the Flue phase.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import * as v from "valibot";
+import { toJsonSchema } from "@valibot/to-json-schema";
+import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, GenericOutput, PhaseParamsSchema, PlanOutput, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
+test("writes: three-state semantics — absent, null, and [] all mean something different", () => {
+    const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
+    const unrestricted = v.parse(AgentConfigSchema, base);
+    assert.equal(unrestricted.writes, undefined, "key absent -> undefined (unrestricted)");
+    const explicitNull = v.parse(AgentConfigSchema, { ...base, writes: null });
+    assert.equal(explicitNull.writes, null, "explicit null -> null (also unrestricted)");
+    const readOnly = v.parse(AgentConfigSchema, { ...base, writes: [] });
+    assert.deepEqual(readOnly.writes, [], "explicit [] -> read-only, must stay an empty array, not undefined/null");
+    const allowlisted = v.parse(AgentConfigSchema, { ...base, writes: ["specs/"] });
+    assert.deepEqual(allowlisted.writes, ["specs/"]);
+    assert.throws(() => v.parse(AgentConfigSchema, { ...base, writes: "specs/" }), "a bare string must not be silently accepted as an allowlist");
+});
+test("array defaults never alias across parses (tripwire, not a fix — see module comment)", () => {
+    const first = v.parse(BuildOutput.schema, { status: "success" });
+    const second = v.parse(BuildOutput.schema, { status: "success" });
+    first.artifacts.push("should-not-leak");
+    first.changed_files.push("should-not-leak");
+    assert.deepEqual(second.artifacts, [], "a later parse must not see an earlier parse's push");
+    assert.deepEqual(second.changed_files, []);
+    assert.notEqual(first.artifacts, second.artifacts, "distinct array references");
+});
+test("PhaseParamsSchema rejects a blank description and an echo of the name, with the exact messages", () => {
+    assert.throws(() => makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "   " }), /description is required/);
+    assert.throws(() => makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "Commit Plan" }), /only restates the phase name/);
+    const ok = makePhaseParams({ name: "commit_plan", kind: "code", owner: "git", description: "  Commit the plan file to the repo  " });
+    assert.equal(ok.description, "Commit the plan file to the repo", "whitespace is collapsed, not just trimmed");
+});
+test("every envelope type still converts to JSON Schema (the sf_report tool wiring depends on this)", () => {
+    for (const envelope of [GenericOutput, PlanOutput, BuildOutput, ScoutOutput, ReviewOutput, DocumentOutput, ChangesOutput, VerifyOutput]) {
+        assert.doesNotThrow(() => toJsonSchema(envelope.schema), `${envelope.name} must stay convertible — no rawTransform allowed on an envelope schema`);
+    }
+});
+test("PhaseParamsSchema itself (the one schema WITH a rawTransform) correctly refuses JSON Schema conversion", () => {
+    assert.throws(() => toJsonSchema(PhaseParamsSchema), /raw_transform/);
+});

package/dist/test/ui_server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/ui_server.test.js

@@ -0,0 +1,119 @@
+/**
+ * Route-parity regression test for the Bun.serve -> Hono port. Builds a real
+ * spf.db (via the tracer, not a fixture file) and drives runUi() with real
+ * HTTP requests — the same shape as the manual verification this port was
+ * checked against, kept as a regression guard rather than a one-off.
+ */
+import { test, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { Tracer } from "../core/tracer.js";
+import { makeEventRecord } from "../core/data_types.js";
+import { runUi } from "../ui/server/serve.js";
+let dir;
+let handle;
+const ADW_ID = "t1";
+before(async () => {
+    dir = mkdtempSync(join(tmpdir(), "spf-ui-test-"));
+    execFileSync("git", ["init", "-q"], { cwd: dir });
+    // -c user.*, not a global git config: this must pass in a fresh CI runner
+    // with no git identity configured at all, not just on a dev machine that
+    // already has one.
+    execFileSync("git", ["-c", "user.email=test@example.com", "-c", "user.name=spf tests", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
+    const dbPath = join(dir, "spf.db");
+    const tracer = new Tracer(dbPath, join(dir, "sessions", ADW_ID, "events.jsonl"));
+    tracer.sessionStart(ADW_ID, "tester", "adw_quality");
+    const phase = {
+        phase_id: `${ADW_ID}_01_request`,
+        adw_id: ADW_ID,
+        seq: 1,
+        params: { name: "request", kind: "engineer", owner: "tester", description: "seed phase", retries: 0 },
+        status: "success",
+        attempt: 0,
+        error: null,
+        started_at: null,
+        ended_at: null,
+    };
+    tracer.phaseUpsert(phase);
+    tracer.event(makeEventRecord({ adw_id: ADW_ID, phase_id: phase.phase_id, type: "log", name: "request", payload: { input: "seed" } }));
+    tracer.sessionFinish(ADW_ID, true);
+    // dist/test/ui_server.test.js -> dist -> package root -> web
+    const webDir = join(import.meta.dirname, "..", "..", "web");
+    handle = await runUi({ dbPath, webDir, port: 0, open: false });
+});
+after(async () => {
+    await handle.close();
+    rmSync(dir, { recursive: true, force: true });
+});
+async function get(path, init) {
+    const res = await fetch(handle.url + path, init);
+    const contentType = res.headers.get("content-type") ?? "";
+    const body = contentType.includes("json") ? await res.json() : await res.text();
+    return { status: res.status, body, contentType };
+}
+test("GET /api/health reports the real db path and session count", async () => {
+    const { status, body } = await get("/api/health");
+    assert.equal(status, 200);
+    assert.equal(body.ok, true);
+    assert.equal(body.journal_mode, "wal");
+    assert.equal(body.sessions, 1);
+});
+test("GET /api/sessions lists the seeded session", async () => {
+    const { status, body } = await get("/api/sessions");
+    assert.equal(status, 200);
+    assert.equal(body.length, 1);
+    assert.equal(body[0].adw_id, ADW_ID);
+});
+test("GET /api/sessions/:adw_id returns detail; unknown id 404s as JSON", async () => {
+    const ok = await get(`/api/sessions/${ADW_ID}`);
+    assert.equal(ok.status, 200);
+    assert.equal(ok.body.session.adw_id, ADW_ID);
+    const missing = await get("/api/sessions/does-not-exist");
+    assert.equal(missing.status, 404);
+    assert.match(missing.body.error, /no session/);
+});
+test("POST /api/sessions/:adw_id/archive persists; GET on the same route 404s instead of falling through to the SPA", async () => {
+    const post = await get(`/api/sessions/${ADW_ID}/archive`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ archived: true }),
+    });
+    assert.equal(post.status, 200);
+    assert.equal(post.body.archived, true);
+    const afterArchive = await get("/api/sessions");
+    assert.equal(afterArchive.body.length, 0, "archived sessions are excluded from the default list");
+    const getOnArchive = await get(`/api/sessions/${ADW_ID}/archive`);
+    assert.equal(getOnArchive.status, 404, "the deliberate behavior change from the Bun version: no silent SPA fallback here");
+    assert.match(getOnArchive.contentType, /json/);
+});
+test("unsafe path segments (dot-segments, encoded percent) are rejected, never resolved onto disk", async () => {
+    const encodedDotDot = await get(`/api/sessions/${ADW_ID}/agents/%2e%2e/prompts`);
+    assert.equal(encodedDotDot.status, 404); // Hono's router normalizes this away before it reaches the handler
+    const encodedPercent = await get(`/api/sessions/%2520/agents/x/prompts`);
+    assert.equal(encodedPercent.status, 400);
+    assert.match(encodedPercent.body.error, /invalid/);
+});
+test("unknown /api/* route 404s as JSON, not the SPA", async () => {
+    const { status, contentType } = await get("/api/nope");
+    assert.equal(status, 404);
+    assert.match(contentType, /json/);
+});
+test("a non-API route serves the SPA's index.html (client-side routing fallback)", async () => {
+    const { status, contentType, body } = await get("/some/client/route");
+    assert.equal(status, 200);
+    assert.match(contentType, /html/);
+    assert.match(body, /<div id="app">/);
+});
+test("static assets are served with immutable caching; index.html is not", async () => {
+    const index = await fetch(handle.url + "/");
+    assert.equal(index.headers.get("cache-control"), "no-store");
+    const html = await index.text();
+    const assetMatch = html.match(/src="([^"]+\.js)"/);
+    assert.ok(assetMatch, "index.html must reference a built JS asset");
+    const asset = await fetch(handle.url + "/" + assetMatch[1].replace(/^\.\//, ""));
+    assert.equal(asset.status, 200);
+    assert.match(asset.headers.get("cache-control") ?? "", /immutable/);
+});

package/dist/test/watch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/watch.test.js

@@ -0,0 +1,227 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcileOrphans } from "../core/watch.js";
+/** In-memory fake — exactly the seam `provider.ts` exists for. */
+class FakeProvider {
+    entries = new Map();
+    prs = new Map();
+    ensureLabelsCalls = 0;
+    transitions = [];
+    openedPrs = [];
+    claimCalls = [];
+    nextPrNumber = 1000;
+    addIssue(number, title, state = "ready", marker = null) {
+        this.entries.set(number, { issue: { number, title, body: "", labels: [`spf:${state}`] }, state, marker });
+    }
+    async ensureLabels() {
+        this.ensureLabelsCalls++;
+        return { created: [], updated: [], unchanged: [] };
+    }
+    async listEligible() {
+        return [...this.entries.values()].filter((e) => e.state === "ready").map((e) => e.issue);
+    }
+    async listInState(state) {
+        return [...this.entries.values()].filter((e) => e.state === state).map((e) => e.issue);
+    }
+    async claim(issue) {
+        this.claimCalls.push(issue.number);
+        const entry = this.entries.get(issue.number);
+        if (entry.state !== "ready")
+            return false;
+        entry.state = "working";
+        return true;
+    }
+    async transition(issue, to, detail) {
+        this.entries.get(issue.number).state = to;
+        this.transitions.push({ number: issue.number, to, detail });
+    }
+    async comment() { }
+    async openPr(issue, opts) {
+        const number = this.nextPrNumber++;
+        this.openedPrs.push({ issueNumber: issue.number, branch: opts.branch });
+        this.prs.set(number, { merged: false, state: "open", ciStatus: "pending" });
+        return { number, branch: opts.branch, url: `https://example.invalid/pr/${number}` };
+    }
+    async prStatus(pr) {
+        return this.prs.get(pr.number) ?? { merged: false, state: "open", ciStatus: "pending" };
+    }
+    async readMarker(issue) {
+        return this.entries.get(issue.number)?.marker ?? null;
+    }
+    async writeMarker(issue, marker) {
+        this.entries.get(issue.number).marker = marker;
+    }
+}
+function fakeGit(overrides = {}) {
+    return {
+        currentBranch: () => "main",
+        createBranch: (n) => n,
+        isRepo: () => true,
+        commitAll: () => "abc123",
+        changedFiles: () => [],
+        refExists: () => true,
+        rev: () => "abc123",
+        shortSha: () => "abc123",
+        mergeBase: () => "abc123",
+        isDirty: () => false,
+        untrackedFiles: () => [],
+        diffFiles: () => [],
+        diffStat: () => "",
+        diffCounts: () => [0, 0],
+        diffText: () => "",
+        fetch: () => { },
+        worktreeAdd: () => { },
+        worktreeRemove: () => { },
+        deleteLocalBranch: () => { },
+        push: () => { },
+        ...overrides,
+    };
+}
+function makeDeps(provider, overrides = {}) {
+    return {
+        provider,
+        git: fakeGit(),
+        worktreeGit: () => fakeGit({ diffFiles: () => ["src/index.ts"] }), // a real commit landed, by default
+        labelPrefix: "spf",
+        chain: "plan-build-test",
+        baseBranch: "main",
+        concurrency: 2,
+        worktreesDir: "/tmp/spf-watch-test-worktrees",
+        dryRun: false,
+        runChain: async () => ({ accepted: true, adwId: "issue-1", detail: "" }),
+        log: () => { },
+        ...overrides,
+    };
+}
+async function waitUntil(predicate, timeoutMs = 2000) {
+    const start = Date.now();
+    while (!predicate()) {
+        if (Date.now() - start > timeoutMs)
+            throw new Error("waitUntil timed out");
+        await new Promise((r) => setTimeout(r, 5));
+    }
+}
+test("branchNameFor: sanitizes a title into a safe branch name", () => {
+    assert.equal(branchNameFor({ number: 42, title: "Add a /health endpoint!!", body: "", labels: [] }), "spf-watch/42-add-a-health-endpoint");
+    assert.equal(branchNameFor({ number: 7, title: "", body: "", labels: [] }), "spf-watch/7-issue");
+});
+test("claimNewWork: claims a ready issue, runs the chain, opens a PR, and moves to review", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(1, "Add a /health endpoint");
+    const state = createWatchState();
+    const deps = makeDeps(provider);
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.deepEqual(provider.claimCalls, [1]);
+    assert.equal(provider.openedPrs.length, 1);
+    assert.equal(provider.openedPrs[0].issueNumber, 1);
+    assert.deepEqual(provider.transitions.map((t) => t.to), ["review"]);
+    assert.equal(provider.entries.get(1).marker?.pr, 1000);
+});
+test("claimNewWork: a rejected chain run blocks the issue with the failure detail", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(2, "Flaky feature");
+    const state = createWatchState();
+    const deps = makeDeps(provider, {
+        runChain: async () => ({ accepted: false, adwId: "issue-2", detail: "build-test failed at phase build" }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.deepEqual(provider.transitions, [{ number: 2, to: "blocked", detail: "build-test failed at phase build" }]);
+    assert.equal(provider.openedPrs.length, 0);
+});
+test("claimNewWork: an accepted run with nothing committed also blocks, without opening a PR", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(3, "No-op request");
+    const state = createWatchState();
+    const deps = makeDeps(provider, { worktreeGit: () => fakeGit({ diffFiles: () => [] }) });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.equal(provider.transitions[0]?.to, "blocked");
+    assert.match(provider.transitions[0]?.detail ?? "", /no committed changes/);
+    assert.equal(provider.openedPrs.length, 0);
+});
+test("claimNewWork: never claims more than the concurrency budget in one tick", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(10, "one");
+    provider.addIssue(11, "two");
+    provider.addIssue(12, "three");
+    const state = createWatchState();
+    // A runChain that never resolves keeps every claimed issue "inflight" for this assertion.
+    const deps = makeDeps(provider, { concurrency: 2, runChain: () => new Promise(() => { }) });
+    await claimNewWork(deps, state);
+    assert.equal(state.inflight.size, 2);
+    assert.equal(provider.claimCalls.length, 2);
+});
+test("claimNewWork: dry-run claims nothing and calls neither claim() nor runChain", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(20, "dry run me");
+    const state = createWatchState();
+    let runChainCalled = false;
+    const deps = makeDeps(provider, {
+        dryRun: true,
+        runChain: async () => {
+            runChainCalled = true;
+            return { accepted: true, adwId: "x", detail: "" };
+        },
+    });
+    await claimNewWork(deps, state);
+    assert.equal(provider.claimCalls.length, 0);
+    assert.equal(runChainCalled, false);
+    assert.equal(provider.entries.get(20).state, "ready");
+});
+test("reconcileOrphans: a working issue with an open PR in its marker resumes as review", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(30, "orphaned mid-review", "working", { pr: 500, branch: "spf-watch/30-x" });
+    provider.prs.set(500, { merged: false, state: "open", ciStatus: "pending" });
+    const state = createWatchState();
+    await reconcileOrphans(makeDeps(provider), state);
+    assert.deepEqual(provider.transitions, [{ number: 30, to: "review", detail: undefined }]);
+});
+test("reconcileOrphans: a working issue with no marker retries up to the cap, then blocks", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(31, "orphaned, no marker", "working", null);
+    const state = createWatchState();
+    const deps = makeDeps(provider);
+    await reconcileOrphans(deps, state); // attempt 1 -> ready
+    assert.equal(provider.entries.get(31).state, "ready");
+    assert.equal(provider.entries.get(31).marker?.attempt, 1);
+    provider.entries.get(31).state = "working"; // simulate it getting re-claimed and orphaned again
+    await reconcileOrphans(deps, state); // attempt 2 -> ready
+    assert.equal(provider.entries.get(31).state, "ready");
+    provider.entries.get(31).state = "working";
+    await reconcileOrphans(deps, state); // attempt 3 exceeds MAX_ORPHAN_ATTEMPTS (2) -> blocked
+    assert.equal(provider.entries.get(31).state, "blocked");
+    assert.match(provider.transitions.at(-1)?.detail ?? "", /Gave up after 2 orphaned attempts/);
+});
+test("reconcileOrphans: skips issues this process is already tracking as in-flight", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(32, "actually still running", "working", null);
+    const state = createWatchState();
+    state.inflight.add(32);
+    await reconcileOrphans(makeDeps(provider), state);
+    assert.equal(provider.transitions.length, 0, "an in-flight issue must not be treated as orphaned");
+});
+test("finishReviews: a merged PR moves the issue to done", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(40, "shipped", "review", { pr: 600, branch: "spf-watch/40-x" });
+    provider.prs.set(600, { merged: true, state: "closed", ciStatus: "success" });
+    await finishReviews(makeDeps(provider));
+    assert.deepEqual(provider.transitions, [{ number: 40, to: "done", detail: undefined }]);
+});
+test("finishReviews: a closed-without-merging PR blocks the issue", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(41, "rejected", "review", { pr: 601, branch: "spf-watch/41-x" });
+    provider.prs.set(601, { merged: false, state: "closed", ciStatus: "failure" });
+    await finishReviews(makeDeps(provider));
+    assert.equal(provider.transitions[0]?.to, "blocked");
+    assert.match(provider.transitions[0]?.detail ?? "", /closed without merging/);
+});
+test("finishReviews: a still-open PR leaves the issue in review", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue(42, "still cooking", "review", { pr: 602, branch: "spf-watch/42-x" });
+    provider.prs.set(602, { merged: false, state: "open", ciStatus: "pending" });
+    await finishReviews(makeDeps(provider));
+    assert.equal(provider.transitions.length, 0);
+    assert.equal(provider.entries.get(42).state, "review");
+});

package/dist/ui/server/app.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+import { SfDb } from "./db.ts";
+export declare function createApp(db: SfDb, webDir: string): Hono;