agent-dealer 0.2.0 → 1.0.0

package/bundle/server/dist/coordinator/session-lifecycle.integration.test.js

@@ -0,0 +1,127 @@
+// packages/server/src/coordinator/session-lifecycle.integration.test.ts
+//
+// The rest of this package's coordinator tests use fakeDeps() for the git-worktree
+// boundary (see session-lifecycle.test.ts, dispatcher.test.ts) — good for the DI seam,
+// but never proves the real adapter (packages/server/src/adapters/git-worktree.ts)
+// actually round-trips with the coordinator. This file exercises the REAL worktree
+// adapter (addWorktree/removeWorktree/isWorktreeClean/mergeBase) against a real temp
+// git repo. github + spawn stay faked: they need network / a real CLI the test
+// environment may not have.
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const run = promisify(execFile);
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-lifecycle-integration-"));
+const { migrate } = await import("../db/index.js");
+const { BUILTIN_AGENT_CLAUDE_ID, BUILTIN_AGENT_CURSOR_ID } = await import("@agent-dealer/shared");
+const { createIssue, getIssue } = await import("../repository/issues.js");
+const { listWorkerSessionsForIssue } = await import("../repository/worker-sessions.js");
+const { listOpenHumanActions } = await import("../repository/human-actions.js");
+const { startIssueWorkflow, advanceIssue } = await import("./session-lifecycle.js");
+const worktreeAdapter = await import("../adapters/git-worktree.js");
+before(() => {
+    migrate();
+});
+async function git(cwd, args) {
+    const { stdout } = await run("git", args, { cwd });
+    return stdout.trim();
+}
+async function initRepo() {
+    const repo = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-integration-repo-"));
+    await git(repo, ["init", "-b", "main"]);
+    await git(repo, ["config", "user.email", "test@example.com"]);
+    await git(repo, ["config", "user.name", "Test"]);
+    fs.writeFileSync(path.join(repo, "README.md"), "hello\n");
+    await git(repo, ["add", "README.md"]);
+    await git(repo, ["commit", "-m", "initial"]);
+    return repo;
+}
+function seedIssue(repo) {
+    return createIssue({
+        title: "Integration issue",
+        description: "test issue",
+        acceptanceCriteria: "works",
+        repo,
+        baseBranch: "main",
+        developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+        reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+        maxReviewRounds: 3,
+        source: "manual",
+    });
+}
+test("a real git worktree carries a developer commit through to review under the real adapter", async () => {
+    const repo = await initRepo();
+    const issue = seedIssue(repo);
+    const branch = `issue-${issue.id}`;
+    // Filled in once the fake "developer" has actually committed inside the real worktree.
+    let developerHeadSha = "";
+    const deps = {
+        worktree: {
+            addWorktree: worktreeAdapter.addWorktree,
+            removeWorktree: worktreeAdapter.removeWorktree,
+            isWorktreeClean: worktreeAdapter.isWorktreeClean,
+            mergeBase: worktreeAdapter.mergeBase,
+        },
+        github: {
+            viewPr: async () => ({
+                number: 1,
+                url: "https://github.com/x/y/pull/1",
+                headRefOid: developerHeadSha,
+                baseRefName: "main",
+                headRefName: branch,
+                reviews: [],
+            }),
+            publishReview: async () => ({ ok: true, event: "APPROVE" }),
+        },
+        spawnDeveloper: async (session) => {
+            const worktreePath = session.worktreePath;
+            // Prove this is a REAL git worktree: write a file and commit, on disk.
+            fs.writeFileSync(path.join(worktreePath, "feature.txt"), "real work\n");
+            await git(worktreePath, ["add", "feature.txt"]);
+            await git(worktreePath, ["commit", "-m", "add feature"]);
+            developerHeadSha = await git(worktreePath, ["rev-parse", "HEAD"]);
+            return { exitCode: 0, transcript: "done", logPath: "/tmp/log" };
+        },
+        spawnReviewer: async () => ({
+            exitCode: 0,
+            transcript: "```json\n" +
+                JSON.stringify({
+                    verdict: "approved",
+                    baseSha: (await git(repo, ["rev-parse", "HEAD"])),
+                    headSha: developerHeadSha,
+                    acceptanceCriteriaAssessment: "met",
+                    evidenceAssessment: "ok",
+                    findings: [],
+                    risks: [],
+                }) +
+                "\n```",
+            logPath: "/tmp/log",
+        }),
+    };
+    await startIssueWorkflow(issue.id, deps);
+    await advanceIssue(issue.id, deps); // developer: real worktree add -> real commit -> real merge-base
+    const afterDev = listWorkerSessionsForIssue(issue.id);
+    assert.equal(afterDev.length, 2);
+    assert.equal(afterDev[0].status, "done");
+    assert.equal(afterDev[1].role, "reviewer");
+    assert.equal(afterDev[1].inputSha, developerHeadSha);
+    assert.ok(developerHeadSha, "developer session must have produced a real commit sha");
+    const afterDevIssue = getIssue(issue.id);
+    assert.equal(afterDevIssue?.status, "reviewing");
+    assert.equal(afterDevIssue?.headSha, developerHeadSha);
+    // The developer's worktree must have been cleaned up by the real adapter, but the
+    // branch it created must survive in the bare repo for the reviewer worktree to check out.
+    const branches = await git(repo, ["branch", "--list", branch]);
+    assert.ok(branches.includes(branch));
+    await advanceIssue(issue.id, deps); // reviewer: real detached worktree checkout at the developer's real commit
+    const afterReview = listWorkerSessionsForIssue(issue.id);
+    assert.equal(afterReview.length, 2);
+    assert.equal(afterReview[1].status, "done");
+    assert.equal(getIssue(issue.id)?.status, "final_review");
+    assert.ok(listOpenHumanActions().some((a) => a.issueId === issue.id && a.actionType === "final_review"));
+    fs.rmSync(repo, { recursive: true, force: true });
+});

