agent-dealer 0.2.0 → 1.0.0

package/bundle/server/dist/adapters/github.js

@@ -0,0 +1,170 @@
+// packages/server/src/adapters/github.ts
+//
+// The coordinator's read/verify boundary onto GitHub via `gh`. Review bodies and PR
+// bodies are always written to a file and passed with `--body-file`, never shell-
+// interpolated (design §"Role permissions and GitHub access"). `publishReview` (NOT-62)
+// is called from the coordinator process itself, never the reviewer worker — the reviewer
+// profile's `publishReview` PermissionPolicy flag is always false; "the coordinator... is
+// the only component that publishes the review result" (design §"Role permissions").
+//
+// `GithubAdapter` is the injectable seam: production code uses `realGithubAdapter` (shells
+// out to the real `gh` CLI), while tests inject a fake — no real GitHub calls, matching the
+// "controlled GitHub adapter fixture" the NOT-61 acceptance criteria asks for.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+export function parsePrView(json) {
+    const raw = JSON.parse(json);
+    return {
+        number: raw.number,
+        url: raw.url,
+        baseRefName: raw.baseRefName,
+        headRefName: raw.headRefName,
+        headRefOid: raw.headRefOid,
+        isDraft: raw.isDraft,
+    };
+}
+export const PR_VIEW_FIELDS = "number,url,baseRefName,headRefName,headRefOid,isDraft";
+const FAILURE_STATES = new Set([
+    "failure",
+    "error",
+    "cancelled",
+    "timed_out",
+    "action_required",
+    "stale",
+    "startup_failure",
+]);
+const PENDING_STATES = new Set(["pending", "queued", "in_progress", "expected", "waiting", "requested"]);
+/** Every terminal-and-genuinely-ok conclusion `gh` can report — anything else fails closed. */
+const SUCCESS_STATES = new Set(["success", "neutral", "skipped"]);
+export function summarizeChecks(rollup) {
+    if (rollup.length === 0)
+        return "none";
+    const states = rollup.map((c) => (c.conclusion || c.state || c.status || "").toLowerCase());
+    if (states.some((s) => FAILURE_STATES.has(s)))
+        return "failure";
+    if (states.some((s) => PENDING_STATES.has(s)))
+        return "pending";
+    if (states.every((s) => SUCCESS_STATES.has(s)))
+        return "success";
+    // An unrecognized terminal conclusion is never treated as success — fail closed rather
+    // than silently waving a handoff through on a vocabulary this code doesn't know yet.
+    return "failure";
+}
+const NO_COMMITS_PATTERN = /no commits between/i;
+const defaultExec = (args, opts) => run("gh", args, opts);
+async function ghPrView(exec, cwd, fields, selector) {
+    const args = ["pr", "view", ...(selector != null ? [selector] : []), "--json", fields];
+    try {
+        const { stdout } = await exec(args, { cwd });
+        return JSON.parse(stdout);
+    }
+    catch (err) {
+        const message = err.stderr ?? err.message;
+        if (/no pull requests found|no default remote|could not find/i.test(message))
+            return null;
+        throw new Error(`gh pr view failed: ${message}`);
+    }
+}
+/** Real `gh` adapter, parameterized over the shell-out so tests can assert exact CLI args without a real `gh`. */
+export function createGithubAdapter(exec = defaultExec) {
+    return {
+        async viewPr({ cwd, number, branch }) {
+            const selector = number != null ? String(number) : branch;
+            const raw = await ghPrView(exec, cwd, PR_VIEW_FIELDS, selector);
+            return raw ? parsePrView(JSON.stringify(raw)) : null;
+        },
+        async createDraftPr({ cwd, base, head, title, bodyFilePath }) {
+            try {
+                const { stdout } = await exec(["pr", "create", "--draft", "--base", base, "--head", head, "--title", title, "--body-file", bodyFilePath], { cwd });
+                // Re-verified by the same explicit branch — a bare `gh pr view` right after this
+                // can hit the identical no-upstream failure `gh pr create` needed `--head` for.
+                const view = await ghPrView(exec, cwd, "number,url", head);
+                if (view)
+                    return { ok: true, number: Number(view.number), url: String(view.url) };
+                // Fallback: `gh pr create` prints the PR URL on its last stdout line.
+                const url = stdout.trim().split("\n").pop() ?? "";
+                const match = url.match(/\/pull\/(\d+)/);
+                return { ok: true, number: match ? Number(match[1]) : 0, url };
+            }
+            catch (err) {
+                const message = err.stderr ?? err.message;
+                return { ok: false, reason: message, noCommits: NO_COMMITS_PATTERN.test(message) };
+            }
+        },
+        async checksSnapshot({ cwd, number, branch }) {
+            const selector = number != null ? String(number) : branch;
+            const raw = await ghPrView(exec, cwd, "statusCheckRollup", selector);
+            const rollup = raw?.statusCheckRollup ?? [];
+            return summarizeChecks(rollup);
+        },
+        async publishReview({ cwd, number, event, bodyFilePath }) {
+            const result = await runReview(exec, cwd, number, event, bodyFilePath);
+            if (result.ok || event === "COMMENT" || !OWN_PR_REVIEW_PATTERN.test(result.reason)) {
+                return result.ok ? { ok: true, event, usedCommentFallback: false } : result;
+            }
+            const fallback = await runReview(exec, cwd, number, "COMMENT", bodyFilePath);
+            return fallback.ok
+                ? { ok: true, event: "COMMENT", usedCommentFallback: true }
+                : { ok: false, reason: `${event} rejected as self-review, and comment fallback also failed: ${fallback.reason}` };
+        },
+    };
+}
+export const realGithubAdapter = createGithubAdapter();
+const REVIEW_FLAG = {
+    APPROVE: "--approve",
+    REQUEST_CHANGES: "--request-changes",
+    COMMENT: "--comment",
+};
+/** GitHub's self-review rejection, worded per event ("approve" / "request changes"). */
+const OWN_PR_REVIEW_PATTERN = /own pull request/i;
+async function runReview(exec, cwd, number, event, bodyFilePath) {
+    try {
+        // The PR is targeted explicitly by number — the reviewer's worktree is a detached-HEAD
+        // checkout with no current branch for a bare `gh pr review` to resolve against.
+        await exec(["pr", "review", String(number), REVIEW_FLAG[event], "--body-file", bodyFilePath], { cwd });
+        return { ok: true };
+    }
+    catch (err) {
+        const message = err.stderr ?? err.message;
+        return { ok: false, reason: message };
+    }
+}
+/** Consecutive "none" reads required before concluding no checks are configured at all. */
+const NONE_STREAK_REQUIRED = 2;
+/**
+ * Bounded poll for CI checks to resolve — the confirmed scope call for NOT-61 (vs a
+ * one-shot read): "pending" keeps polling, "success"/"failure" return immediately once
+ * seen, and the poll gives up as "timeout" if nothing resolves in time or the lease is
+ * lost (`signal` aborts) mid-poll.
+ *
+ * "none" is NOT returned on the first read: GitHub can briefly report an empty
+ * statusCheckRollup before Actions has created its check runs, so a one-shot "empty
+ * rollup ⇒ no checks configured" read races a PR straight past CI — a review round caught
+ * this letting a real handoff through before its checks even appeared. `none` is only
+ * accepted once it has been read `NONE_STREAK_REQUIRED` times in a row (any "pending" in
+ * between resets the streak); if the deadline is hit before that streak completes, the
+ * poll fails closed as "timeout" rather than silently waving the handoff through.
+ */
+export async function pollPrChecks(adapter, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    let noneStreak = 0;
+    for (;;) {
+        if (opts.signal?.aborted)
+            return "timeout";
+        const snapshot = await adapter.checksSnapshot({ cwd: opts.cwd, number: opts.number, branch: opts.branch });
+        if (snapshot === "failure" || snapshot === "success")
+            return snapshot;
+        if (snapshot === "none") {
+            noneStreak++;
+            if (noneStreak >= NONE_STREAK_REQUIRED)
+                return "none";
+        }
+        else {
+            noneStreak = 0;
+        }
+        if (Date.now() >= deadline)
+            return "timeout";
+        await new Promise((resolve) => setTimeout(resolve, Math.min(opts.intervalMs, deadline - Date.now())));
+    }
+}

