agent-dealer 0.2.0 → 1.0.0

package/dist/cli-check.js

@@ -19,6 +19,33 @@ export function resolveClaudeBin() {
     }
     return "claude";
 }
+/** Match server cli-env resolution for Cursor Agent CLI. */
+export function resolveCursorBin() {
+    const home = process.env.HOME ?? os.homedir();
+    if (process.env.CURSOR_CLI)
+        return process.env.CURSOR_CLI;
+    const candidates = [
+        path.join(home, ".local/bin/cursor-agent"),
+        path.join(home, ".cursor/bin/cursor-agent"),
+        "/opt/homebrew/bin/cursor-agent",
+        "/usr/local/bin/cursor-agent",
+        path.join(home, ".local/bin/cursor"),
+        path.join(home, ".cursor/bin/cursor"),
+        "/opt/homebrew/bin/cursor",
+        "/usr/local/bin/cursor",
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return "cursor-agent";
+}
+export function cursorInvokeArgs(args) {
+    const bin = resolveCursorBin();
+    if (path.basename(bin) === "cursor")
+        return ["agent", ...args];
+    return args;
+}
 export async function claudeAvailable() {
     const bin = resolveClaudeBin();
     if (bin !== "claude")
@@ -27,3 +54,16 @@ export async function claudeAvailable() {
         spawn("which", ["claude"]).on("close", (code) => resolve({ ok: code === 0, bin }));
     });
 }
+export async function cursorAvailable() {
+    const bin = resolveCursorBin();
+    if (bin !== "cursor-agent" && bin !== "cursor")
+        return { ok: true, bin };
+    return new Promise((resolve) => {
+        spawn("which", ["cursor-agent"]).on("close", (code) => {
+            if (code === 0)
+                resolve({ ok: true, bin: "cursor-agent" });
+            else
+                spawn("which", ["cursor"]).on("close", (c2) => resolve({ ok: c2 === 0, bin: "cursor" }));
+        });
+    });
+}

package/dist/doctor.js

@@ -1,6 +1,8 @@
 import net from "node:net";
 import fs from "node:fs";
-import { claudeAvailable } from "./cli-check.js";
+import path from "node:path";
+import { cursorAuthIssueFromOutput } from "@agent-dealer/shared";
+import { claudeAvailable, cursorAvailable } from "./cli-check.js";
 import { loadProdEnvFile, prodEnvFilePath, prodHomeDir, resolveBundledListenPort, shortenHome, } from "./env.js";
 import { probeAgentDealer } from "./ports.js";
 import { resolveServerEntry, resolveUiDist } from "./paths.js";
@@ -23,6 +25,62 @@ export async function runDoctor() {
         console.error("  https://docs.anthropic.com/en/docs/claude-code");
         failed = true;
     }