package/bundle/server/dist/coordinator/session-lifecycle.js

@@ -0,0 +1,280 @@
+// packages/server/src/coordinator/session-lifecycle.ts
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { v4 as uuid } from "uuid";
+import { getIssue, transitionIssue, incrementIssueRound } from "../repository/issues.js";
+import { createWorkerSession, claimQueuedSession, completeSession, listWorkerSessionsForIssue, setSessionWorktreePath, } from "../repository/worker-sessions.js";
+import { startWorkflowInstance, appendWorkflowEvent } from "../repository/workflow-events.js";
+import { createHumanAction } from "../repository/human-actions.js";
+import { reconcileFinding, listFindingsForIssue } from "../repository/findings.js";
+import { getAgent } from "../repository/agents.js";
+import { addWorktree, removeWorktree, isWorktreeClean, mergeBase } from "../adapters/git-worktree.js";
+import { viewPr, publishReview } from "../adapters/github.js";
+import { spawnDeveloperSession, spawnReviewerSession } from "./spawn.js";
+import { buildDeveloperPrompt, buildReviewerPrompt } from "./prompts.js";
+import { parseReviewerResult } from "./reviewer-result.js";
+import { routeDeveloperOutcome, routeReviewerOutcome } from "./routing.js";
+export const defaultCoordinatorDeps = {
+    worktree: { addWorktree, removeWorktree, isWorktreeClean, mergeBase },
+    github: { viewPr, publishReview },
+    spawnDeveloper: spawnDeveloperSession,
+    spawnReviewer: spawnReviewerSession,
+};
+function worktreePathFor(issue, role, round) {
+    return path.join(os.tmpdir(), "agent-dealer-worktrees", issue.id, `${role}-r${round}`);
+}
+/**
+ * Resolves the selected agent profile's effective runtime/model/deck at session-creation
+ * time so the recorded worker_session snapshots it (later profile edits don't rewrite
+ * history). Falls back to claude_code only when no profile is set at all. Exported so
+ * other call sites that create worker_sessions (e.g. the human-action resolve route's
+ * repair-round restart) resolve the real profile instead of re-hardcoding a runtime.
+ */
+export function resolveProfile(agentId) {
+    const agent = agentId ? getAgent(agentId) : null;
+    return {
+        runtime: agent?.runtime ?? "claude_code",
+        model: agent?.defaultModel ?? agent?.defaultExecuteModel ?? null,
+        deckId: agent?.deckId ?? null,
+        playbookId: agent?.playbookId ?? null,
+    };
+}
+export async function startIssueWorkflow(issueId, _deps = defaultCoordinatorDeps) {
+    const issue = getIssue(issueId);
+    if (!issue)
+        throw new Error(`Issue not found: ${issueId}`);
+    const instance = startWorkflowInstance(issueId, "dev_reviewer_v1");
+    appendWorkflowEvent({ issueId, workflowInstanceId: instance.id, type: "workflow.started", actorType: "system", stage: "ready" });
+    // Deciding and recording the branch name here (not just on a successful handoff) means
+    // every developer round — including a round 1 that fails after creating the branch —
+    // agrees on the same name, so repair rounds always check out the right ref.
+    const branch = `issue-${issue.id}`;
+    const updated = transitionIssue(issueId, "developing", {
+        currentOwner: "developer",
+        currentIntent: "Developer implementing round 1",
+        branch,
+    });
+    const profile = resolveProfile(issue.developerAgentId);
+    const session = createWorkerSession({
+        issueId,
+        role: "developer",
+        round: 1,
+        agentId: issue.developerAgentId,
+        runtime: profile.runtime,
+        model: profile.model,
+    });
+    appendWorkflowEvent({
+        issueId,
+        workflowInstanceId: instance.id,
+        workerSessionId: session.id,
+        type: "worker.started",
+        actorType: "system",
+        stage: updated.status,
+        round: 1,
+    });
+}
+/** Claims and runs exactly one queued session for this issue to completion, then routes the outcome. */
+export async function advanceIssue(issueId, deps = defaultCoordinatorDeps) {
+    const issue = getIssue(issueId);
+    if (!issue)
+        throw new Error(`Issue not found: ${issueId}`);
+    const queued = listWorkerSessionsForIssue(issueId).filter((s) => s.status === "queued");
+    const session = queued[queued.length - 1];
+    if (!session)
+        return;
+    const claimed = claimQueuedSession(session.id);
+    if (!claimed)
+        return; // another dispatcher already took it
+    const worktreePath = worktreePathFor(issue, claimed.role === "reviewer" ? "reviewer" : "developer", claimed.round);
+    if (claimed.role === "developer") {
+        await runDeveloperSession(issue, claimed, worktreePath, deps);
+    }
+    else {
+        await runReviewerSession(issue, claimed, worktreePath, deps);
+    }
+}
+async function runDeveloperSession(issue, session, worktreePath, deps) {
+    const branch = issue.branch ?? `issue-${issue.id}`;
+    if (session.round === 1) {
+        await deps.worktree.addWorktree({ repo: issue.repo, path: worktreePath, ref: issue.baseBranch, newBranch: branch });
+    }
+    else {
+        // Repair round: the branch already exists from round 1 (git worktree add -b creates
+        // the branch in the repo, independent of that worktree's later removal) — check it
+        // out as-is so work continues from the prior head instead of restarting from base.
+        await deps.worktree.addWorktree({ repo: issue.repo, path: worktreePath, ref: branch });
+    }
+    const withPath = setSessionWorktreePath(session.id, worktreePath);
+    const priorFindings = listFindingsForIssue(issue.id).filter((f) => f.status === "open" || f.status === "recurring");
+    const profile = resolveProfile(issue.developerAgentId);
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot: { title: issue.title, description: issue.description ?? "", acceptanceCriteria: issue.acceptanceCriteria ?? "", repo: issue.repo, baseBranch: issue.baseBranch },
+        round: session.round,
+        findings: priorFindings.length ? priorFindings : undefined,
+        worktreePath,
+        deckId: profile.deckId,
+        playbookId: profile.playbookId,
+    });
+    let result;
+    try {
+        result = await deps.spawnDeveloper(withPath, prompt);
+    }
+    catch {
+        result = { exitCode: 1, transcript: "", logPath: "", timedOut: false };
+    }
+    const sessionStatus = result.exitCode === 0 && !result.timedOut ? "done" : "failed";
+    completeSession(session.id, { status: sessionStatus, exitCode: result.exitCode, logPath: result.logPath });
+    appendWorkflowEvent({ issueId: issue.id, workerSessionId: session.id, type: "worker.completed", actorType: "developer", stage: issue.status, round: session.round });
+    const outcome = await classifyDeveloperOutcome(issue, worktreePath, sessionStatus, deps);
+    const routed = routeDeveloperOutcome(outcome, { currentRound: issue.currentRound, maxReviewRounds: issue.maxReviewRounds });
+    if (outcome.kind === "clean_handoff") {
+        appendWorkflowEvent({ issueId: issue.id, workerSessionId: session.id, type: "pull_request.opened", actorType: "system", stage: issue.status, round: session.round, payload: { prNumber: outcome.prNumber, prUrl: outcome.prUrl, headSha: outcome.headSha } });
+    }
+    if (routed.next === "spawn_reviewer" && outcome.kind === "clean_handoff") {
+        transitionIssue(issue.id, "reviewing", {
+            currentOwner: "reviewer",
+            currentIntent: "Reviewer evaluating PR",
+            headSha: outcome.headSha,
+            baseSha: outcome.baseSha,
+            prNumber: outcome.prNumber,
+            prUrl: outcome.prUrl,
+        });
+        const reviewerProfile = resolveProfile(issue.reviewerAgentId);
+        createWorkerSession({ issueId: issue.id, role: "reviewer", round: session.round, agentId: issue.reviewerAgentId, runtime: reviewerProfile.runtime, model: reviewerProfile.model, inputSha: outcome.headSha });
+    }
+    else if (routed.next === "retry_developer") {
+        incrementIssueRound(issue.id);
+        const next = getIssue(issue.id);
+        const developerProfile = resolveProfile(issue.developerAgentId);
+        createWorkerSession({ issueId: issue.id, role: "developer", round: next.currentRound, agentId: issue.developerAgentId, runtime: developerProfile.runtime, model: developerProfile.model });
+    }
+    else if (routed.next === "human_action") {
+        transitionIssue(issue.id, "needs_human", { currentOwner: "human" });
+        createHumanAction({ issueId: issue.id, actionType: routed.actionType, reason: routed.reason, question: routed.reason });
+    }
+    if (outcome.kind !== "dirty_worktree") {
+        await deps.worktree.removeWorktree({ repo: issue.repo, path: worktreePath, force: false }).catch(() => undefined);
+    }
+}
+async function classifyDeveloperOutcome(issue, worktreePath, sessionStatus, deps) {
+    if (sessionStatus === "failed")
+        return { kind: "session_failed" };
+    const clean = await deps.worktree.isWorktreeClean(worktreePath);
+    if (!clean)
+        return { kind: "dirty_worktree" };
+    try {
+        const view = await deps.github.viewPr({ cwd: worktreePath });
+        const baseSha = await deps.worktree.mergeBase({ repo: worktreePath, base: view.baseRefName, head: view.headRefName });
+        return { kind: "clean_handoff", headSha: view.headRefOid, baseSha, prNumber: view.number, prUrl: view.url };
+    }
+    catch {
+        return { kind: "no_pr" };
+    }
+}
+async function runReviewerSession(issue, session, worktreePath, deps) {
+    await deps.worktree.addWorktree({ repo: issue.repo, path: worktreePath, ref: session.inputSha ?? issue.headSha ?? issue.baseBranch, detach: true });
+    const withPath = setSessionWorktreePath(session.id, worktreePath);
+    const reviewerProfile = resolveProfile(issue.reviewerAgentId);
+    const prompt = buildReviewerPrompt({
+        taskSnapshot: { title: issue.title, description: issue.description ?? "", acceptanceCriteria: issue.acceptanceCriteria ?? "", repo: issue.repo, baseBranch: issue.baseBranch },
+        baseSha: issue.baseSha ?? "",
+        headSha: session.inputSha ?? issue.headSha ?? "",
+        worktreePath,
+        deckId: reviewerProfile.deckId,
+        playbookId: reviewerProfile.playbookId,
+    });
+    let result;
+    try {
+        result = await deps.spawnReviewer(withPath, prompt);
+    }
+    catch {
+        result = { exitCode: 1, transcript: "", logPath: "", timedOut: false };
+    }
+    const sessionStatus = result.exitCode === 0 && !result.timedOut ? "done" : "failed";
+    completeSession(session.id, { status: sessionStatus, exitCode: result.exitCode, logPath: result.logPath });
+    appendWorkflowEvent({ issueId: issue.id, workerSessionId: session.id, type: "worker.completed", actorType: "reviewer", stage: issue.status, round: session.round });
+    const outcome = await classifyReviewerOutcome(issue, session, worktreePath, sessionStatus, result.transcript, deps);
+    const routed = routeReviewerOutcome(outcome, { currentRound: issue.currentRound, maxReviewRounds: issue.maxReviewRounds });
+    if (outcome.kind === "verdict") {
+        appendWorkflowEvent({ issueId: issue.id, workerSessionId: session.id, type: "review.submitted", actorType: "reviewer", stage: issue.status, round: session.round, payload: outcome.result });
+        for (const f of outcome.result.findings) {
+            reconcileFinding({ issueId: issue.id, fingerprint: f.fingerprint, severity: f.severity, title: f.title, rationale: f.rationale, file: f.file, line: f.line, round: session.round });
+        }
+    }
+    if (routed.next === "final_review") {
+        transitionIssue(issue.id, "final_review", { currentOwner: "human" });
+        createHumanAction({ issueId: issue.id, actionType: "final_review", reason: "Reviewer approved the PR", question: "Accept this work?" });
+    }
+    else if (routed.next === "retry_developer_with_findings") {
+        transitionIssue(issue.id, "repairing", { currentOwner: "developer" });
+        incrementIssueRound(issue.id);
+        const next = getIssue(issue.id);
+        const developerProfile = resolveProfile(issue.developerAgentId);
+        createWorkerSession({ issueId: issue.id, role: "developer", round: next.currentRound, agentId: issue.developerAgentId, runtime: developerProfile.runtime, model: developerProfile.model });
+        appendWorkflowEvent({ issueId: issue.id, type: "repair.started", actorType: "system", stage: next.status, round: next.currentRound });
+    }
+    else if (routed.next === "retry_reviewer_at_new_head") {
+        // Record the freshly verified head (never re-queue against the stale one) — the issue
+        // stays in "reviewing" (self-loop) throughout, it never actually left that stage.
+        transitionIssue(issue.id, "reviewing", { headSha: routed.headSha });
+        createWorkerSession({ issueId: issue.id, role: "reviewer", round: session.round, agentId: issue.reviewerAgentId, runtime: reviewerProfile.runtime, model: reviewerProfile.model, inputSha: routed.headSha });
+    }
+    else if (routed.next === "human_action") {
+        transitionIssue(issue.id, "needs_human", { currentOwner: "human" });
+        createHumanAction({ issueId: issue.id, actionType: routed.actionType, reason: routed.reason, question: routed.reason });
+    }
+    await deps.worktree.removeWorktree({ repo: issue.repo, path: worktreePath, force: true }).catch(() => undefined);
+}
+/** Renders the coordinator's own normalized review body — never the agent's raw transcript. */
+function renderReviewBody(result) {
+    const lines = [
+        `**Verdict:** ${result.verdict}`,
+        ``,
+        `**Acceptance criteria:** ${result.acceptanceCriteriaAssessment}`,
+        `**Evidence:** ${result.evidenceAssessment}`,
+    ];
+    if (result.findings.length) {
+        lines.push(``, `**Findings:**`);
+        for (const f of result.findings) {
+            const loc = f.file ? ` (${f.file}${f.line ? `:${f.line}` : ""})` : "";
+            lines.push(`- [${f.severity}] ${f.title}${loc}: ${f.rationale}`);
+        }
+    }
+    if (result.risks.length) {
+        lines.push(``, `**Risks:**`);
+        for (const r of result.risks)
+            lines.push(`- ${r}`);
+    }
+    if (result.productScopeQuestion) {
+        lines.push(``, `**Product scope question:** ${result.productScopeQuestion}`);
+    }
+    return lines.join("\n");
+}
+async function classifyReviewerOutcome(issue, session, worktreePath, sessionStatus, transcript, deps) {
+    if (sessionStatus === "failed")
+        return { kind: "session_failed" };
+    const view = await deps.github.viewPr({ cwd: worktreePath }).catch(() => null);
+    if (view && session.inputSha && view.headRefOid !== session.inputSha) {
+        return { kind: "stale", currentHeadSha: view.headRefOid };
+    }
+    const parsed = parseReviewerResult(transcript);
+    if (!parsed)
+        return { kind: "session_failed" };
+    // The coordinator is the only component that publishes — the reviewer has no git/GitHub
+    // write access (see args.ts), so this is the sole place a review is ever submitted.
+    if (issue.prNumber) {
+        const event = parsed.verdict === "approved" ? "APPROVE" : parsed.verdict === "changes_requested" ? "REQUEST_CHANGES" : "COMMENT";
+        const bodyFile = path.join(os.tmpdir(), `review-${uuid()}.md`);
+        fs.writeFileSync(bodyFile, renderReviewBody(parsed));
+        try {
+            const published = await deps.github.publishReview({ cwd: worktreePath, prNumber: issue.prNumber, event, bodyFilePath: bodyFile });
+            if (!published.ok)
+                return { kind: "publish_failed" };
+        }
+        finally {
+            fs.unlink(bodyFile, () => undefined);
+        }
+    }
+    return { kind: "verdict", result: parsed };
+}