package/bundle/server/dist/adapters/github.test.js

@@ -0,0 +1,205 @@
+// packages/server/src/adapters/github.test.ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parsePrView, summarizeChecks, pollPrChecks, createGithubAdapter, PR_VIEW_FIELDS, } from "./github.js";
+test("parsePrView extracts the ground-truth handoff fields, including draft status", () => {
+    const view = parsePrView(JSON.stringify({
+        number: 7,
+        url: "https://github.com/o/r/pull/7",
+        baseRefName: "main",
+        headRefName: "issue-1",
+        headRefOid: "abc123",
+        isDraft: true,
+    }));
+    assert.deepEqual(view, {
+        number: 7,
+        url: "https://github.com/o/r/pull/7",
+        baseRefName: "main",
+        headRefName: "issue-1",
+        headRefOid: "abc123",
+        isDraft: true,
+    });
+});
+test("summarizeChecks: empty rollup is none, any failure wins over pending, pending beats success", () => {
+    assert.equal(summarizeChecks([]), "none");
+    assert.equal(summarizeChecks([{ state: "success" }, { state: "success" }]), "success");
+    assert.equal(summarizeChecks([{ state: "success" }, { status: "in_progress" }]), "pending");
+    assert.equal(summarizeChecks([{ conclusion: "failure" }, { status: "in_progress" }]), "failure");
+    assert.equal(summarizeChecks([{ conclusion: "cancelled" }]), "failure");
+});
+test("summarizeChecks accepts neutral/skipped as success but fails closed on an unrecognized conclusion", () => {
+    assert.equal(summarizeChecks([{ conclusion: "neutral" }, { conclusion: "skipped" }]), "success");
+    assert.equal(summarizeChecks([{ conclusion: "some_new_gh_conclusion_this_code_does_not_know" }]), "failure");
+});
+/** Records every `gh` invocation and returns responses off a queue — never calls real `gh`. */
+function queuedExec(responses) {
+    const calls = [];
+    const queue = [...responses];
+    const exec = async (args) => {
+        calls.push(args);
+        const next = queue.shift() ?? { stdout: "" };
+        if (next.error != null)
+            throw Object.assign(new Error(next.error), { stderr: next.error });
+        return { stdout: next.stdout ?? "" };
+    };
+    return { exec, calls };
+}
+test("viewPr looks up the PR explicitly by branch, never a bare `gh pr view`", async () => {
+    const { exec, calls } = queuedExec([
+        { stdout: JSON.stringify({ number: 5, url: "u", baseRefName: "main", headRefName: "issue-x", headRefOid: "abc", isDraft: true }) },
+    ]);
+    const view = await createGithubAdapter(exec).viewPr({ cwd: "/repo", branch: "issue-x" });
+    assert.deepEqual(calls[0], ["pr", "view", "issue-x", "--json", PR_VIEW_FIELDS]);
+    assert.equal(view?.number, 5);
+});
+test("viewPr prefers an explicit PR number over branch when both are given", async () => {
+    const { exec, calls } = queuedExec([
+        { stdout: JSON.stringify({ number: 5, url: "u", baseRefName: "main", headRefName: "issue-x", headRefOid: "abc", isDraft: true }) },
+    ]);
+    await createGithubAdapter(exec).viewPr({ cwd: "/repo", number: 5, branch: "issue-x" });
+    assert.deepEqual(calls[0], ["pr", "view", "5", "--json", PR_VIEW_FIELDS]);
+});
+test("createDraftPr passes --head explicitly and re-verifies by that same branch, not a bare `gh pr view`", async () => {
+    const { exec, calls } = queuedExec([
+        { stdout: "https://github.com/o/r/pull/9\n" },
+        { stdout: JSON.stringify({ number: 9, url: "https://github.com/o/r/pull/9" }) },
+    ]);
+    const result = await createGithubAdapter(exec).createDraftPr({
+        cwd: "/repo",
+        base: "main",
+        head: "issue-x",
+        title: "Add widget",
+        bodyFilePath: "/tmp/body.md",
+    });
+    assert.deepEqual(calls[0], ["pr", "create", "--draft", "--base", "main", "--head", "issue-x", "--title", "Add widget", "--body-file", "/tmp/body.md"]);
+    assert.deepEqual(calls[1], ["pr", "view", "issue-x", "--json", "number,url"]);
+    assert.deepEqual(result, { ok: true, number: 9, url: "https://github.com/o/r/pull/9" });
+});
+// NOT-82 dogfood repro: a real Dev-review run pushed its generated branch to origin, but
+// the local worktree had no configured upstream — `gh pr create` (bare, no `--head`)
+// refused with exactly this error, and the coordinator must never hit it.
+const NO_UPSTREAM_ERROR = "aborted: you must first push the current branch to a remote, or use the --head flag";
+test("createDraftPr: a branch pushed to origin with no local upstream still opens a draft PR when --head is explicit", async () => {
+    const exec = async (args) => {
+        if (args[0] === "pr" && args[1] === "create") {
+            if (!args.includes("--head"))
+                throw Object.assign(new Error(NO_UPSTREAM_ERROR), { stderr: NO_UPSTREAM_ERROR });
+            return { stdout: "https://github.com/o/r/pull/42\n" };
+        }
+        if (args[0] === "pr" && args[1] === "view" && args[2] === "issue-4e5eb611") {
+            return { stdout: JSON.stringify({ number: 42, url: "https://github.com/o/r/pull/42" }) };
+        }
+        throw new Error(`unexpected gh invocation: ${args.join(" ")}`);
+    };
+    const result = await createGithubAdapter(exec).createDraftPr({
+        cwd: "/repo",
+        base: "main",
+        head: "issue-4e5eb611",
+        title: "Complete CLI surface",
+        bodyFilePath: "/tmp/body.md",
+    });
+    assert.deepEqual(result, { ok: true, number: 42, url: "https://github.com/o/r/pull/42" });
+});
+test("viewPr: a retry can find the already-created PR by explicit branch even with no local upstream", async () => {
+    const exec = async (args) => {
+        // Bare `gh pr view` (no selector) can't resolve the current branch without upstream
+        // tracking — simulates the real failure mode this adapter must never hit.
+        if (args[1] === "view" && args[2] === "--json") {
+            throw Object.assign(new Error(), { stderr: 'no pull requests found for branch "HEAD"' });
+        }
+        return { stdout: JSON.stringify({ number: 42, url: "u", baseRefName: "main", headRefName: args[2], headRefOid: "abc", isDraft: true }) };
+    };
+    const view = await createGithubAdapter(exec).viewPr({ cwd: "/repo", branch: "issue-4e5eb611" });
+    assert.equal(view?.number, 42);
+});
+test("checksSnapshot looks up the PR's check rollup by explicit selector (number preferred), never a bare `gh pr view`", async () => {
+    const success = { stdout: JSON.stringify({ statusCheckRollup: [{ conclusion: "success" }] }) };
+    const byNumber = queuedExec([success]);
+    await createGithubAdapter(byNumber.exec).checksSnapshot({ cwd: "/repo", number: 42 });
+    assert.deepEqual(byNumber.calls[0], ["pr", "view", "42", "--json", "statusCheckRollup"]);
+    const byBranch = queuedExec([success]);
+    await createGithubAdapter(byBranch.exec).checksSnapshot({ cwd: "/repo", branch: "issue-x" });
+    assert.deepEqual(byBranch.calls[0], ["pr", "view", "issue-x", "--json", "statusCheckRollup"]);
+    const preferNumber = queuedExec([success]);
+    await createGithubAdapter(preferNumber.exec).checksSnapshot({ cwd: "/repo", number: 42, branch: "issue-x" });
+    assert.deepEqual(preferNumber.calls[0], ["pr", "view", "42", "--json", "statusCheckRollup"]);
+    // Bare, unselected lookup — the shape NOT-82's checks-poll stage must never fall back
+    // to now that pollPrChecks always forwards the identity-validated PR number.
+    const bare = queuedExec([success]);
+    await createGithubAdapter(bare.exec).checksSnapshot({ cwd: "/repo" });
+    assert.deepEqual(bare.calls[0], ["pr", "view", "--json", "statusCheckRollup"]);
+});
+test("pollPrChecks forwards its selector to checksSnapshot on every poll iteration", async () => {
+    const seen = [];
+    const adapter = {
+        viewPr: async () => null,
+        createDraftPr: async () => ({ ok: false, reason: "unused", noCommits: false }),
+        checksSnapshot: async ({ number, branch }) => {
+            seen.push({ number, branch });
+            return "success";
+        },
+        publishReview: async () => ({ ok: false, reason: "unused" }),
+    };
+    await pollPrChecks(adapter, { cwd: "/repo", timeoutMs: 1000, intervalMs: 5, number: 42 });
+    assert.deepEqual(seen, [{ number: 42, branch: undefined }]);
+});
+function fakeAdapter(sequence) {
+    const queue = [...sequence];
+    let last = "pending";
+    return {
+        viewPr: async () => null,
+        createDraftPr: async () => ({ ok: false, reason: "unused", noCommits: false }),
+        checksSnapshot: async () => {
+            if (queue.length)
+                last = queue.shift();
+            return last;
+        },
+        publishReview: async () => ({ ok: false, reason: "unused" }),
+    };
+}
+test("pollPrChecks returns immediately on success/failure without polling again", async () => {
+    assert.equal(await pollPrChecks(fakeAdapter(["success"]), { cwd: "/x", timeoutMs: 1000, intervalMs: 5 }), "success");
+    assert.equal(await pollPrChecks(fakeAdapter(["failure"]), { cwd: "/x", timeoutMs: 1000, intervalMs: 5 }), "failure");
+});
+test("pollPrChecks requires none to be read twice in a row before concluding no checks are configured", async () => {
+    // A single "none" read (Actions hasn't created its check runs yet) must NOT resolve.
+    const result = await pollPrChecks(fakeAdapter(["none", "pending", "none", "none"]), {
+        cwd: "/x",
+        timeoutMs: 1000,
+        intervalMs: 5,
+    });
+    assert.equal(result, "none");
+});
+test("pollPrChecks fails closed as timeout if the none-streak never completes in time", async () => {
+    // timeoutMs: 0 — the deadline is already passed after the very first read, before a
+    // second "none" can confirm the streak, so this must NOT resolve as "none".
+    const result = await pollPrChecks(fakeAdapter(["none"]), { cwd: "/x", timeoutMs: 0, intervalMs: 10 });
+    assert.equal(result, "timeout");
+});
+test("pollPrChecks keeps polling through pending until a terminal state resolves", async () => {
+    const result = await pollPrChecks(fakeAdapter(["pending", "pending", "success"]), {
+        cwd: "/x",
+        timeoutMs: 1000,
+        intervalMs: 5,
+    });
+    assert.equal(result, "success");
+});
+test("pollPrChecks gives up as timeout when checks stay pending past the deadline", async () => {
+    const result = await pollPrChecks(fakeAdapter(["pending", "pending", "pending", "pending"]), {
+        cwd: "/x",
+        timeoutMs: 20,
+        intervalMs: 10,
+    });
+    assert.equal(result, "timeout");
+});
+test("pollPrChecks bails out as timeout immediately when the lease signal is already aborted", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const result = await pollPrChecks(fakeAdapter(["pending"]), {
+        cwd: "/x",
+        timeoutMs: 1000,
+        intervalMs: 5,
+        signal: controller.signal,
+    });
+    assert.equal(result, "timeout");
+});

