mergestorm 0.3.25 → 0.3.27

package/dist/stack-blockers.d.ts

@@ -12,6 +12,11 @@ export type StackAgentBusy = {
     agent: "vortex" | "cyclone";
     blocker: string;
 };
+export type StackBusyAgent = StackAgentBusy["agent"];
+export type StackHeldBlocker = StackBlocker & {
+    actAfter: "agents_idle";
+    waitingOn: StackBusyAgent[];
+};
 export type StackLayerAgents = {
     prNumber: number;
     headSha: string | null;
@@ -27,16 +32,57 @@ export type StackLayerAgents = {
         cyclone: boolean;
     };
 };
+export type StackRepairHint = {
+    kind: "restack_conflict" | "merge_conflict";
+    prNumber: number;
+    headSha: string | null;
+    branch: string;
+    liveParent: string | null;
+    files: string[];
+    steps: string;
+} | {
+    kind: "ci_failure";
+    prNumber: number;
+    headSha: string | null;
+    branch: string;
+    failingCheck: string | null;
+    steps: string;
+};
+export type StackLandGatePending = {
+    prNumber: number;
+    headSha: string | null;
+    reason: string;
+};
+export declare function landGateIsPending(reason: string | null | undefined): boolean;
 export declare function layerAgentsBusy(layer: StackLayerDto): StackAgentsBusy;
 export declare function layerAgents(layer: StackLayerDto): StackLayerAgents;
 export declare function isMgParkBase(branch: string | null | undefined): boolean;
 /** GitHub DIRTY vs an mg-park-* freeze is not a merge conflict, verified or not. */
 export declare function boundDirty(layer: StackLayerDto): boolean;
+export declare function mergeabilityPending(layer: StackLayerDto): boolean;
 export declare function sameHead(a: string | null | undefined, b: string | null | undefined): boolean;
 export declare function currentLayer(stack: StackDto): StackLayerDto | undefined;
