agent-dealer 0.2.0 → 1.0.0

package/bundle/shared/dist/worker-sessions.d.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+/** "legacy" is migration-only — the new coordinator never spawns it. */
+export declare const WorkerSessionRole: z.ZodEnum<["developer", "reviewer", "legacy"]>;
+export type WorkerSessionRole = z.infer<typeof WorkerSessionRole>;
+export declare const WorkerSessionStatus: z.ZodEnum<["queued", "running", "done", "failed", "timed_out", "cancelled"]>;
+export type WorkerSessionStatus = z.infer<typeof WorkerSessionStatus>;
+export declare const WorkerSession: z.ZodObject<{
+    id: z.ZodString;
+    issueId: z.ZodString;
+    role: z.ZodEnum<["developer", "reviewer", "legacy"]>;
+    round: z.ZodNumber;
+    agentId: z.ZodNullable<z.ZodString>;
+    runtime: z.ZodNullable<z.ZodEnum<["claude_code", "cursor_local", "codex_local"]>>;
+    model: z.ZodNullable<z.ZodString>;
+    budgetJson: z.ZodNullable<z.ZodString>;
+    worktreePath: z.ZodNullable<z.ZodString>;
+    /** Immutable SHA supplied to this session; required in practice for reviewer sessions. */
+    inputSha: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<["queued", "running", "done", "failed", "timed_out", "cancelled"]>;
+    /** Runtime-native session id (e.g. Claude session_id) for resume/inspection. */
+    sessionRef: z.ZodNullable<z.ZodString>;
+    logPath: z.ZodNullable<z.ZodString>;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    errorJson: z.ZodNullable<z.ZodString>;
+    /** Migration/provider metadata (e.g. original legacy run id). */
+    metadataJson: z.ZodNullable<z.ZodString>;
+    /**
+     * Immutable execution-profile snapshot (serialized ProfileSnapshot) frozen when the
+     * session is created, so a later profile edit never rewrites this session's contract.
+     */
+    profileSnapshotJson: z.ZodNullable<z.ZodString>;
+    /**
+     * The spawned CLI's OS pid, the identity of the coordinator process that spawned it
+     * (NOT-124), and that pid's OS-reported start time (NOT-131). All null until the CLI
+     * actually starts, and for any session whose spawn never reports one.
+     *
+     * `processOwner` alone settles liveness for a pid this coordinator spawned. Across a
+     * restart it no longer matches, and the pid on its own proves nothing — the OS recycles
+     * pids, so `kill(pid, 0)` could succeed forever against an unrelated program.
+     * `processStartedAt` is what keeps the evidence usable there: a recycled pid always
+     * started later, so an exact match identifies the process and not merely the number. A
+     * row written before NOT-131 has none and reads as "no evidence", never as alive.
+     */
+    processPid: z.ZodNullable<z.ZodNumber>;
+    processOwner: z.ZodNullable<z.ZodString>;
+    processStartedAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    startedAt: z.ZodNullable<z.ZodString>;
+    heartbeatAt: z.ZodNullable<z.ZodString>;
+    completedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "queued" | "running" | "done" | "failed" | "timed_out" | "cancelled";
+    id: string;
+    issueId: string;
+    role: "developer" | "reviewer" | "legacy";
+    round: number;
+    agentId: string | null;
+    runtime: "claude_code" | "cursor_local" | "codex_local" | null;
+    model: string | null;
+    budgetJson: string | null;
+    worktreePath: string | null;
+    inputSha: string | null;
+    sessionRef: string | null;
+    logPath: string | null;
+    exitCode: number | null;
+    errorJson: string | null;
+    metadataJson: string | null;
+    profileSnapshotJson: string | null;
+    processPid: number | null;
+    processOwner: string | null;
+    processStartedAt: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    heartbeatAt: string | null;
+    completedAt: string | null;
+    updatedAt: string;
+}, {
+    status: "queued" | "running" | "done" | "failed" | "timed_out" | "cancelled";
+    id: string;
+    issueId: string;
+    role: "developer" | "reviewer" | "legacy";
+    round: number;
+    agentId: string | null;
+    runtime: "claude_code" | "cursor_local" | "codex_local" | null;
+    model: string | null;
+    budgetJson: string | null;
+    worktreePath: string | null;
+    inputSha: string | null;
+    sessionRef: string | null;
+    logPath: string | null;
+    exitCode: number | null;
+    errorJson: string | null;
+    metadataJson: string | null;
+    profileSnapshotJson: string | null;
+    processPid: number | null;
+    processOwner: string | null;
+    processStartedAt: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    heartbeatAt: string | null;
+    completedAt: string | null;
+    updatedAt: string;
+}>;
+export type WorkerSession = z.infer<typeof WorkerSession>;
+export declare const CreateWorkerSessionInput: z.ZodObject<{
+    issueId: z.ZodString;
+    role: z.ZodEnum<["developer", "reviewer", "legacy"]>;
+    round: z.ZodNumber;
+    agentId: z.ZodNullable<z.ZodString>;
+    runtime: z.ZodNullable<z.ZodEnum<["claude_code", "cursor_local", "codex_local"]>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    budgetJson: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    inputSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metadataJson: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    profileSnapshotJson: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    issueId: string;
+    role: "developer" | "reviewer" | "legacy";
+    round: number;
+    agentId: string | null;
+    runtime: "claude_code" | "cursor_local" | "codex_local" | null;
+    model?: string | null | undefined;
+    budgetJson?: string | null | undefined;
+    inputSha?: string | null | undefined;
+    metadataJson?: string | null | undefined;
+    profileSnapshotJson?: string | null | undefined;
+}, {
+    issueId: string;
+    role: "developer" | "reviewer" | "legacy";
+    round: number;
+    agentId: string | null;
+    runtime: "claude_code" | "cursor_local" | "codex_local" | null;
+    model?: string | null | undefined;
+    budgetJson?: string | null | undefined;
+    inputSha?: string | null | undefined;
+    metadataJson?: string | null | undefined;
+    profileSnapshotJson?: string | null | undefined;
+}>;
+export type CreateWorkerSessionInput = z.infer<typeof CreateWorkerSessionInput>;