package/bundle/server/dist/adapters/linear-inbox.js

@@ -1,10 +1,11 @@
-import { findActiveByExternalId, listRunsReadyForPlanReview } from "../repository/runs.js";
-import { getLinearIntakeConfig } from "../repository/intake-settings.js";
+import { DEFAULT_LINEAR_STATE_FILTER, getLinearIntakeConfig } from "../repository/intake-settings.js";
+export { DEFAULT_LINEAR_STATE_FILTER };
 const LINEAR_API = "https://api.linear.app/graphql";
+const PAGE_SIZE = 50;
 function hasApiKey() {
     return Boolean(process.env.LINEAR_API_KEY);
 }
-async function linearQuery(query, variables) {
+async function linearQuery(query, variables, opts) {
     const key = process.env.LINEAR_API_KEY;
     if (!key)
         throw new Error("LINEAR_API_KEY not set");
@@ -12,6 +13,7 @@ async function linearQuery(query, variables) {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: key },
         body: JSON.stringify({ query, variables }),
+        ...(opts?.timeoutMs ? { signal: AbortSignal.timeout(opts.timeoutMs) } : {}),
     });
     if (!res.ok)
         throw new Error(`Linear HTTP ${res.status}: ${await res.text()}`);
@@ -48,20 +50,6 @@ export async function getLinearViewer() {
     const data = (await linearQuery(`query { viewer { id name email } }`));
     return data.viewer;
 }