+    {
+        const cursor = await cursorAvailable();
+        if (!cursor.ok) {
+            console.warn("⚠ Cursor Agent CLI not found (optional for cursor_local agents)");
+        }
+        else {
+            const { spawnSync } = await import("node:child_process");
+            const bin = cursor.bin;
+            const statusArgs = path.basename(bin) === "cursor" ? ["agent", "status"] : ["status"];
+            const status = spawnSync(bin, statusArgs, {
+                encoding: "utf8",
+                timeout: 8000,
+                env: process.env,
+            });
+            const output = `${status.stdout ?? ""}${status.stderr ?? ""}${status.error?.message ?? ""}`;
+            const authIssue = cursorAuthIssueFromOutput(output);
+            if (authIssue) {
+                console.error(`✗ Cursor auth — ${authIssue.message}`);
+                console.error("  See docs/TROUBLESHOOTING.md#cursor-macos-keychain-auth");
+                failed = true;
+            }
+            else if (status.error || status.status !== 0) {
+                const detail = (status.error?.message ?? output.trim()) || `exit ${status.status}`;
+                console.error(`✗ Cursor auth — status failed (${detail})`);
+                console.error("  See docs/TROUBLESHOOTING.md#cursor-macos-keychain-auth");
+                failed = true;
+            }
+            else {
+                console.log(`✓ Cursor Agent CLI auth (${bin})`);
+            }
+        }
+    }
+    {
+        const { spawnSync } = await import("node:child_process");
+        const ghVer = spawnSync("gh", ["--version"], { encoding: "utf8" });
+        if (ghVer.error || ghVer.status !== 0) {
+            console.error("✗ GitHub CLI (`gh`) not found — install gh (required to open draft PRs)");
+            failed = true;
+        }
+        else {
+            const auth = spawnSync("gh", ["auth", "status"], { encoding: "utf8" });
+            const out = `${auth.stdout ?? ""}${auth.stderr ?? ""}`.toLowerCase();
+            if (auth.status !== 0 ||
+                out.includes("not logged in") ||
+                out.includes("failed to log in") ||
+                out.includes("token in keyring is invalid") ||
+                out.includes("re-authenticate")) {
+                console.error("✗ GitHub CLI auth — run: gh auth login -h github.com");
+                console.error("  (Issue workflows open draft PRs via gh; invalid auth wastes agent runs.)");
+                failed = true;
+            }
+            else {
+                console.log("✓ GitHub CLI auth");
+            }
+        }
+    }
     try {
         resolveServerEntry();
         console.log("✓ @agent-dealer/server entry");

package/dist/http.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveApiBase(): string;
+export declare function apiFetch(path: string, opts?: {
+    method?: string;
+    body?: unknown;
+}): Promise<unknown>;

package/dist/http.js

@@ -0,0 +1,19 @@
+import { readRunState } from "./runtime-state.js";
+import { loadProdEnvFile, resolveBundledListenPort } from "./env.js";
+export function resolveApiBase() {
+    loadProdEnvFile();
+    const state = readRunState();
+    const port = state?.port ?? resolveBundledListenPort();
+    return `http://127.0.0.1:${port}`;
+}
+export async function apiFetch(path, opts) {
+    const res = await fetch(`${resolveApiBase()}${path}`, {
+        method: opts?.method ?? "GET",
+        headers: opts?.body ? { "content-type": "application/json" } : undefined,
+        body: opts?.body ? JSON.stringify(opts.body) : undefined,
+    });
+    const json = await res.json().catch(() => null);
+    if (!res.ok)
+        throw new Error(`API error ${res.status}: ${JSON.stringify(json)}`);
+    return json;
+}

package/dist/index.js

@@ -16,6 +16,18 @@ function printUsage() {
   agent-dealer doctor
   agent-dealer install [--to VERSION] [--migrate-cli] [--purge-global]
   agent-dealer upgrade [--to VERSION] [--yes] [--check]
+  agent-dealer agent list
+  agent-dealer issue create --title T --repo owner/repo --developer-agent ID --reviewer-agent ID [--description D] [--acceptance-criteria A] [--base-branch B] [--no-enqueue]
+  agent-dealer issue import --external-id ID --title T --repo owner/repo --developer-agent ID --reviewer-agent ID [--external-label L]
+  agent-dealer issue list [--status S1,S2]
+  agent-dealer issue show <id> [--include evidence]
+  agent-dealer issue start <id>
+  agent-dealer issue guide <id> --message M
+  agent-dealer queue add <issueId>
+  agent-dealer queue remove <issueId>
+  agent-dealer queue list
+  agent-dealer action list
+  agent-dealer action resolve <id> --choice C --by NAME
   agent-dealer --version
 
 Human control plane for agent execution.`);
@@ -123,6 +135,22 @@ export async function runCli(argv) {
         }
         return runUpgrade({ toVersion, yes, check });
     }
+    if (cmd === "agent") {
+        const { runAgentCommand } = await import("./agent.js");
+        return runAgentCommand(args.slice(1));
+    }
+    if (cmd === "issue") {
+        const { runIssueCommand } = await import("./issue.js");
+        return runIssueCommand(args.slice(1));
+    }
+    if (cmd === "queue") {
+        const { runQueueCommand } = await import("./queue.js");
+        return runQueueCommand(args.slice(1));
+    }
+    if (cmd === "action") {
+        const { runActionCommand } = await import("./action.js");
+        return runActionCommand(args.slice(1));
+    }
     console.error(`Unknown command: ${cmd}`);
     printUsage();
     return 1;

package/dist/issue.d.ts

@@ -0,0 +1,35 @@
+export type ParsedIssueArgs = {
+    subcommand: "create";
+    title: string;
+    repo: string;
+    developerAgentId: string;
+    reviewerAgentId: string;
+    description?: string;
+    acceptanceCriteria?: string;
+    baseBranch?: string;
+    enqueue: boolean;
+} | {
+    subcommand: "import";
+    externalId: string;
+    externalLabel?: string;
+    title: string;
+    repo: string;
+    developerAgentId: string;
+    reviewerAgentId: string;
+} | {
+    subcommand: "list";
+    status?: string;
+} | {
+    subcommand: "show";
+    id: string;
+    includeEvidence: boolean;
+} | {
+    subcommand: "start";
+    id: string;
+} | {
+    subcommand: "guide";
+    id: string;
+    message: string;
+};
+export declare function parseIssueArgs(args: string[]): ParsedIssueArgs;
+export declare function runIssueCommand(args: string[]): Promise<number>;

package/dist/issue.js

@@ -0,0 +1,143 @@
+import { apiFetch } from "./http.js";
+/**
+ * NOT-141: the hint reports what the server *did*, never what was requested. Printing
+ * "Queued for admission" off the request flag told operators a queue happened when a
+ * re-import had matched an existing issue and queued nothing.
+ */
+function createOutcomeHint(result) {
+    if (!result.created) {
+        const matched = `Matched existing issue ${result.id} (${result.status}) — nothing new was created`;
+        switch (result.queue) {
+            // Enqueue is idempotent: an issue already waiting is not a queue action, so the hint
+            // must not claim one. `queue list` is the honest next step.
+            case "already_queued":
+                return `${matched}, and it was already in the admission queue — nothing was queued. \`agent-dealer queue list\` shows its position and wait reason.`;
+            case "enqueued":
+                return `${matched}; it was put back in the admission queue.`;
+            case "not_queued":
+                return `${matched} and nothing was queued.`;
+        }
+    }
+    const pass = result.priorPasses > 0
+        ? ` This is pass ${result.priorPasses + 1} on ${result.externalLabel ?? result.externalId} — ${result.priorPasses} earlier pass(es) already finished.`
+        : "";
+    return result.queue === "enqueued"
+        ? `Queued for admission — \`agent-dealer queue list\` shows position and wait reason.${pass}`
+        : `Created as a draft (not queued) — \`agent-dealer queue add <id>\` when it is ready.${pass}`;
+}
+function flag(args, name) {
+    const idx = args.indexOf(name);
+    return idx >= 0 ? args[idx + 1] : undefined;
+}
+export function parseIssueArgs(args) {
+    const [subcommand, ...rest] = args;
+    switch (subcommand) {
+        case "create":
+        case "import": {
+            const title = flag(rest, "--title");
+            const repo = flag(rest, "--repo");
+            const developerAgentId = flag(rest, "--developer-agent");
+            const reviewerAgentId = flag(rest, "--reviewer-agent");
+            if (!title || !repo || !developerAgentId || !reviewerAgentId) {
+                throw new Error(`${subcommand} requires --title, --repo, --developer-agent, --reviewer-agent`);
+            }
+            if (subcommand === "import") {
+                const externalId = flag(rest, "--external-id");
+                if (!externalId)
+                    throw new Error("import requires --external-id");
+                return { subcommand: "import", externalId, externalLabel: flag(rest, "--external-label"), title, repo, developerAgentId, reviewerAgentId };
+            }
+            // NOT-118: create enqueues for admission by default; --no-enqueue leaves a draft out.
+            return { subcommand: "create", title, repo, developerAgentId, reviewerAgentId, description: flag(rest, "--description"), acceptanceCriteria: flag(rest, "--acceptance-criteria"), baseBranch: flag(rest, "--base-branch"), enqueue: !rest.includes("--no-enqueue") };
+        }
+        case "list": {
+            return { subcommand: "list", status: flag(rest, "--status") };
+        }
+        case "show": {
+            const id = rest[0];
+            if (!id)
+                throw new Error("show requires an issue id");
+            return { subcommand: "show", id, includeEvidence: rest.includes("--include") && rest[rest.indexOf("--include") + 1] === "evidence" };
+        }
+        case "start": {
+            const id = rest[0];
+            if (!id)
+                throw new Error("start requires an issue id");
+            return { subcommand: "start", id };
+        }
+        case "guide": {
+            const id = rest[0];
+            const message = flag(rest, "--message");
+            if (!id || !message)
+                throw new Error("guide requires an issue id and --message");
+            return { subcommand: "guide", id, message };
+        }
+        default:
+            throw new Error(`Unknown issue subcommand: ${subcommand}`);
+    }
+}
+export async function runIssueCommand(args) {
+    let parsed;
+    try {
+        parsed = parseIssueArgs(args);
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+    try {
+        switch (parsed.subcommand) {
+            case "create": {
+                const result = (await apiFetch("/api/issues", { method: "POST", body: { title: parsed.title, repo: parsed.repo, developerAgentId: parsed.developerAgentId, reviewerAgentId: parsed.reviewerAgentId, description: parsed.description, acceptanceCriteria: parsed.acceptanceCriteria, baseBranch: parsed.baseBranch, source: "agent", enqueue: parsed.enqueue } }));
+                console.log(JSON.stringify(result, null, 2));
+                // stdout stays pure JSON for agents that pipe it — the hint goes to stderr.
+                console.error(createOutcomeHint(result));
+                return 0;
+            }
+            case "import": {
+                // A re-import of a ticket already in flight answers 409 (apiFetch throws) — the
+                // operator sees the conflicting issue id instead of a 200 they cannot interpret.
+                const result = (await apiFetch("/api/issues", { method: "POST", body: { title: parsed.title, repo: parsed.repo, developerAgentId: parsed.developerAgentId, reviewerAgentId: parsed.reviewerAgentId, source: "linear", externalId: parsed.externalId, externalLabel: parsed.externalLabel } }));
+                console.log(JSON.stringify(result, null, 2));
+                console.error(createOutcomeHint(result));
+                return 0;
+            }
+            case "list": {
+                const query = parsed.status ? `?status=${encodeURIComponent(parsed.status)}` : "";
+                const result = await apiFetch(`/api/issues${query}`);
+                console.log(JSON.stringify(result, null, 2));
+                return 0;
+            }
+            case "show": {
+                const result = await apiFetch(`/api/issues/${parsed.id}`);
+                if (parsed.includeEvidence) {
+                    const evidence = await apiFetch(`/api/issues/${parsed.id}/evidence`);
+                    console.log(JSON.stringify({ ...result, evidence }, null, 2));
+                }
+                else {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                return 0;
+            }
+            case "start": {
+                // NOT-118: start moves the issue to the front of the admission queue. It either
+                // admits it right away or leaves it waiting at position 1 — never a queue bypass.
+                const result = (await apiFetch(`/api/issues/${parsed.id}/start`, { method: "POST" }));
+                console.log(JSON.stringify(result, null, 2));
+                console.error(result.state === "admitted"
+                    ? "Admitted — the workflow started."
+                    : `Queued at position ${result.position}${result.waitReason ? ` — ${result.waitReason}` : ""}.`);
+                return 0;
+            }
+            case "guide": {
+                const result = await apiFetch(`/api/issues/${parsed.id}/guidance`, { method: "POST", body: { markdown: parsed.message } });
+                console.log(JSON.stringify(result, null, 2));
+                return 0;
+            }
+        }
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+}

package/dist/issue.test.d.ts

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

package/dist/issue.test.js

@@ -0,0 +1,240 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseIssueArgs, runIssueCommand } from "./issue.js";
+import { stubFetch } from "./test-fetch-stub.js";
+test("parseIssueArgs: create requires --title and --repo", () => {
+    const parsed = parseIssueArgs(["create", "--title", "Fix bug", "--repo", "/repo", "--developer-agent", "a1", "--reviewer-agent", "a2"]);
+    assert.equal(parsed.subcommand, "create");
+    assert.equal(parsed.title, "Fix bug");
+    // NOT-118: queue by default.
+    assert.equal(parsed.enqueue, true);
+});
+test("parseIssueArgs: create --no-enqueue asks for a draft outside the queue", () => {
+    const parsed = parseIssueArgs(["create", "--title", "Draft", "--repo", "/repo", "--developer-agent", "a1", "--reviewer-agent", "a2", "--no-enqueue"]);
+    assert.equal(parsed.enqueue, false);
+});
+test("parseIssueArgs: show requires an id", () => {
+    const parsed = parseIssueArgs(["show", "issue-123"]);
+    assert.equal(parsed.subcommand, "show");
+    assert.equal(parsed.id, "issue-123");
+});
+test("parseIssueArgs: unknown subcommand throws", () => {
+    assert.throws(() => parseIssueArgs(["bogus"]));
+});
+test("parseIssueArgs: guide requires an id and --message", () => {
+    const parsed = parseIssueArgs(["guide", "issue-123", "--message", "prioritize this"]);
+    assert.equal(parsed.subcommand, "guide");
+    assert.equal(parsed.message, "prioritize this");
+});
+test("parseIssueArgs: list accepts an optional --status", () => {
+    assert.deepEqual(parseIssueArgs(["list"]), { subcommand: "list", status: undefined });
+    assert.deepEqual(parseIssueArgs(["list", "--status", "ready,needs_human"]), {
+        subcommand: "list",
+        status: "ready,needs_human",
+    });
+});
+test("parseIssueArgs: start requires an id", () => {
+    const parsed = parseIssueArgs(["start", "issue-123"]);
+    assert.equal(parsed.subcommand, "start");
+    assert.equal(parsed.id, "issue-123");
+    assert.throws(() => parseIssueArgs(["start"]));
+});
+test("issue list calls GET /api/issues and exits 0", async () => {
+    const stub = stubFetch("/api/issues", "GET", [{ id: "i1", status: "ready" }]);
+    try {
+        const code = await runIssueCommand(["list"]);
+        assert.equal(code, 0);
+        stub.assertCalled();
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("issue list forwards --status as a query param", async () => {
+    const stub = stubFetch(/\/api\/issues\?status=ready%2Cneeds_human$/, "GET", []);
+    try {
+        await runIssueCommand(["list", "--status", "ready,needs_human"]);
+        stub.assertCalled();
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("issue create sends enqueue:true by default and enqueue:false with --no-enqueue", async () => {
+    const enqueued = stubFetch("/api/issues", "POST", { id: "i1", status: "ready" });
+    try {
+        assert.equal(await runIssueCommand(["create", "--title", "T", "--repo", "/r", "--developer-agent", "a1", "--reviewer-agent", "a2"]), 0);
+        assert.equal(enqueued.assertCalled().enqueue, true);
+    }
+    finally {
+        enqueued.restore();
+    }
+    const draft = stubFetch("/api/issues", "POST", { id: "i2", status: "ready" });
+    try {
+        await runIssueCommand(["create", "--title", "T", "--repo", "/r", "--developer-agent", "a1", "--reviewer-agent", "a2", "--no-enqueue"]);
+        assert.equal(draft.assertCalled().enqueue, false);
+    }
+    finally {
+        draft.restore();
+    }
+});
+/** Runs the command with stderr captured — the hints go to stderr, stdout stays JSON. */
+async function captureStderr(args) {
+    const errs = [];
+    const logs = [];
+    const originalError = console.error;
+    const originalLog = console.log;
+    console.error = (message) => errs.push(String(message));
+    console.log = (message) => logs.push(String(message));
+    try {
+        const code = await runIssueCommand(args);
+        return { code, err: errs.join("\n"), out: logs.join("\n") };
+    }
+    finally {
+        console.error = originalError;
+        console.log = originalLog;
+    }
+}
+const createArgs = ["--title", "T", "--repo", "/r", "--developer-agent", "a1", "--reviewer-agent", "a2"];
+test("NOT-141: the create hint reports what the server did, not what was requested", async () => {
+    const matched = stubFetch("/api/issues", "POST", { id: "i1", status: "developing", created: false, queue: "not_queued" });
+    try {
+        const { code, err } = await captureStderr(["create", ...createArgs]);
+        assert.equal(code, 0);
+        assert.doesNotMatch(err, /Queued for admission/);
+        assert.match(err, /Matched existing issue i1 \(developing\)/);
+        assert.match(err, /nothing was queued/);
+    }
+    finally {
+        matched.restore();
+    }
+    // The issue was already waiting: enqueue changed nothing, so the hint must not report a
+    // queue action of any kind — the bug this ticket is about, one step down the line.
+    const alreadyQueued = stubFetch("/api/issues", "POST", { id: "i2", status: "ready", created: false, queue: "already_queued" });
+    try {
+        const { err } = await captureStderr(["create", ...createArgs]);
+        assert.doesNotMatch(err, /Queued for admission/);
+        assert.doesNotMatch(err, /re-queued|was put back/);
+        assert.match(err, /already in the admission queue — nothing was queued/);
+    }
+    finally {
+        alreadyQueued.restore();
+    }
+    const requeued = stubFetch("/api/issues", "POST", { id: "i6", status: "ready", created: false, queue: "enqueued" });
+    try {
+        const { err } = await captureStderr(["create", ...createArgs]);
+        assert.doesNotMatch(err, /Queued for admission/);
+        assert.match(err, /it was put back in the admission queue/);
+    }
+    finally {
+        requeued.restore();
+    }
+    const fresh = stubFetch("/api/issues", "POST", { id: "i3", status: "ready", created: true, queue: "enqueued", priorPasses: 0 });
+    try {
+        const { err } = await captureStderr(["create", ...createArgs]);
+        assert.match(err, /Queued for admission/);
+        assert.doesNotMatch(err, /pass/);
+    }
+    finally {
+        fresh.restore();
+    }
+});
+test("NOT-141: a second pass on a ticket is named as such, not printed like a first import", async () => {
+    const secondPass = stubFetch("/api/issues", "POST", {
+        id: "i5",
+        status: "ready",
+        created: true,
+        queue: "enqueued",
+        priorPasses: 1,
+        externalId: "lin-uuid",
+        externalLabel: "NOT-128",
+    });
+    try {
+        const { err } = await captureStderr(["import", "--external-id", "lin-uuid", ...createArgs]);
+        assert.match(err, /Queued for admission/);
+        assert.match(err, /This is pass 2 on NOT-128 — 1 earlier pass\(es\) already finished\./);
+    }
+    finally {
+        secondPass.restore();
+    }
+});
+test("NOT-141: import reports a fresh row, and surfaces the 409 conflict instead of exiting 0", async () => {
+    const created = stubFetch("/api/issues", "POST", { id: "i4", status: "ready", created: true, queue: "enqueued" });
+    try {
+        const { code, err } = await captureStderr(["import", "--external-id", "NOT-1", ...createArgs]);
+        assert.equal(code, 0);
+        assert.match(err, /Queued for admission/);
+    }
+    finally {
+        created.restore();
+    }
+    const conflict = stubFetch("/api/issues", "POST", { error: "Issue i4 is already tracking linear NOT-1 (developing)", existingIssueId: "i4", existingIssueStatus: "developing" }, 409);
+    try {
+        const { code, err } = await captureStderr(["import", "--external-id", "NOT-1", ...createArgs]);
+        assert.equal(code, 1);
+        assert.match(err, /already tracking linear NOT-1/);
+        assert.doesNotMatch(err, /Queued for admission/);
+    }
+    finally {
+        conflict.restore();
+    }
+});
+test("issue start prints the admitted response shape and exits 0", async () => {
+    const stub = stubFetch("/api/issues/issue-123/start", "POST", {
+        state: "admitted",
+        instance: { id: "wf-1" },
+        workItem: { id: "work-1", kind: "developer" },
+    });
+    const logs = [];
+    const originalLog = console.log;
+    console.log = (message) => logs.push(String(message));
+    try {
+        const code = await runIssueCommand(["start", "issue-123"]);
+        assert.equal(code, 0);
+        stub.assertCalled();
+        const printed = JSON.parse(logs.join("\n"));
+        assert.equal(printed.state, "admitted");
+        assert.equal(printed.instance.id, "wf-1");
+    }
+    finally {
+        console.log = originalLog;
+        stub.restore();
+    }
+});
+test("issue start prints the queued response shape (position + wait reason) and still exits 0", async () => {
+    const stub = stubFetch("/api/issues/issue-123/start", "POST", {
+        state: "queued",
+        position: 1,
+        waitReason: "waiting for slot — running: Other issue",
+    });
+    const logs = [];
+    const errs = [];
+    const originalLog = console.log;
+    const originalError = console.error;
+    console.log = (message) => logs.push(String(message));
+    console.error = (message) => errs.push(String(message));
+    try {
+        const code = await runIssueCommand(["start", "issue-123"]);
+        assert.equal(code, 0);
+        const printed = JSON.parse(logs.join("\n"));
+        assert.equal(printed.state, "queued");
+        assert.equal(printed.position, 1);
+        assert.match(printed.waitReason, /waiting for slot/);
+        assert.match(errs.join("\n"), /Queued at position 1 — waiting for slot/);
+    }
+    finally {
+        console.log = originalLog;
+        console.error = originalError;
+        stub.restore();
+    }
+});
+test("issue start returns nonzero on API failure", async () => {
+    const stub = stubFetch("/api/issues/issue-123/start", "POST", { error: "not ready" }, 400);
+    try {
+        const code = await runIssueCommand(["start", "issue-123"]);
+        assert.equal(code, 1);
+    }
+    finally {
+        stub.restore();
+    }
+});

package/dist/lifecycle.contract.test.d.ts

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