package/bundle/shared/dist/worker-sessions.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { Runtime } from "./runtime.js";
+/** "legacy" is migration-only — the new coordinator never spawns it. */
+export const WorkerSessionRole = z.enum(["developer", "reviewer", "legacy"]);
+export const WorkerSessionStatus = z.enum([
+    "queued",
+    "running",
+    "done",
+    "failed",
+    "timed_out",
+    "cancelled",
+]);
+export const WorkerSession = z.object({
+    id: z.string().uuid(),
+    issueId: z.string().uuid(),
+    role: WorkerSessionRole,
+    round: z.number().int().min(1),
+    agentId: z.string().uuid().nullable(),
+    runtime: Runtime.nullable(),
+    model: z.string().nullable(),
+    budgetJson: z.string().nullable(),
+    worktreePath: z.string().nullable(),
+    /** Immutable SHA supplied to this session; required in practice for reviewer sessions. */
+    inputSha: z.string().nullable(),
+    status: WorkerSessionStatus,
+    /** Runtime-native session id (e.g. Claude session_id) for resume/inspection. */
+    sessionRef: z.string().nullable(),
+    logPath: z.string().nullable(),
+    exitCode: z.number().int().nullable(),
+    errorJson: z.string().nullable(),
+    /** Migration/provider metadata (e.g. original legacy run id). */
+    metadataJson: z.string().nullable(),
+    /**
+     * Immutable execution-profile snapshot (serialized ProfileSnapshot) frozen when the
+     * session is created, so a later profile edit never rewrites this session's contract.
+     */
+    profileSnapshotJson: z.string().nullable(),
+    /**
+     * The spawned CLI's OS pid, the identity of the coordinator process that spawned it
+     * (NOT-124), and that pid's OS-reported start time (NOT-131). All null until the CLI
+     * actually starts, and for any session whose spawn never reports one.
+     *
+     * `processOwner` alone settles liveness for a pid this coordinator spawned. Across a
+     * restart it no longer matches, and the pid on its own proves nothing — the OS recycles
+     * pids, so `kill(pid, 0)` could succeed forever against an unrelated program.
+     * `processStartedAt` is what keeps the evidence usable there: a recycled pid always
+     * started later, so an exact match identifies the process and not merely the number. A
+     * row written before NOT-131 has none and reads as "no evidence", never as alive.
+     */
+    processPid: z.number().int().nullable(),
+    processOwner: z.string().nullable(),
+    processStartedAt: z.string().nullable(),
+    createdAt: z.string(),
+    startedAt: z.string().nullable(),
+    heartbeatAt: z.string().nullable(),
+    completedAt: z.string().nullable(),
+    updatedAt: z.string(),
+});
+export const CreateWorkerSessionInput = z.object({
+    issueId: z.string().uuid(),
+    role: WorkerSessionRole,
+    round: z.number().int().min(1),
+    agentId: z.string().uuid().nullable(),
+    runtime: Runtime.nullable(),
+    model: z.string().nullable().optional(),
+    budgetJson: z.string().nullable().optional(),
+    inputSha: z.string().nullable().optional(),
+    metadataJson: z.string().nullable().optional(),
+    profileSnapshotJson: z.string().nullable().optional(),
+});