-export async function testLinearConnection() {
-    if (!hasApiKey()) {
-        return { connected: false, error: "LINEAR_API_KEY not set" };
-    }
-    try {
-        const viewer = await getLinearViewer();
-        if (!viewer)
-            return { connected: false, error: "No viewer returned" };
-        return { connected: true, viewer };
-    }
-    catch (e) {
-        return { connected: false, error: String(e) };
-    }
-}
 export function buildIssueFilter(settings, viewerId) {
     const filter = {
         state: { name: { in: settings.stateFilter } },
@@ -74,8 +62,23 @@ export function buildIssueFilter(settings, viewerId) {
     }
     return filter;
 }
-function isPromoted(issueId) {
-    return findActiveByExternalId("linear", issueId) !== null;
+/**
+ * Normalize free-form kick input to a Linear issue id or identifier.
+ * Accepts `NOT-103`, a UUID, or a Linear issue URL.
+ */
+export function parseLinearIssueRef(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const fromUrl = trimmed.match(/linear\.app\/[^/]+\/issue\/([A-Za-z0-9_-]+)/i);
+    if (fromUrl?.[1])
+        return fromUrl[1];
+    if (/^[A-Z][A-Z0-9]*-\d+$/i.test(trimmed))
+        return trimmed.toUpperCase();
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(trimmed)) {
+        return trimmed.toLowerCase();
+    }
+    return null;
 }
 export async function listLinearCandidates() {
     if (!hasApiKey())
@@ -89,14 +92,21 @@ export async function listLinearCandidates() {
             return [];
     }
     const filter = buildIssueFilter(settings, viewerId);
-    const data = (await linearQuery(`query PollIssues($filter: IssueFilter) {
-      issues(filter: $filter, first: 30) {
-        nodes { ${ISSUE_FIELDS} }
-      }
-    }`, { filter }));
-    return data.issues.nodes
-        .filter((n) => !isPromoted(n.id))
-        .map(nodeToCandidate);
+    const nodes = [];
+    let after;
+    for (;;) {
+        const data = (await linearQuery(`query PollIssues($filter: IssueFilter, $after: String) {
+        issues(filter: $filter, first: ${PAGE_SIZE}, after: $after) {
+          nodes { ${ISSUE_FIELDS} }
+          pageInfo { hasNextPage endCursor }
+        }
+      }`, { filter, after: after ?? null }));
+        nodes.push(...data.issues.nodes);
+        if (!data.issues.pageInfo.hasNextPage || !data.issues.pageInfo.endCursor)
+            break;
+        after = data.issues.pageInfo.endCursor;
+    }
+    return nodes.map(nodeToCandidate);
 }
 export async function getLinearIssue(issueId) {
     const data = (await linearQuery(`query Issue($id: String!) {
@@ -106,7 +116,166 @@ export async function getLinearIssue(issueId) {
         return null;
     return nodeToCandidate(data.issue);
 }
-/** Runs with a plan ready for human review. */
-export function listAwaitingPlanReview() {
-    return listRunsReadyForPlanReview();
+const RELATION_PAGE_FIELDS = `
+  nodes { type issue { id identifier state { name type } } }
+  pageInfo { hasNextPage endCursor }
+`;
+/** A blocker Linear won't let us read (other team, no permission, deleted) — never satisfied. */
+const UNREADABLE_BLOCKER = {
+    id: "",
+    identifier: "an unreadable blocker",
+    stateName: "no access",
+    stateType: "unknown",
+};
+function relationToBlocker(node) {
+    if (!node.issue)
+        return UNREADABLE_BLOCKER;
+    return {
+        id: node.issue.id,
+        identifier: node.issue.identifier,
+        stateName: node.issue.state?.name ?? "unknown state",
+        stateType: node.issue.state?.type ?? "unknown",
+    };
+}
+/**
+ * NOT-104: for each requested Linear issue id, the issues that declare `blocks` on it.
+ *
+ * Linear models "Y blocks X" as a relation *from* Y, so X sees it in `inverseRelations`;
+ * X's own `relations` are its *downstream* issues and reading those would gate on the
+ * wrong side of every edge. Only `type === "blocks"` counts — `related`, `duplicate` and
+ * the parent/sub-issue hierarchy are deliberately ignored so an open parent epic does not
+ * block its own children.
+ *
+ * `includeArchived` is on because a queued dealer issue whose Linear ticket was archived
+ * must still resolve; archived blockers are judged by their state type, not the flag.
+ *
+ * Every request covers the whole batch — per-entry queries would make a 10-entry queue at a
+ * 60s TTL cost ~600 Linear requests/hour. Ids Linear does not return are simply absent from
+ * the map; the caller treats that as "unknown", never as "no blockers". An issue with more
+ * relations than fit in one page is *paged through* rather than dropped: `related` and
+ * `duplicate` links share that connection, so a well-linked ticket would otherwise park for
+ * good on relations that were never meant to gate it. Those nested pages are walked in
+ * rounds, one request per round across every issue still paging, so relation volume costs
+ * extra requests only in depth (rare) and never in queue width.
+ */
+export async function fetchLinearBlockers(issueIds, opts = {}) {
+    const out = new Map();
+    if (issueIds.length === 0)
+        return out;
+    // One deadline for the whole batch, not per page: the caller's budget is a slice of a ~3s
+    // coordinator tick, and a queue deeper than one page must not multiply it.
+    const deadlineAt = opts.timeoutMs ? Date.now() + opts.timeoutMs : null;
+    const remaining = () => (deadlineAt ? Math.max(1, deadlineAt - Date.now()) : undefined);
+    // Relations gathered so far per issue. Deleting an id here is how an incomplete list stays
+    // "unknown": it never reaches `out`, and the caller parks the entry for this tick only.
+    const relationsById = new Map();
+    let paging = [];
+    let after;
+    for (;;) {
+        const data = (await linearQuery(`query BlockingRelations($ids: [ID!], $after: String) {
+        issues(filter: { id: { in: $ids } }, first: ${PAGE_SIZE}, after: $after, includeArchived: true) {
+          nodes {
+            id
+            inverseRelations(first: ${PAGE_SIZE}) { ${RELATION_PAGE_FIELDS} }
+          }
+          pageInfo { hasNextPage endCursor }
+        }
+      }`, { ids: issueIds, after: after ?? null }, { timeoutMs: remaining() }));
+        for (const node of data.issues.nodes) {
+            // A list we did not get at all is unknown, not "no blockers": the one unsatisfied
+            // blocker may be exactly the relation we are missing.
+            if (!node.inverseRelations)
+                continue;
+            relationsById.set(node.id, [...(node.inverseRelations.nodes ?? [])]);
+            const next = nextRelationCursor(node.inverseRelations, null);
+            if (next === INCOMPLETE)
+                relationsById.delete(node.id);
+            else if (next)
+                paging.push({ id: node.id, after: next });
+        }
+        if (!data.issues.pageInfo.hasNextPage || !data.issues.pageInfo.endCursor)
+            break;
+        after = data.issues.pageInfo.endCursor;
+    }
+    // One request per round, however many issues are still paging.
+    while (paging.length > 0) {
+        const pages = await fetchInverseRelationRound(paging, remaining);
+        const nextRound = [];
+        for (const pending of paging) {
+            const page = pages.get(pending.id);
+            const relations = relationsById.get(pending.id);
+            // Linear stopped returning the issue mid-walk: we saw part of the list and the blocker
+            // that matters may be in the part we did not.
+            if (!page || !relations) {
+                relationsById.delete(pending.id);
+                continue;
+            }
+            relations.push(...(page.nodes ?? []));
+            const next = nextRelationCursor(page, pending.after);
+            if (next === INCOMPLETE)
+                relationsById.delete(pending.id);
+            else if (next)
+                nextRound.push({ id: pending.id, after: next });
+        }
+        paging = nextRound;
+    }
+    for (const [id, relations] of relationsById) {
+        out.set(id, relations.filter((r) => r.type === "blocks").map(relationToBlocker));
+    }
+    return out;
+}
+/** A relation list Linear will not let us finish — the id stays out of the result. */
+const INCOMPLETE = Symbol("incomplete relation page");
+/**
+ * Where to continue a relation connection: `null` when the list is complete, a cursor when
+ * there is more, `INCOMPLETE` when Linear claims more but hands back no usable cursor (which
+ * would otherwise loop forever).
+ */
+function nextRelationCursor(page, after) {
+    if (!page.pageInfo?.hasNextPage)
+        return null;
+    const cursor = page.pageInfo.endCursor;
+    if (!cursor || cursor === after)
+        return INCOMPLETE;
+    return cursor;
+}
+/**
+ * Advance every still-paging issue by one nested page in a single request.
+ *
+ * Each issue needs its own cursor, which one `issues(filter:)` selection cannot express, so
+ * the round is built as one aliased selection per issue. That keeps the cost of deep relation
+ * lists at one request per *round* rather than one per entry — the acceptance criterion is
+ * "no per-entry queries", and a queue of well-linked tickets is exactly where the naive
+ * version multiplies. Issues Linear omits come back absent from the map.
+ */
+async function fetchInverseRelationRound(pending, remaining) {
+    const varDefs = [];
+    const selections = [];
+    const variables = {};
+    pending.forEach((entry, i) => {
+        varDefs.push(`$ids${i}: [ID!], $after${i}: String`);
+        selections.push(`r${i}: issues(filter: { id: { in: $ids${i} } }, first: 1, includeArchived: true) {
+        nodes {
+          id
+          inverseRelations(first: ${PAGE_SIZE}, after: $after${i}) { ${RELATION_PAGE_FIELDS} }
+        }
+      }`);
+        variables[`ids${i}`] = [entry.id];
+        variables[`after${i}`] = entry.after;
+    });
+    const data = (await linearQuery(`query BlockingRelationsPage(${varDefs.join(", ")}) {\n${selections.join("\n")}\n}`, variables, { timeoutMs: remaining() }));
+    const out = new Map();
+    pending.forEach((entry, i) => {
+        const page = data[`r${i}`]?.nodes?.find((n) => n.id === entry.id)?.inverseRelations;
+        if (page)
+            out.set(entry.id, page);
+    });
+    return out;
+}
+/** Resolve free-form kick text to a Linear candidate (or null if not found / unparseable). */
+export async function lookupLinearIssue(raw) {
+    const id = parseLinearIssueRef(raw);
+    if (!id)
+        return null;
+    return getLinearIssue(id);
 }