agent-dealer 0.2.0 → 1.0.0

package/bundle/shared/dist/index.js

@@ -4,12 +4,21 @@ import { AgentWithHealth } from "./agents.js";
 import { PhaseBudget, RunBudget } from "./budget.js";
 export * from "./runtime.js";
 export * from "./agents.js";
+export * from "./runtime-auth-health.js";
 export * from "./budget.js";
 export * from "./execution.js";
-export * from "./plan-triage.js";
 export * from "./outbound-draft.js";
-export * from "./result-qa.js";
 export * from "./playbook-reflect.js";
+export * from "./issues.js";
+export * from "./github-repo.js";
+export * from "./worker-sessions.js";
+export * from "./profile-snapshot.js";
+export * from "./workflow.js";
+export * from "./human-actions.js";
+export * from "./findings.js";
+export * from "./usage-events.js";
+export * from "./runtime-availability.js";
+export * from "./queue-entries.js";
 export const RunStatus = z.enum([
     "queued",
     "plan_pending",
@@ -248,51 +257,26 @@ export const LinearCandidate = z.object({
     labels: z.array(z.string()).optional(),
     teamId: z.string().optional(),
 });
-export const LinearRoutingRule = z.object({
-    label: z.string().min(1),
-    agentId: z.string().uuid(),
-});
+// NOT-71: defaultAgentId and routingRules (label -> agent `autoAgent` routing) are gone
+// with intake/agent-routing.ts and the promote endpoint that consumed them. The persisted
+// `linear.defaultAgentId` / `linear.routingRules` rows are left in intake_settings — this
+// ticket removes no user data — but nothing reads them into the config any more.
 export const LinearIntakeConfig = z.object({
     stateFilter: z.array(z.string()),
     teamId: z.string().nullable(),
     assigneeMe: z.boolean(),
-    defaultAgentId: z.string().uuid().nullable(),
     syncEnabled: z.boolean(),
-    routingRules: z.array(LinearRoutingRule),
-});
-/** GET /api/intake/linear/config — effective config plus persistence hints for the UI */
-export const LinearIntakeConfigView = LinearIntakeConfig.extend({
-    persisted: LinearIntakeConfig,
-    envOverrides: z.object({
-        stateFilter: z.boolean(),
-        teamId: z.boolean(),
-    }),
-});
-export const LinearIntakeConfigPatch = LinearIntakeConfig.partial();
-export const LinearConnectionStatus = z.object({
-    connected: z.boolean(),
-    viewer: z
-        .object({
-        id: z.string(),
-        name: z.string(),
-        email: z.string().optional(),
-    })
-        .optional(),
-    error: z.string().optional(),
-});
-export const ResolveAgentResult = z.object({
-    agentId: z.string().uuid(),
-    reason: z.string(),
 });
 export const AgentDeckConfig = z.object({
     host: z.string(),
     port: z.number().int().min(1).max(65535),
     envOverride: z.boolean(),
 });
-export const AgentDeckConfigPatch = z.object({
-    host: z.string().min(1).optional(),
-    port: z.number().int().min(1).max(65535).optional(),
-});
+/** Typed outcomes for deck-metadata discovery — never collapse to an empty list. */
+export const DeckAccessErrorCode = z.enum([
+    "UNAUTHORIZED",
+    "DECK_UNAVAILABLE",
+]);
 export const AgentDeckStatus = z.object({
     connected: z.boolean(),
     apiUrl: z.string(),
@@ -300,6 +284,8 @@ export const AgentDeckStatus = z.object({
     deckCount: z.number().optional(),
     envOverride: z.boolean(),
     error: z.string().optional(),
+    deckAccessError: DeckAccessErrorCode.optional(),
+    deckAccessErrorMessage: z.string().optional(),
 });
 export const PromoteLinearInput = z
     .object({

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

@@ -0,0 +1,385 @@
+import { z } from "zod";
+export declare const IssueStatus: z.ZodEnum<["ready", "developing", "reviewing", "repairing", "final_review", "needs_human", "done", "closed"]>;
+export type IssueStatus = z.infer<typeof IssueStatus>;
+export declare const IssueOwner: z.ZodEnum<["human", "developer", "reviewer", "system"]>;
+export type IssueOwner = z.infer<typeof IssueOwner>;
+/** "agent" covers an issue a coding agent created via the API/CLI (PRD §5). */
+export declare const IssueSource: z.ZodEnum<["manual", "linear", "agent"]>;
+export type IssueSource = z.infer<typeof IssueSource>;
+export declare const Issue: z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodEnum<["manual", "linear", "agent"]>;
+    externalId: z.ZodNullable<z.ZodString>;
+    externalLabel: z.ZodNullable<z.ZodString>;
+    externalUrl: z.ZodNullable<z.ZodString>;
+    title: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    acceptanceCriteria: z.ZodNullable<z.ZodString>;
+    /**
+     * Portable GitHub identity (`github.com/owner/repo`) for new issues (NOT-149).
+     * Legacy rows may still hold a local filesystem path until explicitly migrated —
+     * the coordinator resolves those via an explicit compatibility path, never by guessing.
+     */
+    repo: z.ZodString;
+    baseBranch: z.ZodString;
+    status: z.ZodEnum<["ready", "developing", "reviewing", "repairing", "final_review", "needs_human", "done", "closed"]>;
+    currentOwner: z.ZodEnum<["human", "developer", "reviewer", "system"]>;
+    currentIntent: z.ZodNullable<z.ZodString>;
+    developerAgentId: z.ZodNullable<z.ZodString>;
+    reviewerAgentId: z.ZodNullable<z.ZodString>;
+    maxReviewRounds: z.ZodNumber;
+    currentRound: z.ZodNumber;
+    /** 0 is a valid policy: no automatic infra retry, escalate to a human immediately. */
+    maxInfraAttempts: z.ZodNumber;
+    infraAttempts: z.ZodNumber;
+    branch: z.ZodNullable<z.ZodString>;
+    baseSha: z.ZodNullable<z.ZodString>;
+    headSha: z.ZodNullable<z.ZodString>;
+    prNumber: z.ZodNullable<z.ZodNumber>;
+    prUrl: z.ZodNullable<z.ZodString>;
+    /**
+     * When true, reviewer `approved` merges the PR and marks the issue done (skips
+     * `final_review`). Kick UI defaults this on; API/CLI omit → false so existing
+     * callers keep the human final-review path.
+     */
+    autoMerge: z.ZodBoolean;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "done" | "final_review" | "ready" | "developing" | "reviewing" | "repairing" | "needs_human" | "closed";
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    title: string;
+    source: "manual" | "linear" | "agent";
+    externalId: string | null;
+    externalLabel: string | null;
+    externalUrl: string | null;
+    description: string | null;
+    acceptanceCriteria: string | null;
+    repo: string;
+    baseBranch: string;
+    currentOwner: "developer" | "reviewer" | "human" | "system";
+    currentIntent: string | null;
+    developerAgentId: string | null;
+    reviewerAgentId: string | null;
+    maxReviewRounds: number;
+    currentRound: number;
+    maxInfraAttempts: number;
+    infraAttempts: number;
+    branch: string | null;
+    baseSha: string | null;
+    headSha: string | null;
+    prNumber: number | null;
+    prUrl: string | null;
+    autoMerge: boolean;
+}, {
+    status: "done" | "final_review" | "ready" | "developing" | "reviewing" | "repairing" | "needs_human" | "closed";
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    title: string;
+    source: "manual" | "linear" | "agent";
+    externalId: string | null;
+    externalLabel: string | null;
+    externalUrl: string | null;
+    description: string | null;
+    acceptanceCriteria: string | null;
+    repo: string;
+    baseBranch: string;
+    currentOwner: "developer" | "reviewer" | "human" | "system";
+    currentIntent: string | null;
+    developerAgentId: string | null;
+    reviewerAgentId: string | null;
+    maxReviewRounds: number;
+    currentRound: number;
+    maxInfraAttempts: number;
+    infraAttempts: number;
+    branch: string | null;
+    baseSha: string | null;
+    headSha: string | null;
+    prNumber: number | null;
+    prUrl: string | null;
+    autoMerge: boolean;
+}>;
+export type Issue = z.infer<typeof Issue>;
+export declare const CreateIssueInput: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    acceptanceCriteria: z.ZodOptional<z.ZodString>;
+    /** GitHub URL or `owner/repo` — normalized to `github.com/owner/repo` on parse. */
+    repo: z.ZodEffects<z.ZodString, string, string>;
+    baseBranch: z.ZodDefault<z.ZodString>;
+    developerAgentId: z.ZodString;
+    reviewerAgentId: z.ZodString;
+    maxReviewRounds: z.ZodDefault<z.ZodNumber>;
+    maxInfraAttempts: z.ZodDefault<z.ZodNumber>;
+    /** Kick UI sends true; omit/false preserves final_review after approve. */
+    autoMerge: z.ZodDefault<z.ZodBoolean>;
+    source: z.ZodDefault<z.ZodEnum<["manual", "linear", "agent"]>>;
+    externalId: z.ZodOptional<z.ZodString>;
+    externalLabel: z.ZodOptional<z.ZodString>;
+    externalUrl: z.ZodOptional<z.ZodString>;
+    /**
+     * NOT-118: a create directive, not an issue field — the route enqueues the new issue for
+     * admission by default so creating one never starts a workflow behind the queue's back.
+     * `false` creates a draft that sits outside the queue until someone adds or starts it.
+     */
+    enqueue: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    source: "manual" | "linear" | "agent";
+    repo: string;
+    baseBranch: string;
+    developerAgentId: string;
+    reviewerAgentId: string;
+    maxReviewRounds: number;
+    maxInfraAttempts: number;
+    autoMerge: boolean;
+    enqueue: boolean;
+    externalId?: string | undefined;
+    externalLabel?: string | undefined;
+    externalUrl?: string | undefined;
+    description?: string | undefined;
+    acceptanceCriteria?: string | undefined;
+}, {
+    title: string;
+    repo: string;
+    developerAgentId: string;
+    reviewerAgentId: string;
+    source?: "manual" | "linear" | "agent" | undefined;
+    externalId?: string | undefined;
+    externalLabel?: string | undefined;
+    externalUrl?: string | undefined;
+    description?: string | undefined;
+    acceptanceCriteria?: string | undefined;
+    baseBranch?: string | undefined;
+    maxReviewRounds?: number | undefined;
+    maxInfraAttempts?: number | undefined;
+    autoMerge?: boolean | undefined;
+    enqueue?: boolean | undefined;
+}>;
+/** Wire/API body shape — defaults applied by `CreateIssueInput.parse` / repository. */
+export type CreateIssueInput = z.input<typeof CreateIssueInput>;
+/** Pre-start (or parked-on-`needs_human`) edits only — the route enforces no active
+ * workflow instance; status/owner/intent/branch/SHA/PR stay coordinator-owned. */
+export declare const UpdateIssueInput: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    acceptanceCriteria: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    repo: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    developerAgentId: z.ZodOptional<z.ZodString>;
+    reviewerAgentId: z.ZodOptional<z.ZodString>;
+    maxReviewRounds: z.ZodOptional<z.ZodNumber>;
+    maxInfraAttempts: z.ZodOptional<z.ZodNumber>;
+    autoMerge: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    title?: string | undefined;
+    description?: string | null | undefined;
+    acceptanceCriteria?: string | null | undefined;
+    repo?: string | undefined;
+    baseBranch?: string | undefined;
+    developerAgentId?: string | undefined;
+    reviewerAgentId?: string | undefined;
+    maxReviewRounds?: number | undefined;
+    maxInfraAttempts?: number | undefined;
+    autoMerge?: boolean | undefined;
+}, {
+    title?: string | undefined;
+    description?: string | null | undefined;
+    acceptanceCriteria?: string | null | undefined;
+    repo?: string | undefined;
+    baseBranch?: string | undefined;
+    developerAgentId?: string | undefined;
+    reviewerAgentId?: string | undefined;
+    maxReviewRounds?: number | undefined;
+    maxInfraAttempts?: number | undefined;
+    autoMerge?: boolean | undefined;
+}>;
+export type UpdateIssueInput = z.infer<typeof UpdateIssueInput>;
+/**
+ * Guard rails only — which status the coordinator may move an issue to next.
+ * The *specific* target within an allowed set (e.g. which needs_human resolution
+ * leads where) is coordinator business logic, not encoded here, mirroring how
+ * VALID_TRANSITIONS works for the legacy RunStatus table today.
+ */
+export declare const ISSUE_STATUS_TRANSITIONS: Record<IssueStatus, IssueStatus[]>;
+export declare function canTransitionIssue(from: IssueStatus, to: IssueStatus): boolean;
+/**
+ * The statuses a pass can never leave — derived from the transition table so the two cannot
+ * drift. "Terminal" is a property of the *local* issue row, not of the upstream ticket: a
+ * closed dealer issue for a still-open Linear ticket is the normal case a re-import serves
+ * (NOT-141).
+ */
+export declare const TERMINAL_ISSUE_STATUSES: readonly IssueStatus[];
+/** Membership test for {@link TERMINAL_ISSUE_STATUSES} — false means the pass can still move. */
+export declare function isTerminalIssueStatus(status: IssueStatus): boolean;
+/**
+ * What the request did to the admission queue — the *mutation*, not the intent. `enqueue`
+ * is idempotent, so a re-import of an already-queued issue changes nothing; reporting that
+ * as "queued" is how the CLI came to announce a queue action for a request that queued
+ * nothing (NOT-141).
+ */
+export declare const QueueOutcome: z.ZodEnum<["enqueued", "already_queued", "not_queued"]>;
+export type QueueOutcome = z.infer<typeof QueueOutcome>;
+/**
+ * NOT-141: `POST /api/issues` answers with the issue *plus* what the server did with it.
+ * `created: false` means the request matched a live issue for the same `(source,
+ * externalId)` and re-enqueued it instead of making a second row — without these flags a
+ * caller cannot tell an import from a no-op, and the CLI printed "Queued for admission" for
+ * requests that queued nothing.
+ */
+export declare const CreateIssueResult: z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodEnum<["manual", "linear", "agent"]>;
+    externalId: z.ZodNullable<z.ZodString>;
+    externalLabel: z.ZodNullable<z.ZodString>;
+    externalUrl: z.ZodNullable<z.ZodString>;
+    title: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    acceptanceCriteria: z.ZodNullable<z.ZodString>;
+    /**
+     * Portable GitHub identity (`github.com/owner/repo`) for new issues (NOT-149).
+     * Legacy rows may still hold a local filesystem path until explicitly migrated —
+     * the coordinator resolves those via an explicit compatibility path, never by guessing.
+     */
+    repo: z.ZodString;
+    baseBranch: z.ZodString;
+    status: z.ZodEnum<["ready", "developing", "reviewing", "repairing", "final_review", "needs_human", "done", "closed"]>;
+    currentOwner: z.ZodEnum<["human", "developer", "reviewer", "system"]>;
+    currentIntent: z.ZodNullable<z.ZodString>;
+    developerAgentId: z.ZodNullable<z.ZodString>;
+    reviewerAgentId: z.ZodNullable<z.ZodString>;
+    maxReviewRounds: z.ZodNumber;
+    currentRound: z.ZodNumber;
+    /** 0 is a valid policy: no automatic infra retry, escalate to a human immediately. */
+    maxInfraAttempts: z.ZodNumber;
+    infraAttempts: z.ZodNumber;
+    branch: z.ZodNullable<z.ZodString>;
+    baseSha: z.ZodNullable<z.ZodString>;
+    headSha: z.ZodNullable<z.ZodString>;
+    prNumber: z.ZodNullable<z.ZodNumber>;
+    prUrl: z.ZodNullable<z.ZodString>;
+    /**
+     * When true, reviewer `approved` merges the PR and marks the issue done (skips
+     * `final_review`). Kick UI defaults this on; API/CLI omit → false so existing
+     * callers keep the human final-review path.
+     */
+    autoMerge: z.ZodBoolean;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+} & {
+    created: z.ZodBoolean;
+    queue: z.ZodEnum<["enqueued", "already_queued", "not_queued"]>;
+    /**
+     * How many issues already existed for this `(source, externalId)` before the request (0
+     * for a manual create). With `created: true` they are all terminal, so a non-zero count
+     * means this import opened a *second* pass on a ticket dealer has already finished once —
+     * callers should say that out loud instead of presenting it as a first import.
+     */
+    priorPasses: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    status: "done" | "final_review" | "ready" | "developing" | "reviewing" | "repairing" | "needs_human" | "closed";
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    title: string;
+    source: "manual" | "linear" | "agent";
+    externalId: string | null;
+    externalLabel: string | null;
+    externalUrl: string | null;
+    description: string | null;
+    acceptanceCriteria: string | null;
+    repo: string;
+    baseBranch: string;
+    currentOwner: "developer" | "reviewer" | "human" | "system";
+    currentIntent: string | null;
+    developerAgentId: string | null;
+    reviewerAgentId: string | null;
+    maxReviewRounds: number;
+    currentRound: number;
+    maxInfraAttempts: number;
+    infraAttempts: number;
+    branch: string | null;
+    baseSha: string | null;
+    headSha: string | null;
+    prNumber: number | null;
+    prUrl: string | null;
+    autoMerge: boolean;
+    created: boolean;
+    queue: "enqueued" | "already_queued" | "not_queued";
+    priorPasses: number;
+}, {
+    status: "done" | "final_review" | "ready" | "developing" | "reviewing" | "repairing" | "needs_human" | "closed";
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    title: string;
+    source: "manual" | "linear" | "agent";
+    externalId: string | null;
+    externalLabel: string | null;
+    externalUrl: string | null;
+    description: string | null;
+    acceptanceCriteria: string | null;
+    repo: string;
+    baseBranch: string;
+    currentOwner: "developer" | "reviewer" | "human" | "system";
+    currentIntent: string | null;
+    developerAgentId: string | null;
+    reviewerAgentId: string | null;
+    maxReviewRounds: number;
+    currentRound: number;
+    maxInfraAttempts: number;
+    infraAttempts: number;
+    branch: string | null;
+    baseSha: string | null;
+    headSha: string | null;
+    prNumber: number | null;
+    prUrl: string | null;
+    autoMerge: boolean;
+    created: boolean;
+    queue: "enqueued" | "already_queued" | "not_queued";
+    priorPasses: number;
+}>;
+export type CreateIssueResult = z.infer<typeof CreateIssueResult>;
+/** 409 body when a re-import collides with a live issue — mirrors the runs promote path. */
+export interface ExistingIssueConflict {
+    error: string;
+    existingIssueId: string;
+    existingIssueStatus: IssueStatus;
+}
+/**
+ * Issue-scoped artifact. Distinct from the legacy run-scoped `Artifact`: it is keyed
+ * by `issueId` (+ optional `workerSessionId`), never a `runId`, so it validates on its
+ * own terms rather than failing `Artifact.runId`'s UUID check.
+ */
+export declare const IssueArtifact: z.ZodObject<{
+    id: z.ZodString;
+    issueId: z.ZodNullable<z.ZodString>;
+    workerSessionId: z.ZodNullable<z.ZodString>;
+    kind: z.ZodString;
+    contentJson: z.ZodNullable<z.ZodString>;
+    blobPath: z.ZodNullable<z.ZodString>;
+    author: z.ZodEnum<["human", "agent", "system"]>;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    issueId: string | null;
+    createdAt: string;
+    workerSessionId: string | null;
+    kind: string;
+    contentJson: string | null;
+    blobPath: string | null;
+    author: "human" | "system" | "agent";
+}, {
+    id: string;
+    issueId: string | null;
+    createdAt: string;
+    workerSessionId: string | null;
+    kind: string;
+    contentJson: string | null;
+    blobPath: string | null;
+    author: "human" | "system" | "agent";
+}>;
+export type IssueArtifact = z.infer<typeof IssueArtifact>;

package/bundle/shared/dist/issues.js

@@ -0,0 +1,169 @@
+import { z } from "zod";
+import { GitHubRepoInput } from "./github-repo.js";
+export const IssueStatus = z.enum([
+    "ready",
+    "developing",
+    "reviewing",
+    "repairing",
+    "final_review",
+    "needs_human",
+    "done",
+    "closed",
+]);
+export const IssueOwner = z.enum(["human", "developer", "reviewer", "system"]);
+/** "agent" covers an issue a coding agent created via the API/CLI (PRD §5). */
+export const IssueSource = z.enum(["manual", "linear", "agent"]);
+export const Issue = z.object({
+    id: z.string().uuid(),
+    source: IssueSource,
+    externalId: z.string().nullable(),
+    externalLabel: z.string().nullable(),
+    externalUrl: z.string().nullable(),
+    title: z.string(),
+    description: z.string().nullable(),
+    acceptanceCriteria: z.string().nullable(),
+    /**
+     * Portable GitHub identity (`github.com/owner/repo`) for new issues (NOT-149).
+     * Legacy rows may still hold a local filesystem path until explicitly migrated —
+     * the coordinator resolves those via an explicit compatibility path, never by guessing.
+     */
+    repo: z.string(),
+    baseBranch: z.string(),
+    status: IssueStatus,
+    currentOwner: IssueOwner,
+    currentIntent: z.string().nullable(),
+    developerAgentId: z.string().uuid().nullable(),
+    reviewerAgentId: z.string().uuid().nullable(),
+    maxReviewRounds: z.number().int().min(1),
+    currentRound: z.number().int().min(1),
+    /** 0 is a valid policy: no automatic infra retry, escalate to a human immediately. */
+    maxInfraAttempts: z.number().int().min(0),
+    infraAttempts: z.number().int().min(0),
+    branch: z.string().nullable(),
+    baseSha: z.string().nullable(),
+    headSha: z.string().nullable(),
+    prNumber: z.number().int().nullable(),
+    prUrl: z.string().nullable(),
+    /**
+     * When true, reviewer `approved` merges the PR and marks the issue done (skips
+     * `final_review`). Kick UI defaults this on; API/CLI omit → false so existing
+     * callers keep the human final-review path.
+     */
+    autoMerge: z.boolean(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const CreateIssueInput = z.object({
+    title: z.string().min(1),
+    description: z.string().optional(),
+    acceptanceCriteria: z.string().optional(),
+    /** GitHub URL or `owner/repo` — normalized to `github.com/owner/repo` on parse. */
+    repo: GitHubRepoInput,
+    baseBranch: z.string().min(1).default("main"),
+    developerAgentId: z.string().uuid(),
+    reviewerAgentId: z.string().uuid(),
+    maxReviewRounds: z.number().int().min(1).default(3),
+    maxInfraAttempts: z.number().int().min(0).default(3),
+    /** Kick UI sends true; omit/false preserves final_review after approve. */
+    autoMerge: z.boolean().default(false),
+    source: IssueSource.default("manual"),
+    externalId: z.string().optional(),
+    externalLabel: z.string().optional(),
+    externalUrl: z.string().optional(),
+    /**
+     * NOT-118: a create directive, not an issue field — the route enqueues the new issue for
+     * admission by default so creating one never starts a workflow behind the queue's back.
+     * `false` creates a draft that sits outside the queue until someone adds or starts it.
+     */
+    enqueue: z.boolean().default(true),
+});
+/** Pre-start (or parked-on-`needs_human`) edits only — the route enforces no active
+ * workflow instance; status/owner/intent/branch/SHA/PR stay coordinator-owned. */
+export const UpdateIssueInput = z.object({
+    title: z.string().min(1).optional(),
+    description: z.string().nullable().optional(),
+    acceptanceCriteria: z.string().nullable().optional(),
+    repo: GitHubRepoInput.optional(),
+    baseBranch: z.string().min(1).optional(),
+    developerAgentId: z.string().uuid().optional(),
+    reviewerAgentId: z.string().uuid().optional(),
+    maxReviewRounds: z.number().int().min(1).optional(),
+    maxInfraAttempts: z.number().int().min(0).optional(),
+    autoMerge: z.boolean().optional(),
+});
+/**
+ * Guard rails only — which status the coordinator may move an issue to next.
+ * The *specific* target within an allowed set (e.g. which needs_human resolution
+ * leads where) is coordinator business logic, not encoded here, mirroring how
+ * VALID_TRANSITIONS works for the legacy RunStatus table today.
+ */
+export const ISSUE_STATUS_TRANSITIONS = {
+    ready: ["developing", "closed"],
+    developing: ["developing", "reviewing", "needs_human", "closed"],
+    // Self-loop matches developing/repairing below: a stale-review retry re-queues a fresh
+    // reviewer at a newly verified head without leaving the "reviewing" stage.
+    reviewing: ["reviewing", "repairing", "final_review", "needs_human", "closed"],
+    repairing: ["repairing", "reviewing", "needs_human", "closed"],
+    // "reviewing" lets a reviewer-side infra escalation (session_failed/publish_failed
+    // exhausted) resume with a fresh reviewer session at the still-valid pinned head,
+    // instead of always routing back through the developer.
+    needs_human: ["developing", "reviewing", "repairing", "final_review", "done", "closed"],
+    // Self-loop: human complete parks owner/intent for undraft+merge without leaving the stage.
+    final_review: ["final_review", "done", "repairing", "needs_human", "closed"],
+    done: [],
+    closed: [],
+};
+export function canTransitionIssue(from, to) {
+    return ISSUE_STATUS_TRANSITIONS[from].includes(to);
+}
+/**
+ * The statuses a pass can never leave — derived from the transition table so the two cannot
+ * drift. "Terminal" is a property of the *local* issue row, not of the upstream ticket: a
+ * closed dealer issue for a still-open Linear ticket is the normal case a re-import serves
+ * (NOT-141).
+ */
+export const TERMINAL_ISSUE_STATUSES = Object.keys(ISSUE_STATUS_TRANSITIONS).filter((status) => ISSUE_STATUS_TRANSITIONS[status].length === 0);
+/** Membership test for {@link TERMINAL_ISSUE_STATUSES} — false means the pass can still move. */
+export function isTerminalIssueStatus(status) {
+    return TERMINAL_ISSUE_STATUSES.includes(status);
+}
+/**
+ * What the request did to the admission queue — the *mutation*, not the intent. `enqueue`
+ * is idempotent, so a re-import of an already-queued issue changes nothing; reporting that
+ * as "queued" is how the CLI came to announce a queue action for a request that queued
+ * nothing (NOT-141).
+ */
+export const QueueOutcome = z.enum(["enqueued", "already_queued", "not_queued"]);
+/**
+ * NOT-141: `POST /api/issues` answers with the issue *plus* what the server did with it.
+ * `created: false` means the request matched a live issue for the same `(source,
+ * externalId)` and re-enqueued it instead of making a second row — without these flags a
+ * caller cannot tell an import from a no-op, and the CLI printed "Queued for admission" for
+ * requests that queued nothing.
+ */
+export const CreateIssueResult = Issue.extend({
+    created: z.boolean(),
+    queue: QueueOutcome,
+    /**
+     * How many issues already existed for this `(source, externalId)` before the request (0
+     * for a manual create). With `created: true` they are all terminal, so a non-zero count
+     * means this import opened a *second* pass on a ticket dealer has already finished once —
+     * callers should say that out loud instead of presenting it as a first import.
+     */
+    priorPasses: z.number().int().min(0),
+});
+/**
+ * Issue-scoped artifact. Distinct from the legacy run-scoped `Artifact`: it is keyed
+ * by `issueId` (+ optional `workerSessionId`), never a `runId`, so it validates on its
+ * own terms rather than failing `Artifact.runId`'s UUID check.
+ */
+export const IssueArtifact = z.object({
+    id: z.string(),
+    issueId: z.string().nullable(),
+    workerSessionId: z.string().nullable(),
+    kind: z.string(),
+    contentJson: z.string().nullable(),
+    blobPath: z.string().nullable(),
+    author: z.enum(["human", "agent", "system"]),
+    createdAt: z.string(),
+});

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

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