package/bundle/shared/dist/worker-sessions.test.d.ts

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

package/bundle/shared/dist/worker-sessions.test.js

@@ -0,0 +1,39 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { WorkerSession, WorkerSessionRole, WorkerSessionStatus } from "./worker-sessions.js";
+test("WorkerSession schema parses a queued developer session", () => {
+    const session = {
+        id: "44444444-4444-4444-4444-444444444444",
+        issueId: "11111111-1111-1111-1111-111111111111",
+        role: "developer",
+        round: 1,
+        agentId: "22222222-2222-2222-2222-222222222222",
+        runtime: "claude_code",
+        model: null,
+        budgetJson: null,
+        worktreePath: null,
+        inputSha: null,
+        status: "queued",
+        sessionRef: null,
+        logPath: null,
+        exitCode: null,
+        errorJson: null,
+        metadataJson: null,
+        profileSnapshotJson: null,
+        processPid: null,
+        processOwner: null,
+        processStartedAt: null,
+        createdAt: new Date().toISOString(),
+        startedAt: null,
+        heartbeatAt: null,
+        completedAt: null,
+        updatedAt: new Date().toISOString(),
+    };
+    assert.deepStrictEqual(WorkerSession.parse(session), session);
+});
+test("WorkerSessionRole accepts the legacy migration-only role", () => {
+    assert.equal(WorkerSessionRole.parse("legacy"), "legacy");
+});
+test("WorkerSessionStatus rejects an invalid status", () => {
+    assert.throws(() => WorkerSessionStatus.parse("bogus"));
+});