+export declare function conflictLiveParent(stack: StackDto, layer: StackLayerDto): string | null;
+export declare function conflictRepairSteps(branch: string, liveParent: string | null): string;
+export declare function agentsCannotClear(blocker: string): boolean;
+export declare function stackRepair(stack: StackDto, attention: StackBlocker | null, layer: StackLayerDto | undefined, bounce: MergeQueueEntryDto | undefined): StackRepairHint | null;
 /** Pair-gate attention plus live hard blocks on every other open layer. */
 export declare function stackBlockers(stack: StackDto, entries?: MergeQueueEntryDto[], cursor?: Pick<StackWatchCursor, "bounceId" | "afterFinishedAt">): {
+    attention: null;
+    held: StackHeldBlocker;
+    issues: StackBlocker[];
+    currentCandidate: {
+        prNumber: number;
+        headSha: string | null;
+    } | null;
+    bounce: undefined;
+    busy: StackAgentBusy[];
+    agents: StackLayerAgents | null;
+    repair: StackRepairHint | null;
+    landGatePending: StackLandGatePending | null;
+} | {
     attention: StackBlocker | null;
+    held: null;
     issues: StackBlocker[];
     currentCandidate: {
         prNumber: number;
@@ -45,6 +91,8 @@ export declare function stackBlockers(stack: StackDto, entries?: MergeQueueEntry
     bounce: MergeQueueEntryDto | undefined;
     busy: StackAgentBusy[];
     agents: StackLayerAgents | null;
+    repair: StackRepairHint | null;
+    landGatePending: StackLandGatePending | null;
 };
 /** Compact contract text shared by status and wait summaries. */
-export declare function stackBlockersSummary(attention: Pick<StackBlocker, "prNumber" | "blocker"> | null, issues: StackBlocker[], busy?: readonly StackAgentBusy[]): string;
+export declare function stackBlockersSummary(attention: Pick<StackBlocker, "prNumber" | "blocker"> | null, issues: StackBlocker[], busy?: readonly StackAgentBusy[], landGatePending?: Pick<StackLandGatePending, "prNumber" | "reason"> | null, actAfter?: StackHeldBlocker["actAfter"] | null): string;

package/dist/stack-blockers.js

@@ -1,4 +1,8 @@
 import { deriveStackAgentsBusy, mergeQueueBounceLabel, restackRetryPending, } from "./stack-dto.js";
+export function landGateIsPending(reason) {
+    const token = reason?.trim().replace(/^landing blocked:\s*/i, "").match(/^[a-z_]+/i)?.[0] ?? "";
+    return /_(?:pending|running)$/i.test(token);
+}
 export function layerAgentsBusy(layer) {
     return layer.agentsBusy ?? deriveStackAgentsBusy(layer);
 }
@@ -26,6 +30,12 @@ export function boundDirty(layer) {
     return (!layer.headSha || layer.mergeableHeadSha === layer.headSha) &&
         (layer.mergeable === false || layer.mergeableState?.toLowerCase() === "dirty");
 }
+export function mergeabilityPending(layer) {
+    if (isMgParkBase(layer.parentBranch))
+        return false;
+    return layer.mergeable == null && !!layer.headSha && layer.mergeableHeadSha === layer.headSha &&
+        layer.mergeableState?.toLowerCase() === "pending";
+}
 export function sameHead(a, b) {
     const left = a?.trim().toLowerCase();
     const right = b?.trim().toLowerCase();
@@ -88,6 +98,9 @@ function layerAttention(stack, layer, queue, cursor) {
             const name = layer.checks?.failingName?.trim();
             return hardBlock(`CI failed${name ? ` — ${name}` : ""}`);
         }
+        if (layer.agentRuns?.some((run) => run.agent === "cyclone" && run.status === "failed" &&
+            sameHead(run.sha, layer.headSha)))
+            return hardBlock("Cyclone failed");
         const tempest = layer.agentRuns?.find((run) => run.agent === "tempest" &&
             ["findings", "failed"].includes(run.status) && sameHead(run.sha, layer.headSha));
         if (tempest)
@@ -98,8 +111,9 @@ function layerAttention(stack, layer, queue, cursor) {
         if (seam)
             return hardBlock(seam);
         if (stack.unit?.landPrNumber === layer.prNumber) {
-            if (stack.unit.landingBlockReason?.trim())
-                return hardBlock(stack.unit.landingBlockReason.trim());
+            const landing = stack.unit.landingBlockReason?.trim();
+            if (landing && !landGateIsPending(landing))
+                return hardBlock(landing);
             if (stack.unit.tempestLandStatus?.toLowerCase() === "failed")
                 return hardBlock("Tempest failed");
         }
@@ -115,6 +129,81 @@ function layerAttention(stack, layer, queue, cursor) {
         return none;
     return { blocker: mergeQueueBounceLabel(bounce), bounceKind: kind, bounce };
 }
+function isTerminalLayer(layer) {
+    return layer.state === "merged" || layer.state === "closed";
+}
+export function conflictLiveParent(stack, layer) {
+    const promoted = (candidate) => !!stack.unit?.members?.some((member) => member.prNumber === candidate.prNumber && member.promotedHeadSha?.trim());
+    const sibling = stack.layers
+        .filter((candidate) => candidate.prNumber > 0 && candidate.position < layer.position &&
+        !isTerminalLayer(candidate) && !promoted(candidate))
+        .sort((a, b) => b.position - a.position)[0];
+    if (sibling)
+        return sibling.branch;
+    const retired = new Set([
+        ...stack.layers.filter((candidate) => isTerminalLayer(candidate) || promoted(candidate)).map((candidate) => candidate.branch),
+        ...(stack.unit?.members ?? []).filter((member) => member.promotedHeadSha?.trim()).map((member) => member.branch),
+    ]);
+    const usable = (branch) => !!branch?.trim() && !isMgParkBase(branch) && !retired.has(branch) && branch !== layer.branch;
+    for (const branch of [layer.restackError?.from?.branch, layer.parentBranch, stack.unit?.branch, stack.trunkBranch]) {
+        if (usable(branch))
+            return branch;
+    }
+    return null;
+}
+function conflictFiles(layer, bounce) {
+    const paths = bounce?.bounceDetail?.conflictPaths?.filter((path) => path.trim());
+    if (paths?.length)
+        return [...paths];
+    const detail = layer.restackError?.kind === "rebase_conflict" ? layer.restackError.detail : layer.conflictDetail;
+    const listed = detail?.match(/^conflict in (.+)$/)?.[1];
+    return listed ? listed.split(", ").map((path) => path.trim()).filter(Boolean) : [];
+}
+export function conflictRepairSteps(branch, liveParent) {
+    if (!liveParent) {
+        return `The live parent of ${branch} is unknown (it is never an mg-park-* freeze). Do not merge or rebase anything; stop and tell the human.`;
+    }
+    return `Merge ${liveParent} into ${branch}: git fetch origin, check out ${branch} at its live remote head, git merge origin/${liveParent}, resolve the conflicts, run the tests, then an ordinary git push (no force). Do not rebase onto trunk, main, or mg-park-*, and do not retarget the PR base.`;
+}
+function landPrLiveParent(stack, layer) {
+    const base = stack.unit?.landTarget?.trim() || layer.parentBranch?.trim();
+    return base && !isMgParkBase(base) && base !== layer.branch ? base : null;
+}
+export function agentsCannotClear(blocker) {
+    return blocker === "Conflict" || blocker === "Restack failed" || blocker === "Draft PR" ||
+        blocker.startsWith("Merge conflicts");
+}
+export function stackRepair(stack, attention, layer, bounce) {
+    if (!attention || !layer || attention.prNumber !== layer.prNumber)
+        return null;
+    const landPr = !!stack.unit && layer.prNumber === stack.unit.landPrNumber && layer.branch === stack.unit.branch;
+    const restackConflict = attention.blocker === "Conflict" || attention.bounceKind === "restack_conflict";
+    const mergeConflict = attention.blocker.startsWith("Merge conflicts");
+    if (restackConflict || mergeConflict) {
+        const liveParent = landPr ? landPrLiveParent(stack, layer) : conflictLiveParent(stack, layer);
+        return {
+            kind: restackConflict ? "restack_conflict" : "merge_conflict",
+            prNumber: layer.prNumber,
+            headSha: layer.headSha ?? null,
+            branch: layer.branch,
+            liveParent,
+            files: conflictFiles(layer, bounce),
+            steps: conflictRepairSteps(layer.branch, liveParent),
+        };
+    }
+    if (attention.blocker.startsWith("CI failed") || attention.bounceKind === "ci_failure") {
+        const failingCheck = bounce?.bounceDetail?.failingCheck?.trim() || layer.checks?.failingName?.trim() || null;
+        return {
+            kind: "ci_failure",
+            prNumber: layer.prNumber,
+            headSha: layer.headSha ?? null,
+            branch: layer.branch,
+            failingCheck,
+            steps: `Read the failing ${failingCheck ? `check ${failingCheck}` : "checks"} on ${layer.branch} (gh run list --branch ${layer.branch}, then gh run view <run-id> --log-failed), fix it on ${layer.branch} with the smallest patch, run that check locally, confirm the remote head is still ${layer.headSha ?? "the head you started from"}, then an ordinary git push. Do not retarget the PR base.`,
+        };
+    }
+    return null;
+}
 /** Pair-gate attention plus live hard blocks on every other open layer. */
 export function stackBlockers(stack, entries = [], cursor = {}) {
     const candidate = currentLayer(stack);
@@ -134,8 +223,13 @@ export function stackBlockers(stack, entries = [], cursor = {}) {
     for (const layer of open) {
         const selected = layer.prNumber === candidate?.prNumber;
         const result = layerAttention(stack, layer, selected ? queue : [], cursor);
-        if (!result.blocker)
+        if (!result.blocker) {
+            if (mergeabilityPending(layer) && (selected || !candidate || layer.position > candidate.position)) {
+                issues.push({ prNumber: layer.prNumber, headSha: layer.headSha ?? null,
+                    blocker: `Merge state unknown${layer.parentBranch ? ` vs ${layer.parentBranch}` : ""}`, bounceKind: null });
+            }
             continue;
+        }
         const issue = { prNumber: layer.prNumber, headSha: layer.headSha ?? null,
             blocker: result.blocker, bounceKind: result.bounceKind };
         if (selected || (!attention && layer === child)) {
@@ -155,16 +249,35 @@ export function stackBlockers(stack, entries = [], cursor = {}) {
                 busy.push({ prNumber: attention.prNumber, headSha: attention.headSha, agent, blocker: attention.blocker });
         }
     }
+    const landing = stack.unit?.landingBlockReason?.trim();
+    const landLayer = stack.unit?.landPrNumber != null && !stack.archivedAt
+        ? open.find((layer) => layer.prNumber === stack.unit?.landPrNumber)
+        : undefined;
+    const landGatePending = landLayer && landing && landGateIsPending(landing)
+        ? { prNumber: landLayer.prNumber, headSha: landLayer.headSha ?? null, reason: landing }
+        : null;
+    if (busy.length && attention && agentsCannotClear(attention.blocker)) {
+        const held = { ...attention, actAfter: "agents_idle", waitingOn: busy.map((entry) => entry.agent) };
+        return { attention: null, held, issues: [attention, ...issues], currentCandidate, bounce: undefined, busy, agents,
+            repair: stackRepair(stack, attention, attentionLayer, undefined), landGatePending };
+    }
     if (busy.length)
-        return { attention: null, issues, currentCandidate, bounce: undefined, busy, agents };
-    return { attention, issues, currentCandidate, bounce, busy, agents };
+        return { attention: null, held: null, issues, currentCandidate, bounce: undefined, busy, agents, repair: null, landGatePending };
+    return { attention, held: null, issues, currentCandidate, bounce, busy, agents, repair: stackRepair(stack, attention, attentionLayer, bounce), landGatePending };
 }
 /** Compact contract text shared by status and wait summaries. */
-export function stackBlockersSummary(attention, issues, busy = []) {
-    const blocked = attention ? ` · blocked: #${attention.prNumber} ${attention.blocker}` : "";
-    const working = busy.length
-        ? ` · held: #${busy[0].prNumber} ${busy[0].blocker} while ${busy.map((entry) => entry.agent === "cyclone" ? "Cyclone patches" : "Vortex reviews").join(" and ")}`
+export function stackBlockersSummary(attention, issues, busy = [], landGatePending = null, actAfter = null) {
+    const agentWork = (entry) => entry.agent === "cyclone" ? "Cyclone patches" : "Vortex reviews";
+    const blocked = attention && actAfter && busy.length
+        ? ` · blocked after the agents: #${attention.prNumber} ${attention.blocker} (plan the fix; act once ${busy.map(agentWork).join(" and ")} finish and the watch returns attention)`
+        : attention ? ` · blocked: #${attention.prNumber} ${attention.blocker}` : "";
+    const working = busy.length && !actAfter
+        ? ` · held: #${busy[0].prNumber} ${busy[0].blocker} while ${busy.map(agentWork).join(" and ")}`
+        : "";
+    const listed = actAfter && attention ? issues.filter((issue) => issue.prNumber !== attention.prNumber || issue.blocker !== attention.blocker) : issues;
+    const labels = listed.slice(0, 3).map(issue => `#${issue.prNumber} ${issue.blocker}`).join("; ");
+    const gate = landGatePending && !attention
+        ? ` · land gate: #${landGatePending.prNumber} ${landGatePending.reason} (nothing to fix; wait)`
         : "";
-    const labels = issues.slice(0, 3).map(issue => `#${issue.prNumber} ${issue.blocker}`).join("; ");
-    return blocked + working + (issues.length ? ` · issues: ${labels}${issues.length > 3 ? `; +${issues.length - 3} more` : ""}` : "");
+    return blocked + working + gate + (listed.length ? ` · issues: ${labels}${listed.length > 3 ? `; +${listed.length - 3} more` : ""}` : "");
 }

package/dist/stack-dto.d.ts

@@ -5,6 +5,10 @@ export type RestackError = {
     attemptedAt: string;
     attempts: number;
     backupRef: string | null;
+    from?: {
+        branch: string;
+        oldSha: string;
+    };
 };
 export declare function restackAttemptsExhausted(error: Pick<RestackError, "attempts">): boolean;
 export declare function pushRejectionIsRetryable(message: string): boolean;
@@ -154,6 +158,14 @@ export type StackLayerConflictResolution = {
      */
     dispatchId: string | null;
 };
+export type StackLayerCiFixStatus = "verified" | "unverified" | "no_changes" | "failed";
+export type StackLayerCiFix = {
+    status: StackLayerCiFixStatus;
+    failingCheck: string | null;
+    resultSha: string | null;
+    reason: string | null;
+    at: string;
+};
 export type StackLayerDto = {
     branch: string;
     parentBranch: string | null;
@@ -228,6 +240,7 @@ export type StackLayerDto = {
      * layers and when the specialist never ran.
      */
     conflictResolution?: StackLayerConflictResolution | null;
+    ciFix?: StackLayerCiFix | null;
 };
 export type StackUnitMemberDto = {
     prNumber: number;
@@ -370,6 +383,7 @@ export type MergeQueueBounceDetail = {
     conflictDetail?: string;
     conflictPaths?: string[];
     message?: string;
+    warning?: string;
 };
 export type MergeQueueEntryDto = {
     id: string;

package/dist/stack-watch-obligation.d.ts

@@ -0,0 +1,43 @@
+import type { StackDto } from "./stack-dto.js";
+export declare const STACK_WATCH_NOT_DONE_SENTENCE = "This stack is not landed. Your task is not done. Call stack_wait again with this cursor.";
+export type StackWatchDoneReason = "landed" | "closed" | "archived" | "not_found";
+export type StackWatchReason = StackWatchDoneReason | "open" | "attention" | "unread" | "rate_limited" | "failed";
+export type StackWatchNextArgs = {
+    stack_id: string;
+    enrolled_head_sha?: string | null;
+    after_finished_at?: string | null;
+    bounce_id?: string | null;
+    timeout_s: 45;
+};
+export type StackWatchNext = {
+    tool: "stack_wait";
+    args: StackWatchNextArgs;
+    command: string;
+};
+export type StackWatchObligation = {
+    done: boolean;
+    until: "landed";
+    reason: StackWatchReason;
+    next: StackWatchNext | null;
+    message: string;
+};
+export type StackWatchObligationInput = {
+    stackId: string;
+    terminal: StackWatchDoneReason | null;
+    cursor?: {
+        enrolledHeadSha?: string | null;
+        afterFinishedAt?: string | null;
+        bounceId?: string | null;
+    } | null;
+    status?: string;
+    attention?: {
+        prNumber: number;
+        blocker: string;
+    } | null;
+    retryAfterSeconds?: number;
+    unread?: boolean;
+    freshCursor?: boolean;
+};
+export declare function stackTerminalReason(stack: Pick<StackDto, "archivedAt" | "layers" | "unit"> | null | undefined): StackWatchDoneReason | null;
+export declare function stackWatchNextArgs(stackId: string, cursor: StackWatchObligationInput["cursor"]): StackWatchNextArgs;
+export declare function stackWatchObligation(input: StackWatchObligationInput): StackWatchObligation;

package/dist/stack-watch-obligation.js

@@ -0,0 +1,79 @@
+export const STACK_WATCH_NOT_DONE_SENTENCE = "This stack is not landed. Your task is not done. Call stack_wait again with this cursor.";
+const DONE_MESSAGES = {
+    landed: "This stack is landed. The watch is done; stop calling stack_wait for it.",
+    closed: "Every PR in this stack is merged or closed and nothing is left to land, but not every PR landed. The watch is done; tell the human which PRs were closed without landing.",
+    archived: "This stack is archived: the human took it back. The watch is done; stop calling stack_wait for it and do not push to its PRs.",
+    not_found: "No stack with this id exists for this account. Mergestorm deletes a stack once none of its layers is open, so a stack you were watching has most likely landed; a mistyped id or another account's stack reads the same. The watch is done; confirm each PR is merged (gh pr view <n> --json state) before reporting it landed.",
+};
+export function stackTerminalReason(stack) {
+    if (!stack)
+        return "not_found";
+    if (stack.archivedAt)
+        return "archived";
+    const layers = stack.layers;
+    if (layers.some((layer) => layer.state !== "merged" && layer.state !== "closed"))
+        return null;
+    const unit = stack.unit;
+    if (layers.length === 0 && !unit)
+        return null;
+    const landPr = unit?.landPr;
+    if (landPr && landPr.prNumber > 0 && landPr.state !== "merged" && landPr.state !== "closed")
+        return null;
+    if (unit && unit.state !== "landed" && unit.state !== "abandoned")
+        return null;
+    const everyLayerMerged = layers.every((layer) => layer.state === "merged");
+    return everyLayerMerged && (!unit || unit.state === "landed") ? "landed" : "closed";
+}
+export function stackWatchNextArgs(stackId, cursor) {
+    return {
+        stack_id: stackId,
+        ...(cursor && cursor.enrolledHeadSha !== undefined ? { enrolled_head_sha: cursor.enrolledHeadSha } : {}),
+        ...(cursor && cursor.afterFinishedAt !== undefined ? { after_finished_at: cursor.afterFinishedAt } : {}),
+        ...(cursor && cursor.bounceId !== undefined ? { bounce_id: cursor.bounceId } : {}),
+        timeout_s: 45,
+    };
+}
+export function stackWatchObligation(input) {
+    if (input.terminal) {
+        return {
+            done: true,
+            until: "landed",
+            reason: input.terminal,
+            next: null,
+            message: DONE_MESSAGES[input.terminal],
+        };
+    }
+    const args = stackWatchNextArgs(input.stackId, input.cursor);
+    const reason = input.status === "rate_limited"
+        ? "rate_limited"
+        : input.status === "failed"
+            ? "failed"
+            : input.attention ? "attention" : input.unread ? "unread" : "open";
+    const parts = [
+        STACK_WATCH_NOT_DONE_SENTENCE,
+        `Watch stack ${input.stackId} as a whole until it lands or the human takes it back. A clean push, a submit, or one merged layer does not finish it: merging a lower layer can break a layer above it.`,
+    ];
+    if (reason === "rate_limited") {
+        parts.push(`Wait ${input.retryAfterSeconds !== undefined ? `${input.retryAfterSeconds}s` : "retry_after_seconds"} first, then call stack_wait with the same cursor.`);
+    }
+    else if (reason === "failed") {
+        parts.push(`This read failed, which does not end the task. Call stack_wait once more with the same cursor; if that fails too, tell the human that stack ${input.stackId} is not landed and is no longer being watched.`);
+    }
+    else if (reason === "attention" && input.attention) {
+        parts.push(`First fix #${input.attention.prNumber} (${input.attention.blocker}); repair, when present, names the fix. Calling stack_wait again before fixing it returns the same attention. After your push, call stack_wait with this cursor and enrolled_head_sha set to the SHA you pushed.`);
+    }
+    else if (reason === "unread") {
+        parts.push("This tool did not read the stack's state; stack_wait will.");
+    }
+    parts.push(`Next call: stack_wait ${JSON.stringify(args)}.`);
+    if (input.freshCursor) {
+        parts.push("If you already hold a cursor from an earlier stack_wait on this stack, keep passing that cursor instead.");
+    }
+    return {
+        done: false,
+        until: "landed",
+        reason,
+        next: { tool: "stack_wait", args, command: `mg stack wait ${input.stackId} --json` },
+        message: parts.join(" "),
+    };
+}

package/dist/stack-watch.d.ts

@@ -1,4 +1,5 @@
-import { type StackAgentBusy, type StackBlocker, type StackLayerAgents } from "./stack-blockers.js";
+import { type StackAgentBusy, type StackBlocker, type StackBusyAgent, type StackHeldBlocker, type StackLayerAgents, type StackLandGatePending, type StackRepairHint } from "./stack-blockers.js";
+import { type StackWatchObligation } from "./stack-watch-obligation.js";
 import { apiFetch } from "./api.js";
 import type { Config } from "./config.js";
 export declare const STACK_WATCH_SCHEMA: "mergestorm.stack_watch/v1";
@@ -27,7 +28,12 @@ export type StackWatchEnvelope = {
     } | null;
     assessment: "available" | "unavailable";
     busy: StackAgentBusy[];
+    actAfter: StackHeldBlocker["actAfter"] | null;
+    waitingOn: StackBusyAgent[];
     agents: StackLayerAgents | null;
+    repair: StackRepairHint | null;
+    landGatePending: StackLandGatePending | null;
+    watch: StackWatchObligation;
 };
 export type PollStackWatchOptions = {
     timeoutMs?: number;

package/dist/stack-watch.js

@@ -1,4 +1,5 @@
 import { currentLayer, layerAgents, stackBlockers, } from "./stack-blockers.js";
+import { stackTerminalReason, stackWatchObligation, } from "./stack-watch-obligation.js";
 import { setTimeout as sleep } from "node:timers/promises";
 import { apiFetch } from "./api.js";
 import { REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus, transientRetryWaitMs, } from "./commands/review-client.js";
@@ -47,10 +48,20 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
     let lastEnvelope = {
         schema: STACK_WATCH_SCHEMA, status: "failed", stackId: id, blocker: null,
         bounceKind: null, prNumber: null, headSha: null, cursor,
-        issues: [], currentCandidate: null, assessment: "unavailable", busy: [], agents: null,
+        issues: [], currentCandidate: null, assessment: "unavailable", busy: [], actAfter: null, waitingOn: [], agents: null, repair: null,
+        landGatePending: null,
     };
+    let terminal = null;
+    const seal = (snapshot, retryAfterSeconds) => ({
+        ...snapshot,
+        watch: stackWatchObligation({
+            stackId: id, terminal, cursor: snapshot.cursor, status: snapshot.status, retryAfterSeconds,
+            attention: snapshot.status === "attention" && snapshot.blocker && snapshot.prNumber != null
+                ? { prNumber: snapshot.prNumber, blocker: snapshot.blocker } : null,
+        }),
+    });
     let transientFailures = 0;
-    const timeout = () => new StackWatchTimeoutError(lastEnvelope);
+    const timeout = () => new StackWatchTimeoutError(seal(lastEnvelope));
     const pause = async (ms) => {
         const remaining = Math.min(ms, Math.max(0, deadline - now()));
         if (remaining > 0)
@@ -76,11 +87,11 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
                     throw timeout();
                 if (timeoutMs !== 0 && isTransientReviewPollError(err) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
                     transientFailures += 1;
-                    opts.onTick?.(lastEnvelope);
+                    opts.onTick?.(seal(lastEnvelope));
                     await pause(transientRetryWaitMs({ failureCount: transientFailures, random: opts.random }));
                     continue;
                 }
-                throw new StackWatchError(err instanceof Error ? err.message : String(err), { ...lastEnvelope, status: "failed", assessment: "unavailable" }, { cause: err });
+                throw new StackWatchError(err instanceof Error ? err.message : String(err), seal({ ...lastEnvelope, status: "failed", assessment: "unavailable" }), { cause: err });
             }
             if (response.status === 200)
                 return response.body;
@@ -90,14 +101,14 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
             if (timeoutMs !== 0 && isTransientReviewPollStatus(response.status) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES &&
                 (response.status !== 429 || retryWaitMs < deadline - now())) {
                 transientFailures += 1;
-                opts.onTick?.({ ...lastEnvelope, status: response.status === 429 ? "rate_limited" : lastEnvelope.status });
+                opts.onTick?.(seal({ ...lastEnvelope, status: response.status === 429 ? "rate_limited" : lastEnvelope.status }, response.status === 429 ? response.retryAfterSeconds : undefined));
                 await pause(retryWaitMs);
                 continue;
             }
-            throw new StackWatchError(`Stack poll failed (HTTP ${response.status})`, {
+            throw new StackWatchError(`Stack poll failed (HTTP ${response.status})`, seal({
                 ...lastEnvelope, status: response.status === 429 ? "rate_limited" : "failed",
                 assessment: "unavailable",
-            }, undefined, response.retryAfterSeconds);
+            }, response.retryAfterSeconds), undefined, response.retryAfterSeconds);
         }
         throw timeout();
     };
@@ -106,16 +117,22 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
         const stack = snapshot && Array.isArray(snapshot.stacks)
             ? snapshot.stacks.find((candidate) => candidate.id.trim().toLowerCase() === id)
             : undefined;
+        if (snapshot && Array.isArray(snapshot.stacks) && !stack) {
+            terminal = "not_found";
+            throw new StackWatchError("Stack not found or not owned by the current user", seal({ ...lastEnvelope, status: "failed", assessment: "unavailable", blocker: null, issues: [], busy: [], actAfter: null, waitingOn: [],
+                prNumber: null, headSha: null, repair: null, agents: null, currentCandidate: null, landGatePending: null }));
+        }
         if (!stack || !Array.isArray(stack.layers)) {
-            throw new StackWatchError("Stack snapshot missing or invalid", { ...lastEnvelope, status: "failed", assessment: "unavailable" });
+            throw new StackWatchError("Stack snapshot missing or invalid", seal({ ...lastEnvelope, status: "failed", assessment: "unavailable" }));
         }
+        terminal = stackTerminalReason(stack);
         return stack;
     };
     const queueRoute = `/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}`;
     const readQueue = async (route, finalSnapshot = false) => {
         const queue = await request(route, finalSnapshot);
         if (!queue || !Array.isArray(queue.entries)) {
-            throw new StackWatchError("Invalid merge queue response", { ...lastEnvelope, status: "failed", assessment: "unavailable" });
+            throw new StackWatchError("Invalid merge queue response", seal({ ...lastEnvelope, status: "failed", assessment: "unavailable" }));
         }
         return {
             entries: queue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id),
@@ -123,16 +140,18 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
         };
     };
     const evaluate = (stack, entries) => {
-        const { attention, issues, currentCandidate, bounce, busy, agents } = stackBlockers(stack, entries, cursor);
+        const { attention, held: named, issues, currentCandidate, bounce, busy, agents, repair, landGatePending } = stackBlockers(stack, entries, cursor);
         if (bounce)
             cursor = Object.freeze({ ...cursor, bounceId: bounce.id,
                 ...(bounce.finishedAt !== undefined ? { afterFinishedAt: bounce.finishedAt } : {}) });
         const held = busy[0];
-        lastEnvelope = { ...lastEnvelope, cursor, issues, currentCandidate, assessment: "available", busy, agents,
-            blocker: attention?.blocker ?? null, bounceKind: attention?.bounceKind ?? null,
-            prNumber: attention?.prNumber ?? held?.prNumber ?? currentCandidate?.prNumber ?? null,
-            headSha: attention ? attention.headSha : held ? held.headSha : currentCandidate?.headSha ?? null,
-            status: attention ? "attention" : busy.length || entries.some((entry) => ["queued", "running", "waiting"].includes(entry.state))
+        const shown = attention ?? named;
+        lastEnvelope = { ...lastEnvelope, cursor, issues, currentCandidate, assessment: "available", busy, agents, repair, landGatePending,
+            actAfter: named?.actAfter ?? null, waitingOn: named?.waitingOn ?? [],
+            blocker: shown?.blocker ?? null, bounceKind: shown?.bounceKind ?? null,
+            prNumber: shown?.prNumber ?? held?.prNumber ?? currentCandidate?.prNumber ?? null,
+            headSha: shown ? shown.headSha : held ? held.headSha : currentCandidate?.headSha ?? null,
+            status: attention ? "attention" : busy.length || landGatePending || entries.some((entry) => ["queued", "running", "waiting"].includes(entry.state))
                 ? "in_progress" : "waiting" };
     };
     let stack = await enrich(timeoutMs === 0);
@@ -145,8 +164,8 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
         agents: layer ? layerAgents(layer) : null };
     let queue = await readQueue(queueRoute, timeoutMs === 0);
     evaluate(stack, queue.entries);
-    if (lastEnvelope.status === "attention" || timeoutMs === 0)
-        return lastEnvelope;
+    if (lastEnvelope.status === "attention" || timeoutMs === 0 || terminal)
+        return seal(lastEnvelope);
     while (now() < deadline) {
         const heldAt = now();
         const seconds = Math.min(lastEnvelope.busy.length ? STACK_WATCH_BUSY_RECHECK_S : 45, Math.max(1, Math.ceil((deadline - heldAt) / 1000)));
@@ -162,9 +181,9 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
             agents: refreshed ? layerAgents(refreshed) : null };
         transientFailures = 0;
         evaluate(stack, queue.entries);
-        if (lastEnvelope.status === "attention")
-            return lastEnvelope;
-        opts.onTick?.(lastEnvelope);
+        if (lastEnvelope.status === "attention" || terminal)
+            return seal(lastEnvelope);
+        opts.onTick?.(seal(lastEnvelope));
     }
     throw timeout();
 }

package/dist/ui/ansi.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Brand ink. xterm-256 77 (#5FAF5F) � muted green that Terminal.app
+ * actually paints. 24-bit `38;2;61;�` was read as palette 61 (purple).
+ */
+export declare const BRAND_GREEN: {
+    readonly hex: "#5FAF5F";
+    readonly index: 77;
+};
+export declare const BRAND_GREEN_SGR: string;
+/** Full-cell fill. Glyphs like ? leave a hairline; a space with this bg does not. */
+export declare const BRAND_FILL_SGR: string;
 export declare const ansi: {
     readonly enabled: boolean;
     green: (t: string) => string;
@@ -7,8 +18,10 @@ export declare const ansi: {
     yellow: (t: string) => string;
     gray: (t: string) => string;
     brightGreen: (t: string) => string;
+    /** Solid cell (space + fg/bg 77). Stacks flush � no ? hairline. */
+    brandFill: (t: string) => string;
     invert: (t: string) => string;
     boldGreen: (t: string) => string;
-    /** Prompt / mark ink. Never 32 — that reads as sick dark green. */
+    /** Prompt / mark ink. Never ANSI 32, 92, or 24-bit. */
     boldBrightGreen: (t: string) => string;
 };

package/dist/ui/ansi.js

@@ -9,7 +9,25 @@ function computeEnabled() {
 function wrap(code, text) {
     if (!computeEnabled())
         return text;
-    return `[${code}m${text}`;
+    return `\x1b[${code}m${text}\x1b[0m`;
+}
+/**
+ * Brand ink. xterm-256 77 (#5FAF5F) � muted green that Terminal.app
+ * actually paints. 24-bit `38;2;61;�` was read as palette 61 (purple).
+ */
+export const BRAND_GREEN = { hex: "#5FAF5F", index: 77 };
+export const BRAND_GREEN_SGR = `38;5;${BRAND_GREEN.index}`;
+/** Full-cell fill. Glyphs like ? leave a hairline; a space with this bg does not. */
+export const BRAND_FILL_SGR = `${BRAND_GREEN_SGR};48;5;${BRAND_GREEN.index}`;
+function brandGreen(text, bold = false) {
+    if (!computeEnabled())
+        return text;
+    return `\x1b[${bold ? "1;" : ""}${BRAND_GREEN_SGR}m${text}\x1b[0m`;
+}
+function brandFill(text) {
+    if (!computeEnabled())
+        return text;
+    return `\x1b[${BRAND_FILL_SGR}m${text}\x1b[0m`;
 }
 export const ansi = {
     get enabled() {
@@ -21,9 +39,11 @@ export const ansi = {
     red: (t) => wrap("31", t),
     yellow: (t) => wrap("33", t),
     gray: (t) => wrap("90", t),
-    brightGreen: (t) => wrap("92", t),
+    brightGreen: (t) => brandGreen(t),
+    /** Solid cell (space + fg/bg 77). Stacks flush � no ? hairline. */
+    brandFill: (t) => brandFill(t),
     invert: (t) => wrap("7", t),
-    boldGreen: (t) => (computeEnabled() ? `${t}` : t),
-    /** Prompt / mark ink. Never 32 — that reads as sick dark green. */
-    boldBrightGreen: (t) => (computeEnabled() ? `${t}` : t),
+    boldGreen: (t) => (computeEnabled() ? `\x1b[1;32m${t}\x1b[0m` : t),
+    /** Prompt / mark ink. Never ANSI 32, 92, or 24-bit. */
+    boldBrightGreen: (t) => brandGreen(t, true),
 };