package/bundle/server/dist/coordinator/session-lifecycle.test.js

@@ -0,0 +1,121 @@
+// packages/server/src/coordinator/session-lifecycle.test.ts
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-lifecycle-"));
+const { migrate } = await import("../db/index.js");
+const { BUILTIN_AGENT_CLAUDE_ID, BUILTIN_AGENT_CURSOR_ID } = await import("@agent-dealer/shared");
+const { createIssue, getIssue } = await import("../repository/issues.js");
+const { listWorkerSessionsForIssue } = await import("../repository/worker-sessions.js");
+const { listOpenHumanActions } = await import("../repository/human-actions.js");
+const { listWorkflowEventsForIssue } = await import("../repository/workflow-events.js");
+const { startIssueWorkflow, advanceIssue } = await import("./session-lifecycle.js");
+const { ReviewerResult } = await import("./reviewer-result.js");
+before(() => {
+    migrate();
+});
+function seedIssue(title) {
+    return createIssue({
+        title,
+        description: "test issue",
+        acceptanceCriteria: "works",
+        repo: "/tmp/fake-repo",
+        baseBranch: "main",
+        developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+        reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+        maxReviewRounds: 3,
+        source: "manual",
+    });
+}
+/** Fake deps: no real git/gh/spawn — deterministic canned responses per test. */
+function fakeDeps(overrides = {}) {
+    return {
+        worktree: {
+            addWorktree: overrides.addWorktree ?? (async () => { }),
+            removeWorktree: async () => { },
+            isWorktreeClean: overrides.isWorktreeClean ?? (async () => true),
+            mergeBase: overrides.mergeBase ?? (async () => "base-sha-1"),
+        },
+        github: {
+            viewPr: overrides.viewPr ??
+                (async () => ({ number: 1, url: "https://github.com/x/y/pull/1", headRefOid: "head-sha-1", baseRefName: "main", headRefName: "issue-branch", reviews: [] })),
+            publishReview: overrides.publishReview ?? (async () => ({ ok: true, event: "APPROVE" })),
+        },
+        spawnDeveloper: overrides.spawnDeveloper ?? (async () => ({ exitCode: 0, transcript: "done", logPath: "/tmp/log" })),
+        spawnReviewer: overrides.spawnReviewer ?? (async () => ({ exitCode: 0, transcript: "reviewed", logPath: "/tmp/log" })),
+    };
+}
+test("starting a workflow creates one instance and one queued developer session for round 1", async () => {
+    const issue = seedIssue("Start workflow");
+    await startIssueWorkflow(issue.id, fakeDeps());
+    const sessions = listWorkerSessionsForIssue(issue.id);
+    assert.equal(sessions.length, 1);
+    assert.equal(sessions[0].role, "developer");
+    assert.equal(sessions[0].round, 1);
+    assert.equal(getIssue(issue.id)?.status, "developing");
+});
+test("clean developer handoff advances to a queued reviewer session", async () => {
+    const issue = seedIssue("Clean handoff");
+    await startIssueWorkflow(issue.id, fakeDeps());
+    await advanceIssue(issue.id, fakeDeps());
+    const sessions = listWorkerSessionsForIssue(issue.id);
+    assert.equal(sessions.length, 2);
+    assert.equal(sessions[1].role, "reviewer");
+    assert.equal(sessions[1].inputSha, "head-sha-1");
+    assert.equal(getIssue(issue.id)?.status, "reviewing");
+    assert.equal(getIssue(issue.id)?.headSha, "head-sha-1");
+});
+test("approved review creates a final_review human action", async () => {
+    const issue = seedIssue("Approved review");
+    const approvedResult = { verdict: "approved", baseSha: "base-sha-1", headSha: "head-sha-1", acceptanceCriteriaAssessment: "met", evidenceAssessment: "ok", findings: [], risks: [] };
+    await startIssueWorkflow(issue.id, fakeDeps());
+    await advanceIssue(issue.id, fakeDeps()); // developer -> reviewer queued
+    await advanceIssue(issue.id, fakeDeps({
+        spawnReviewer: async () => ({ exitCode: 0, transcript: "```json\n" + JSON.stringify(approvedResult) + "\n```", logPath: "/tmp/log" }),
+    })); // reviewer runs -> approved
+    assert.equal(getIssue(issue.id)?.status, "final_review");
+    const actions = listOpenHumanActions();
+    assert.ok(actions.some((a) => a.issueId === issue.id && a.actionType === "final_review"));
+});
+test("changes_requested with rounds remaining queues a round-2 developer session with findings context", async () => {
+    const issue = seedIssue("Changes requested");
+    const crResult = {
+        verdict: "changes_requested",
+        baseSha: "base-sha-1",
+        headSha: "head-sha-1",
+        acceptanceCriteriaAssessment: "partial",
+        evidenceAssessment: "ok",
+        findings: [{ fingerprint: "fp1", severity: "blocking", title: "Missing check", rationale: "r" }],
+        risks: [],
+    };
+    await startIssueWorkflow(issue.id, fakeDeps());
+    await advanceIssue(issue.id, fakeDeps());
+    await advanceIssue(issue.id, fakeDeps({ spawnReviewer: async () => ({ exitCode: 0, transcript: "```json\n" + JSON.stringify(crResult) + "\n```", logPath: "/tmp/log" }) }));
+    const sessions = listWorkerSessionsForIssue(issue.id);
+    assert.equal(sessions.length, 3);
+    assert.equal(sessions[2].role, "developer");
+    assert.equal(sessions[2].round, 2);
+    assert.equal(getIssue(issue.id)?.status, "repairing");
+    assert.equal(getIssue(issue.id)?.currentRound, 2);
+});
+test("dirty worktree after developer session creates policy_escalation without consuming a round", async () => {
+    const issue = seedIssue("Dirty worktree");
+    await startIssueWorkflow(issue.id, fakeDeps());
+    await advanceIssue(issue.id, fakeDeps({ isWorktreeClean: async () => false }));
+    assert.equal(getIssue(issue.id)?.status, "needs_human");
+    assert.equal(getIssue(issue.id)?.currentRound, 1);
+    const actions = listOpenHumanActions();
+    assert.ok(actions.some((a) => a.issueId === issue.id && a.actionType === "policy_escalation"));
+});
+test("every completed round emits workflow_events with the issue and round attached", async () => {
+    const issue = seedIssue("Events issue");
+    await startIssueWorkflow(issue.id, fakeDeps());
+    await advanceIssue(issue.id, fakeDeps());
+    const events = listWorkflowEventsForIssue(issue.id);
+    assert.ok(events.some((e) => e.type === "workflow.started"));
+    assert.ok(events.some((e) => e.type === "worker.started"));
+    assert.ok(events.some((e) => e.type === "worker.completed"));
+    assert.ok(events.some((e) => e.type === "pull_request.opened"));
+});