package/bundle/shared/dist/workflow.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+export declare const WorkflowInstanceOutcome: z.ZodEnum<["done", "closed", "migrated"]>;
+export type WorkflowInstanceOutcome = z.infer<typeof WorkflowInstanceOutcome>;
+export declare const WorkflowInstance: z.ZodObject<{
+    id: z.ZodString;
+    issueId: z.ZodString;
+    workflowVersion: z.ZodString;
+    startedAt: z.ZodString;
+    completedAt: z.ZodNullable<z.ZodString>;
+    outcome: z.ZodNullable<z.ZodEnum<["done", "closed", "migrated"]>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    issueId: string;
+    startedAt: string;
+    completedAt: string | null;
+    workflowVersion: string;
+    outcome: "done" | "closed" | "migrated" | null;
+}, {
+    id: string;
+    issueId: string;
+    startedAt: string;
+    completedAt: string | null;
+    workflowVersion: string;
+    outcome: "done" | "closed" | "migrated" | null;
+}>;
+export type WorkflowInstance = z.infer<typeof WorkflowInstance>;
+export declare const WorkflowEventType: z.ZodEnum<["issue.created", "workflow.started", "worker.started", "worker.completed", "worker.failed", "worker.deferred", "worktree.ready", "deck.connected", "brief.resolved", "branch.pushed", "checks.started", "pull_request.opened", "pull_request.updated", "checks.completed", "review.submitted", "repair.started", "guidance.added", "human_action.requested", "human_action.resolved", "final_review.requested", "issue.completed", "issue.closed", "legacy.imported"]>;
+export type WorkflowEventType = z.infer<typeof WorkflowEventType>;
+export declare const WorkflowEvent: z.ZodObject<{
+    id: z.ZodString;
+    issueId: z.ZodString;
+    /** Nullable only for issue creation/guidance emitted before any workflow starts. */
+    workflowInstanceId: z.ZodNullable<z.ZodString>;
+    workerSessionId: z.ZodNullable<z.ZodString>;
+    type: z.ZodEnum<["issue.created", "workflow.started", "worker.started", "worker.completed", "worker.failed", "worker.deferred", "worktree.ready", "deck.connected", "brief.resolved", "branch.pushed", "checks.started", "pull_request.opened", "pull_request.updated", "checks.completed", "review.submitted", "repair.started", "guidance.added", "human_action.requested", "human_action.resolved", "final_review.requested", "issue.completed", "issue.closed", "legacy.imported"]>;
+    actorType: z.ZodEnum<["human", "developer", "reviewer", "system"]>;
+    actorRef: z.ZodNullable<z.ZodString>;
+    /** Issue status at emit time — lets the timeline render without re-deriving state. */
+    stage: z.ZodString;
+    round: z.ZodNullable<z.ZodNumber>;
+    payloadJson: z.ZodNullable<z.ZodString>;
+    artifactRef: z.ZodNullable<z.ZodString>;
+    /** Provider-native key (e.g. GitHub delivery id) for idempotent re-ingestion. */
+    idempotencyKey: z.ZodNullable<z.ZodString>;
+    causationEventId: z.ZodNullable<z.ZodString>;
+    ts: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "issue.created" | "workflow.started" | "worker.started" | "worker.completed" | "worker.failed" | "worker.deferred" | "worktree.ready" | "deck.connected" | "brief.resolved" | "branch.pushed" | "checks.started" | "pull_request.opened" | "pull_request.updated" | "checks.completed" | "review.submitted" | "repair.started" | "guidance.added" | "human_action.requested" | "human_action.resolved" | "final_review.requested" | "issue.completed" | "issue.closed" | "legacy.imported";
+    id: string;
+    issueId: string;
+    round: number | null;
+    workflowInstanceId: string | null;
+    workerSessionId: string | null;
+    actorType: "developer" | "reviewer" | "human" | "system";
+    actorRef: string | null;
+    stage: string;
+    payloadJson: string | null;
+    artifactRef: string | null;
+    idempotencyKey: string | null;
+    causationEventId: string | null;
+    ts: string;
+}, {
+    type: "issue.created" | "workflow.started" | "worker.started" | "worker.completed" | "worker.failed" | "worker.deferred" | "worktree.ready" | "deck.connected" | "brief.resolved" | "branch.pushed" | "checks.started" | "pull_request.opened" | "pull_request.updated" | "checks.completed" | "review.submitted" | "repair.started" | "guidance.added" | "human_action.requested" | "human_action.resolved" | "final_review.requested" | "issue.completed" | "issue.closed" | "legacy.imported";
+    id: string;
+    issueId: string;
+    round: number | null;
+    workflowInstanceId: string | null;
+    workerSessionId: string | null;
+    actorType: "developer" | "reviewer" | "human" | "system";
+    actorRef: string | null;
+    stage: string;
+    payloadJson: string | null;
+    artifactRef: string | null;
+    idempotencyKey: string | null;
+    causationEventId: string | null;
+    ts: string;
+}>;
+export type WorkflowEvent = z.infer<typeof WorkflowEvent>;

package/bundle/shared/dist/workflow.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+export const WorkflowInstanceOutcome = z.enum(["done", "closed", "migrated"]);
+export const WorkflowInstance = z.object({
+    id: z.string().uuid(),
+    issueId: z.string().uuid(),
+    workflowVersion: z.string(),
+    startedAt: z.string(),
+    completedAt: z.string().nullable(),
+    outcome: WorkflowInstanceOutcome.nullable(),
+});
+export const WorkflowEventType = z.enum([
+    "issue.created",
+    "workflow.started",
+    "worker.started",
+    "worker.completed",
+    "worker.failed",
+    "worker.deferred",
+    /** Mid-session milestones (NOT-109) — low volume, not per-tool-call. */
+    "worktree.ready",
+    "deck.connected",
+    "brief.resolved",
+    "branch.pushed",
+    "checks.started",
+    "pull_request.opened",
+    "pull_request.updated",
+    "checks.completed",
+    "review.submitted",
+    "repair.started",
+    "guidance.added",
+    "human_action.requested",
+    "human_action.resolved",
+    "final_review.requested",
+    "issue.completed",
+    "issue.closed",
+    /** Migration-only — the NOT-66 cutover repoints a legacy `events` row under this type,
+     * preserving the original type/payload inside `payloadJson` (see `role: "legacy"` on
+     * `WorkerSessionRole` and `outcome: "migrated"` on `WorkflowInstanceOutcome` for the same
+     * migration-sentinel pattern). The new coordinator never emits it. */
+    "legacy.imported",
+]);
+export const WorkflowEvent = z.object({
+    id: z.string().uuid(),
+    issueId: z.string().uuid(),
+    /** Nullable only for issue creation/guidance emitted before any workflow starts. */
+    workflowInstanceId: z.string().uuid().nullable(),
+    workerSessionId: z.string().uuid().nullable(),
+    type: WorkflowEventType,
+    actorType: z.enum(["human", "developer", "reviewer", "system"]),
+    actorRef: z.string().nullable(),
+    /** Issue status at emit time — lets the timeline render without re-deriving state. */
+    stage: z.string(),
+    round: z.number().int().nullable(),
+    payloadJson: z.string().nullable(),
+    artifactRef: z.string().nullable(),
+    /** Provider-native key (e.g. GitHub delivery id) for idempotent re-ingestion. */
+    idempotencyKey: z.string().nullable(),
+    causationEventId: z.string().uuid().nullable(),
+    ts: z.string(),
+});

