mergestorm 0.3.9 → 0.3.13

package/dist/commands/status.js

@@ -1,28 +1,228 @@
-import { apiFetch } from "../api.js";
+import { getReview } from "../api.js";
 import { loadConfig } from "../config.js";
-import { CommandError } from "../errors.js";
+import { CommandError, DetachedError, REVIEW_EXIT, isCommandErrorCode, } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
 import { renderFindings } from "../ui/findings.js";
-export async function cmdStatus(jobId, opts = {}) {
-    const format = opts.format ?? "json";
-    const cfg = await loadConfig();
-    const { status, body } = await apiFetch(cfg, `/api/v1/reviews/${jobId}`, {
-        signal: opts.signal,
+import { toReviewJobEnvelope, } from "../ui/job-envelope.js";
+import { REVIEW_POLL_DEFAULT_TIMEOUT_MS, ReviewPollTimeoutError, pollReview, } from "./review-client.js";
+const STATUS_USAGE = "usage: mergestorm status <job_id> [--json] [--wait] [--timeout seconds]";
+function usageError(message = STATUS_USAGE) {
+    return new CommandError(message, REVIEW_EXIT.usage, "usage");
+}
+export function parseStatusArgs(args, defaults = { format: "json" }) {
+    let jobId;
+    let format = defaults.format;
+    let wait = false;
+    let timeoutMs = REVIEW_POLL_DEFAULT_TIMEOUT_MS;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--json") {
+            format = "json";
+            continue;
+        }
+        if (a === "--pretty") {
+            format = "pretty";
+            continue;
+        }
+        if (a === "--wait") {
+            wait = true;
+            continue;
+        }
+        if (a === "--no-wait") {
+            wait = false;
+            continue;
+        }
+        if (a === "--timeout" || a.startsWith("--timeout=")) {
+            const value = a === "--timeout" ? args[++i] : a.slice("--timeout=".length);
+            const seconds = Number(value);
+            if (!value || !Number.isFinite(seconds) || seconds <= 0) {
+                throw usageError("--timeout must be a positive number of seconds");
+            }
+            timeoutMs = Math.round(seconds * 1_000);
+            wait = true;
+            continue;
+        }
+        if (a.startsWith("-")) {
+            throw usageError(`unknown flag: ${a}`);
+        }
+        if (jobId)
+            throw usageError();
+        jobId = a;
+    }
+    if (!jobId)
+        throw usageError();
+    return { jobId, format, wait, timeoutMs };
+}
+function printPretty(row) {
+    const envelope = toReviewJobEnvelope(row);
+    console.log(`Status:  ${envelope.status}`);
+    if (envelope.verdict)
+        console.log(`Verdict: ${ansi.bold(envelope.verdict)}`);
+    if (envelope.router_mode)
+        console.log(`Router:  ${envelope.router_mode}`);
+    if (envelope.specialists_requested.length > 0) {
+        console.log(`Requested: ${envelope.specialists_requested.join(", ")}`);
+    }
+    if (envelope.specialists_run.length > 0) {
+        console.log(`Run:       ${envelope.specialists_run.join(", ")}`);
+    }
+    if (envelope.credits) {
+        console.log(`Credits:   ${envelope.credits.standard} standard`);
+    }
+    if (envelope.summary)
+        console.log(envelope.summary);
+    if (envelope.error)
+        console.log(ansi.red(`Error: ${envelope.error}`));
+    renderFindings(envelope.findings, {
+        emptyMessage: envelope.status === "completed",
+    });
+}
+export async function cmdStatus(args, opts = {}) {
+    const parsed = parseStatusArgs(args, {
+        format: opts.defaultFormat ?? "json",
     });
-    if (status !== 200) {
-        throw new CommandError(JSON.stringify(body, null, 2));
+    const json = parsed.format === "json";
+    const interactive = Boolean(opts.interactive && !json);
+    const fallback = { jobId: parsed.jobId };
+    let jsonPrinted = false;
+    const printJson = (row, extra = {}) => {
+        console.log(JSON.stringify(toReviewJobEnvelope(row, { ...fallback, ...extra })));
+        jsonPrinted = true;
+    };
+    try {
+        const cfg = await loadConfig();
+        if (!parsed.wait) {
+            let body;
+            try {
+                body = await getReview(parsed.jobId, cfg, { signal: opts.signal });
+            }
+            catch (err) {
+                if (err instanceof CommandError &&
+                    (err.code === "auth_invalid" || err.code === "missing_api_key")) {
+                    throw err;
+                }
+                if (err instanceof Error && err.name === "AbortError")
+                    throw err;
+                if (isCommandErrorCode(err, "api_timeout")) {
+                    if (json)
+                        printJson(null, { status: "in_progress", error: err.message });
+                    throw new CommandError(err.message, REVIEW_EXIT.timeout, "review_timeout");
+                }
+                if (isCommandErrorCode(err, "rate_limited")) {
+                    if (json) {
+                        printJson(null, {
+                            status: "rate_limited",
+                            error: err.message,
+                            retryAfterSeconds: err.retryAfterSeconds,
+                        });
+                    }
+                    else {
+                        console.log(`Status:  rate_limited`);
+                        console.log(err.message);
+                    }
+                    throw err;
+                }
+                throw new CommandError(err instanceof Error ? err.message : String(err), REVIEW_EXIT.failed, "review_failed");
+            }
+            const row = body && typeof body === "object"
+                ? { ...body, job_id: parsed.jobId }
+                : { job_id: parsed.jobId, status: "failed", error: "Invalid review response" };
+            if (row.status === "failed" || row.status === "quota_exceeded") {
+                if (json)
+                    printJson(row);
+                else
+                    printPretty(row);
+                throw new CommandError(`Review ${row.status}: ${row.error ?? ""}`, row.status === "quota_exceeded" ? REVIEW_EXIT.quota : REVIEW_EXIT.failed, row.status === "quota_exceeded" ? "review_quota" : "review_failed");
+            }
+            if (json)
+                printJson(row);
+            else
+                printPretty(row);
+            return;
+        }
+        if (!json) {
+            const waitHint = interactive
+                ? ` Waiting… (${ansi.dim("ctrl+c to detach — job keeps running")})`
+                : " Waiting…";
+            console.log(`Job ${parsed.jobId}.${waitHint}`);
+        }
+        let row;
+        try {
+            row = await pollReview(cfg, parsed.jobId, {
+                timeoutMs: parsed.timeoutMs,
+                intervalMs: opts.pollIntervalMs,
+                signal: opts.signal,
+                propagateTimeout: interactive,
+                onTick(kind) {
+                    if (json)
+                        console.error(kind === "retry" ? "?" : ".");
+                    else
+                        process.stdout.write(kind === "retry" ? "?" : ".");
+                },
+            });
+        }
+        catch (err) {
+            if (opts.interactive && err instanceof Error && err.name === "AbortError") {
+                throw new DetachedError(parsed.jobId);
+            }
+            if (interactive && isCommandErrorCode(err, "api_timeout")) {
+                throw new DetachedError(parsed.jobId);
+            }
+            if (err instanceof ReviewPollTimeoutError) {
+                const message = `Timed out waiting for review ${parsed.jobId}`;
+                if (json) {
+                    printJson(err.lastRow, {
+                        jobId: parsed.jobId,
+                        status: err.lastRow.status ?? "in_progress",
+                        error: "Timed out waiting for review.",
+                    });
+                }
+                throw new CommandError(message, REVIEW_EXIT.timeout, "review_timeout");
+            }
+            if (isCommandErrorCode(err, "rate_limited")) {
+                if (json) {
+                    printJson(null, {
+                        status: "rate_limited",
+                        error: err.message,
+                        retryAfterSeconds: err.retryAfterSeconds,
+                    });
+                }
+                else {
+                    console.log(`Status:  rate_limited`);
+                    console.log(err.message);
+                }
+                throw err;
+            }
+            throw err;
+        }
+        if (!json)
+            console.log("");
+        if (row.status === "failed" || row.status === "quota_exceeded") {
+            const message = `Review ${row.status}: ${row.error ?? ""}`;
+            if (json)
+                printJson(row);
+            else
+                printPretty(row);
+            throw new CommandError(message, row.status === "quota_exceeded" ? REVIEW_EXIT.quota : REVIEW_EXIT.failed, row.status === "quota_exceeded" ? "review_quota" : "review_failed");
+        }
+        if (json)
+            printJson(row);
+        else
+            printPretty(row);
     }
-    if (format === "json") {
-        console.log(JSON.stringify(body, null, 2));
-        return;
+    catch (err) {
+        if (err instanceof DetachedError)
+            throw err;
+        if (json &&
+            !jsonPrinted &&
+            !(err instanceof Error && err.name === "AbortError")) {
+            const message = err instanceof Error ? err.message : String(err);
+            printJson(null, { status: "failed", error: message });
+        }
+        if (err instanceof CommandError &&
+            (err.code === "auth_invalid" || err.code === "missing_api_key")) {
+            throw new CommandError(err.message, REVIEW_EXIT.auth, err.code);
+        }
+        throw err;
     }
-    const row = body;
-    console.log(`Status:  ${row.status}`);
-    if (row.verdict)
-        console.log(`Verdict: ${ansi.bold(row.verdict)}`);
-    if (row.summary)
-        console.log(row.summary);
-    if (row.error)
-        console.log(ansi.red(`Error: ${row.error}`));
-    renderFindings(row.findings, { emptyMessage: row.status === "completed" });
 }

package/dist/errors.d.ts

@@ -2,13 +2,29 @@
  * Stable machine codes for CommandError control flow.
  * UX copy in `message` may change freely; match on `code`, never on message text.
  */
-export type CommandErrorCode = "auth_invalid" | "api_timeout" | "not_a_repo" | "missing_api_key";
+export type CommandErrorCode = "auth_invalid" | "api_timeout" | "not_a_repo" | "missing_api_key" | "registered_parent" | "usage" | "review_quota" | "review_failed" | "review_timeout" | "rate_limited";
+/** Stable one-shot exit codes for machine callers of `mergestorm review`. */
+export declare const REVIEW_EXIT: {
+    readonly success: 0;
+    readonly usage: 2;
+    readonly quota: 3;
+    readonly failed: 4;
+    readonly timeout: 5;
+    readonly auth: 6;
+    readonly rate_limited: 7;
+};
+export type CommandErrorExtras = {
+    retryAfterSeconds?: number;
+};
 /** Thrown by command handlers; one-shot mode maps `exitCode` onto process.exitCode. */
 export declare class CommandError extends Error {
     readonly exitCode: number;
     readonly code?: CommandErrorCode;
-    constructor(message: string, exitCode?: number, code?: CommandErrorCode);
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, exitCode?: number, code?: CommandErrorCode, extras?: CommandErrorExtras);
 }
+export declare const RATE_LIMITED_HINT = "Rate limited. Wait for a running review or mergestorm jobs.";
+export declare function rateLimitedMessage(retryAfterSeconds?: number): string;
 export declare function isCommandErrorCode(err: unknown, code: CommandErrorCode): err is CommandError;
 /** Review/status poll aborted by Ctrl+C — shell returns to the prompt. */
 export declare class DetachedError extends Error {

package/dist/errors.js

@@ -1,14 +1,35 @@
+/** Stable one-shot exit codes for machine callers of `mergestorm review`. */
+export const REVIEW_EXIT = {
+    success: 0,
+    usage: 2,
+    quota: 3,
+    failed: 4,
+    timeout: 5,
+    auth: 6,
+    rate_limited: 7,
+};
 /** Thrown by command handlers; one-shot mode maps `exitCode` onto process.exitCode. */
 export class CommandError extends Error {
     exitCode;
     code;
-    constructor(message, exitCode = 1, code) {
+    retryAfterSeconds;
+    constructor(message, exitCode = 1, code, extras) {
         super(message);
         this.name = "CommandError";
         this.exitCode = exitCode;
         this.code = code;
+        if (extras?.retryAfterSeconds !== undefined) {
+            this.retryAfterSeconds = extras.retryAfterSeconds;
+        }
     }
 }
+export const RATE_LIMITED_HINT = "Rate limited. Wait for a running review or mergestorm jobs.";
+export function rateLimitedMessage(retryAfterSeconds) {
+    if (retryAfterSeconds == null || !Number.isFinite(retryAfterSeconds)) {
+        return RATE_LIMITED_HINT;
+    }
+    return `${RATE_LIMITED_HINT} Retry after ${Math.ceil(retryAfterSeconds)}s.`;
+}
 export function isCommandErrorCode(err, code) {
     return err instanceof CommandError && err.code === code;
 }

package/dist/git-stack.d.ts

@@ -23,6 +23,8 @@ export declare function defaultLayerBranchName(explicit?: string): string;
  * (`git rev-list --count base..head`). Used by stack submit to refuse empty layers.
  */
 export declare function commitsAheadOf(base: string, head: string, cwd?: string): number;
+/** Fetch one remote branch so submit can count commits ahead of a park freeze. */
+export declare function fetchRemoteBranch(name: string, cwd?: string): void;
 /** Push branch to origin and set upstream. */
 export declare function pushBranch(branch: string, cwd?: string): void;
 /** First line of the tip commit on `branch` (for PR title). */

package/dist/git-stack.js

@@ -107,6 +107,10 @@ export function commitsAheadOf(base, head, cwd = process.cwd()) {
     }
     return n;
 }
+/** Fetch one remote branch so submit can count commits ahead of a park freeze. */
+export function fetchRemoteBranch(name, cwd = process.cwd()) {
+    git(["fetch", "origin", name], cwd);
+}
 /** Push branch to origin and set upstream. */
 export function pushBranch(branch, cwd = process.cwd()) {
     try {

package/dist/git.d.ts

@@ -4,7 +4,18 @@ export declare function parseGithubOriginRepo(cwd?: string): {
     owner: string;
     repo: string;
 } | null;
-export declare function collectChangedFiles(base: string, head: string, cwd?: string): Promise<{
+/**
+ * Repo-root absolute path for the current working tree.
+ * Kept local (not imported from repo-identity) to avoid a git ↔ repo-identity cycle.
+ */
+export declare function repoRoot(cwd?: string): string;
+/**
+ * Repo-root-relative names of files changed between base and head that resolve
+ * inside the sandbox root. Bounds both the uploaded file contents and the diff
+ * itself to the sandbox so tracked files outside it never reach the API.
+ */
+export declare function changedNamesInSandbox(base: string, head: string, cwd?: string, sandboxRoot?: string): Promise<string[]>;
+export declare function collectChangedFiles(base: string, head: string, cwd?: string, sandboxRoot?: string): Promise<{
     path: string;
     content: string;
 }[]>;

package/dist/git.js

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { readFile, stat } from "node:fs/promises";
+import { readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 export function git(args, cwd = process.cwd()) {
     try {
@@ -33,15 +33,61 @@ export function parseGithubOriginRepo(cwd = process.cwd()) {
  * Repo-root absolute path for the current working tree.
  * Kept local (not imported from repo-identity) to avoid a git ↔ repo-identity cycle.
  */
-function repoRoot(cwd = process.cwd()) {
+export function repoRoot(cwd = process.cwd()) {
     return realpathSync(git(["rev-parse", "--show-toplevel"], cwd).trim());
 }
-export async function collectChangedFiles(base, head, cwd = process.cwd()) {
+/**
+ * Repo-root-relative names of files changed between base and head that resolve
+ * inside the sandbox root. Bounds both the uploaded file contents and the diff
+ * itself to the sandbox so tracked files outside it never reach the API.
+ */
+export async function changedNamesInSandbox(base, head, cwd = process.cwd(), sandboxRoot) {
     const root = repoRoot(cwd);
-    const names = git(["diff", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd)
-        .split("\n")
-        .map((s) => s.trim())
+    const bound = sandboxRoot ? await realpath(path.resolve(sandboxRoot)) : root;
+    // D/T are included so deletions and type changes stay in the review diff,
+    // even though their contents cannot be read from the working tree for upload.
+    // -z disables core.quotePath quoting and NUL-terminates names, so paths with
+    // spaces or non-ASCII characters survive the split verbatim.
+    const names = git(["diff", "--name-only", "-z", "--diff-filter=ACMRDT", `${base}...${head}`], cwd)
+        .split("\0")
         .filter(Boolean);
+    const kept = [];
+    for (const name of names) {
+        const abs = path.join(root, name);
+        let real;
+        try {
+            real = await realpath(abs);
+        }
+        catch {
+            // Deleted from the working tree: resolve the nearest existing ancestor so
+            // the path can still be bounded against the sandbox for the diff pathspec.
+            let ancestor = path.dirname(abs);
+            let realAncestor;
+            while (!realAncestor) {
+                try {
+                    realAncestor = await realpath(ancestor);
+                }
+                catch {
+                    const up = path.dirname(ancestor);
+                    if (up === ancestor)
+                        throw new Error(`cannot resolve ${abs}`);
+                    ancestor = up;
+                }
+            }
+            real = path.join(realAncestor, path.relative(ancestor, abs));
+        }
+        const relToBound = path.relative(bound, real);
+        if (relToBound === ".." || relToBound.startsWith(`..${path.sep}`)) {
+            console.warn(`Warning: skipping ${name} for review upload: it resolves outside the ${sandboxRoot ? "sandbox root" : "repo root"}`);
+            continue;
+        }
+        kept.push(name);
+    }
+    return kept;
+}
+export async function collectChangedFiles(base, head, cwd = process.cwd(), sandboxRoot) {
+    const root = repoRoot(cwd);
+    const names = await changedNamesInSandbox(base, head, cwd, sandboxRoot);
     const files = [];
     for (const name of names.slice(0, 40)) {
         const abs = path.join(root, name);
@@ -53,7 +99,6 @@ export async function collectChangedFiles(base, head, cwd = process.cwd()) {
             files.push({ path: name, content });
         }
         catch {
-            // deleted or unreadable — do not silently drop without a hint
             console.warn(`Warning: could not read ${name} for review upload (resolved from repo root); skipping file contents`);
         }
     }

package/dist/shell.d.ts

@@ -1,4 +1,4 @@
-/** Shell autocomplete + `/help` — derived from the command registry (STRUCT-01). */
+/** Shell autocomplete + `/help` � derived from the command registry (STRUCT-01). */
 export declare const COMMANDS: import("./ui/prompt.js").CommandSpec[];
 /** Strips an optional leading "/" so both "review" and "/review" work. */
 export declare function parseLine(line: string): {

package/dist/shell.js

@@ -5,11 +5,14 @@ import { dispatchCommand, shellCommandSpecs, } from "./commands/registry.js";
 import { ansi } from "./ui/ansi.js";
 import { printBannerHeader, shellPrompt } from "./ui/banner.js";
 import { CTRL_C_EXIT_HINT, CtrlCExitGate } from "./ui/ctrl-c-exit.js";
-import { askLine, PromptClosedError } from "./ui/prompt.js";
-/** Shell autocomplete + `/help` — derived from the command registry (STRUCT-01). */
+import { askLine, formatSlashLabel, PromptClosedError } from "./ui/prompt.js";
+/** Shell autocomplete + `/help` � derived from the command registry (STRUCT-01). */
 export const COMMANDS = shellCommandSpecs();
 function printHelp() {
-    const rows = COMMANDS.map((c) => `  ${ansi.green("/" + c.name.padEnd(10))} ${c.summary}`).join("\n");
+    const rows = COMMANDS.map((c) => {
+        const label = formatSlashLabel(c).slice(1);
+        return `  ${ansi.green("/" + label.padEnd(20))} ${c.summary}`;
+    }).join("\n");
     console.log(`
   ${ansi.bold("Commands")}
 ${rows}

package/dist/stack-dto.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Wire types returned by the stack list/enrich HTTP endpoints.
+ *
+ * `api/src/stacks.ts#loadStackDtos` is the producer. Keep this file
+ * dependency-free and byte-for-byte aligned with the canonical wire contract.
+ */
+export type StackBranchState = "clean" | "needs_restack" | "restacking" | "conflict" | "merged" | "closed";
+export type StackCiStatus = "success" | "pending" | "failure" | "neutral" | "none" | "unknown";
+export type StackReviewStatus = "approved" | "changes_requested" | "reviewed" | "failed" | "none" | "unknown";
+/** `failed` is the newest Vortex `pr_reviews` row. Work paints Review failed. */
+export type StackVortexStatus = "reviewing" | "seam_pending" | "all_clear" | "findings" | "throttled" | "failed";
+export type StackCycloneStatus = "patching" | "awaiting_fix";
+export type StackTempestStatus = "reviewing" | "findings" | "clear" | "failed" | "stale";
+export type StackAgentName = "vortex" | "cyclone" | "tempest";
+/**
+ * One live-or-resting agent run for a PR (#1119): a dumb projection of one
+ * ledger row (webhook job / lease / review-state / pr_reviews). Two live
+ * Vortex jobs on two SHAs → two runs → two chips. Carries only safe facts —
+ * never job ids, holders, or error strings.
+ */
+export type StackAgentRun = {
+    agent: StackAgentName;
+    /** Agent-specific status, e.g. "reviewing" / "patching" / "all_clear". */
+    status: string;
+    /** Full SHA when known. UI shortens to 7. */
+    sha: string | null;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    /**
+     * Vortex in-flight sub-state from pr_reviews.phase (#1189): "fanout" while
+     * Core + specialists run in parallel, "synthesizing" during consolidation.
+     * Only on live `reviewing` runs; unknown values fall back to plain Reviewing.
+     */
+    phase?: string | null;
+    /**
+     * Actionable finding count from the latest `pr_reviews.findings` payload
+     * (#1248). Info-only notes (Continue, Decision required) are excluded.
+     * Only on resting Vortex `findings` runs.
+     */
+    findingCount?: number | null;
+};
+export type StackLayerChecks = {
+    total: number;
+    success: number;
+    pending: number;
+    failure: number;
+    failingName: string | null;
+};
+/** Closing / Development-sidebar issue. Cap 3 on the wire. */
+export type StackLinkedIssue = {
+    number: number;
+    title: string | null;
+};
+/** Cyclone merge-conflict specialist resolution for this PR (#973). */
+export type StackLayerConflictResolution = {
+    resolvedAt: string;
+    /** Branch the conflicts were resolved against (stacks parent or GitHub base). */
+    baseBranch: string | null;
+    /** Conflicted paths the specialist resolved; the writer caps the list. */
+    files: string[];
+    /** Head commit of the pushed resolution, when known. */
+    headSha: string | null;
+    /**
+     * Chat dispatch that triggered the run (#973). Traces a mark to the job that
+     * pushed it; null when the row predates dispatch tracing (or had no job).
+     */
+    dispatchId: string | null;
+};
+export type StackLayerDto = {
+    branch: string;
+    parentBranch: string | null;
+    prNumber: number;
+    position: number;
+    state: StackBranchState;
+    title: string | null;
+    htmlUrl: string | null;
+    ciStatus: StackCiStatus;
+    reviewStatus: StackReviewStatus;
+    checks: StackLayerChecks | null;
+    /** null on the fast list or when no Vortex/seam signal exists. */
+    vortexStatus: StackVortexStatus | null;
+    /** null on the fast list or when no Cyclone signal exists. */
+    cycloneStatus: StackCycloneStatus | null;
+    /** null when no Tempest signal exists. Fast list and enrich both paint this from pr_reviews (#876). */
+    tempestStatus: StackTempestStatus | null;
+    /**
+     * Ledger-backed agent runs, one per live row (#1119). Fast list and enrich
+     * both paint this from our tables only — never GitHub. The per-agent status
+     * fields above stay as a rollup of the newest run for older clients.
+     * Undefined = producer predates runs (clients fall back to the rollup).
+     */
+    agentRuns?: StackAgentRun[];
+    conflictDetail: string | null;
+    lastRestackedSha: string | null;
+    /** GitHub PR mergeability from enrich; null when unknown. */
+    mergeable: boolean | null;
+    /** GitHub REST mergeable_state; null when unknown. */
+    mergeableState: string | null;
+    /**
+     * Vortex-style linked issues (keywords + Development sidebar), cap 3.
+     * null until first enrich finds any; kept on merged unit members (unlike CI).
+     */
+    linkedIssues?: StackLinkedIssue[] | null;
+    /**
+     * Specialist lanes Vortex launched on this PR (smart router / Manual).
+     * Fast list and enrich both fill from vortex_pr_review_state (#896 / #915).
+     * Durable after merge — terminal layers keep the last run so Work can grey
+     * the marks on a done-growing unit member instead of dropping them (#1021).
+     */
+    specialistsRun?: string[] | null;
+    /** Published invocation count per specialist lane. Frontend paint follows separately. */
+    specialistRunCounts?: Record<string, number> | null;
+    /** Number of published reviews Core participated in for this PR. */
+    coreRuns?: number | null;
+    /**
+     * Cyclone's merge-conflict specialist resolved this PR (#973). Fast list and
+     * enrich both paint from cyclone_conflict_resolutions; null on terminal
+     * layers and when the specialist never ran.
+     */
+    conflictResolution?: StackLayerConflictResolution | null;
+};
+export type StackUnitMemberDto = {
+    prNumber: number;
+    branch: string;
+    position: number;
+    seamState: string;
+    seamReviewedSha: string | null;
+    promotedHeadSha: string | null;
+    promotedAt: string;
+    /**
+     * GitHub PR title snapshotted at promote / enrich (#965).
+     * Survives stack_branches dropping the open-chain row. null until first write.
+     */
+    title?: string | null;
+    /**
+     * Linked issues snapshotted onto the member at promote / enrich (#936).
+     * Survives stack_branches dropping the open-chain row. null until first write.
+     */
+    linkedIssues?: StackLinkedIssue[] | null;
+    /**
+     * Vortex specialist lanes that ran on this PR (#1021). Painted from
+     * vortex_pr_review_state on the fast list — the open layer is gone after
+     * promote, so the member must carry the marks for the greyed-out row.
+     */
+    specialistsRun?: string[] | null;
+    /** Published invocation count per specialist lane. */
+    specialistRunCounts?: Record<string, number> | null;
+    /** Number of published reviews Core participated in for this PR. */
+    coreRuns?: number | null;
+};
+export type StackUnitDto = {
+    id: string;
+    uNumber: number;
+    state: string;
+    branch: string;
+    landTarget: string;
+    members: StackUnitMemberDto[];
+    landPrNumber: number | null;
+    tempestLandStatus: string | null;
+    landingBlockReason: string | null;
+    /**
+     * Land-PR chrome. Fast list hydrates last-known CI/title/mergeable/issues from
+     * `review_units` (#878 / #892) and may attach a tempest-only stub (#876). Enrich
+     * refreshes GitHub and writes back. Null when the land PR is an open stack
+     * layer (chips live on `layers`) or the unit has no land PR.
+     */
+    landPr: StackLayerDto | null;
+};
+export type StackDto = {
+    id: string;
+    owner: string;
+    repo: string;
+    trunkBranch: string;
+    /** Real trunk the review unit eventually lands into. */
+    landTarget: string;
+    autoPromoteWhenGreen: boolean;
+    /**
+     * Dashboard-only archive (#963): set hides the stack from the active Work
+     * list; GitHub PRs stay open. Only PATCH /stacks/:id toggles it.
+     */
+    archivedAt: string | null;
+    layers: StackLayerDto[];
+    /** Present when a review-unit row exists for this stack. */
+    unit?: StackUnitDto;
+};

package/dist/stack-dto.js

@@ -0,0 +1,7 @@
+/**
+ * Wire types returned by the stack list/enrich HTTP endpoints.
+ *
+ * `api/src/stacks.ts#loadStackDtos` is the producer. Keep this file
+ * dependency-free and byte-for-byte aligned with the canonical wire contract.
+ */
+export {};