package/bundle/shared/dist/workflow.test.d.ts

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

package/bundle/shared/dist/workflow.test.js

@@ -0,0 +1,61 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { WorkflowEvent, WorkflowEventType, WorkflowInstance } from "./workflow.js";
+test("WorkflowInstance schema parses a running instance", () => {
+    const instance = {
+        id: "55555555-5555-5555-5555-555555555555",
+        issueId: "11111111-1111-1111-1111-111111111111",
+        workflowVersion: "dev_reviewer_v1",
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        outcome: null,
+    };
+    assert.deepStrictEqual(WorkflowInstance.parse(instance), instance);
+});
+test("WorkflowEventType accepts every PRD §9.2 event type", () => {
+    const types = [
+        "issue.created",
+        "workflow.started",
+        "worker.started",
+        "worker.completed",
+        "worker.failed",
+        "worktree.ready",
+        "deck.connected",
+        "brief.resolved",
+        "branch.pushed",
+        "checks.started",
+        "pull_request.opened",
+        "pull_request.updated",
+        "checks.completed",
+        "review.submitted",
+        "repair.started",
+        "guidance.added",
+        "human_action.requested",
+        "human_action.resolved",
+        "final_review.requested",
+        "issue.completed",
+        "issue.closed",
+    ];
+    for (const t of types) {
+        assert.equal(WorkflowEventType.parse(t), t);
+    }
+});
+test("WorkflowEvent allows a nullable workflow_instance_id for pre-workflow guidance", () => {
+    const event = {
+        id: "66666666-6666-6666-6666-666666666666",
+        issueId: "11111111-1111-1111-1111-111111111111",
+        workflowInstanceId: null,
+        workerSessionId: null,
+        type: "guidance.added",
+        actorType: "human",
+        actorRef: "yusuke",
+        stage: "ready",
+        round: null,
+        payloadJson: JSON.stringify({ markdown: "please prioritize the login bug" }),
+        artifactRef: null,
+        idempotencyKey: null,
+        causationEventId: null,
+        ts: new Date().toISOString(),
+    };
+    assert.deepStrictEqual(WorkflowEvent.parse(event), event);
+});

package/bundle/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/shared",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/dist/action.d.ts

@@ -0,0 +1 @@
+export declare function runActionCommand(args: string[]): Promise<number>;

package/dist/action.js

@@ -0,0 +1,50 @@
+import { apiFetch } from "./http.js";
+function flag(args, name) {
+    const idx = args.indexOf(name);
+    return idx >= 0 ? args[idx + 1] : undefined;
+}
+/** Parses responseOptionsJson so `action list` surfaces the valid choices directly,
+ * instead of forcing the caller to decode a JSON-encoded string within the JSON output. */
+function withChoices(action) {
+    let choices = [];
+    if (action.responseOptionsJson) {
+        try {
+            choices = JSON.parse(action.responseOptionsJson);
+        }
+        catch {
+            choices = [];
+        }
+    }
+    return { ...action, choices };
+}
+export async function runActionCommand(args) {
+    const [subcommand, ...rest] = args;
+    try {
+        if (subcommand === "list") {
+            const result = (await apiFetch("/api/human-actions"));
+            console.log(JSON.stringify(result.map(withChoices), null, 2));
+            return 0;
+        }
+        if (subcommand === "resolve") {
+            const id = rest[0];
+            const choice = flag(rest, "--choice");
+            const resolvedBy = flag(rest, "--by");
+            if (!id || !choice || !resolvedBy) {
+                console.error("resolve requires an action id, --choice, and --by");
+                return 1;
+            }
+            const result = await apiFetch(`/api/human-actions/${id}/resolve`, {
+                method: "POST",
+                body: { choice, resolvedBy },
+            });
+            console.log(JSON.stringify(result, null, 2));
+            return 0;
+        }
+        console.error(`Unknown action subcommand: ${subcommand}`);
+        return 1;
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+}

package/dist/action.test.d.ts

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

package/dist/action.test.js

@@ -0,0 +1,70 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runActionCommand } from "./action.js";
+import { stubFetch } from "./test-fetch-stub.js";
+test("action list calls GET /api/human-actions and surfaces parsed choices", async () => {
+    const stub = stubFetch("/api/human-actions", "GET", [
+        {
+            id: "a1",
+            issueId: "i1",
+            workflowInstanceId: null,
+            actionType: "final_review",
+            reason: "done",
+            question: "Accept?",
+            evidenceJson: null,
+            responseOptionsJson: JSON.stringify([{ choice: "complete", label: "Accept — merge & mark done" }]),
+            continuationPreviewJson: null,
+            status: "open",
+            resolutionJson: null,
+            resolvedBy: null,
+            requestedAt: "2026-01-01T00:00:00.000Z",
+            resolvedAt: null,
+        },
+    ]);
+    const originalLog = console.log;
+    let printed = "";
+    console.log = (msg) => {
+        printed = msg;
+    };
+    try {
+        const code = await runActionCommand(["list"]);
+        assert.equal(code, 0);
+        stub.assertCalled();
+        const [action] = JSON.parse(printed);
+        assert.deepEqual(action.choices, [{ choice: "complete", label: "Accept — merge & mark done" }]);
+    }
+    finally {
+        console.log = originalLog;
+        stub.restore();
+    }
+});
+test("action resolve requires an id, --choice, and --by", async () => {
+    const code = await runActionCommand(["resolve", "a1", "--choice", "complete"]);
+    assert.equal(code, 1);
+});
+test("action resolve calls POST /api/human-actions/:id/resolve with resolvedBy and choice", async () => {
+    const stub = stubFetch("/api/human-actions/a1/resolve", "POST", { issueStatus: "closed" });
+    try {
+        const code = await runActionCommand(["resolve", "a1", "--choice", "complete", "--by", "alice"]);
+        assert.equal(code, 0);
+        const body = stub.assertCalled();
+        assert.deepEqual(body, { choice: "complete", resolvedBy: "alice" });
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("action resolve returns nonzero on API failure", async () => {
+    const stub = stubFetch("/api/human-actions/a1/resolve", "POST", { error: "bad choice" }, 400);
+    try {
+        const code = await runActionCommand(["resolve", "a1", "--choice", "bogus", "--by", "alice"]);
+        assert.equal(code, 1);
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("unknown action subcommand returns nonzero", async () => {
+    const code = await runActionCommand(["bogus"]);
+    assert.equal(code, 1);
+});

package/dist/agent.d.ts

@@ -0,0 +1 @@
+export declare function runAgentCommand(args: string[]): Promise<number>;

package/dist/agent.js

@@ -0,0 +1,17 @@
+import { apiFetch } from "./http.js";
+export async function runAgentCommand(args) {
+    const [subcommand] = args;
+    try {
+        if (subcommand === "list") {
+            const result = await apiFetch("/api/agents");
+            console.log(JSON.stringify(result, null, 2));
+            return 0;
+        }
+        console.error(`Unknown agent subcommand: ${subcommand}`);
+        return 1;
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+}

package/dist/agent.test.d.ts

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

package/dist/agent.test.js

@@ -0,0 +1,19 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runAgentCommand } from "./agent.js";
+import { stubFetch } from "./test-fetch-stub.js";
+test("agent list calls GET /api/agents and exits 0", async () => {
+    const stub = stubFetch("/api/agents", "GET", { agents: [], issueCount: 0 });
+    try {
+        const code = await runAgentCommand(["list"]);
+        assert.equal(code, 0);
+        stub.assertCalled();
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("unknown agent subcommand returns nonzero", async () => {
+    const code = await runAgentCommand(["bogus"]);
+    assert.equal(code, 1);
+});

package/dist/cli-check.d.ts

@@ -1,6 +1,13 @@
 /** Match server cli-env resolution for doctor checks. */
 export declare function resolveClaudeBin(): string;
+/** Match server cli-env resolution for Cursor Agent CLI. */
+export declare function resolveCursorBin(): string;
+export declare function cursorInvokeArgs(args: string[]): string[];
 export declare function claudeAvailable(): Promise<{
     ok: boolean;
     bin: string;
 }>;
+export declare function cursorAvailable(): Promise<{
+    ok: boolean;
+    bin: string;
+}>;