stageflow 0.42.0 → 0.46.0

package/dist/runtime/artifactPath.js

@@ -0,0 +1,84 @@
+import path from "node:path";
+export function attemptArtifactsPrefix(stageId, attempt) {
+    return path.posix.join("stages", stageId, "attempts", String(attempt), "artifacts");
+}
+export function buildArtifactListedPath(parts) {
+    const relative = parts.relative.replace(/\\/g, "/");
+    const segments = relative.split("/").filter((segment) => segment.length > 0);
+    return path.posix.join("stages", parts.stageId, "attempts", String(parts.attempt), "artifacts", ...segments);
+}
+function parseStrictGrantable(listedPath) {
+    if (typeof listedPath !== "string" || listedPath.length === 0)
+        return undefined;
+    const posix = listedPath.replace(/\\/g, "/");
+    if (path.isAbsolute(listedPath) || path.posix.isAbsolute(posix))
+        return undefined;
+    if (posix.includes("\0") || posix.includes(".."))
+        return undefined;
+    const parts = posix.split("/").filter((part) => part.length > 0);
+    if (parts.length < 6)
+        return undefined;
+    if (parts[0] !== "stages" || parts[2] !== "attempts" || parts[4] !== "artifacts") {
+        return undefined;
+    }
+    const attemptRaw = parts[3];
+    if (!/^\d+$/.test(attemptRaw))
+        return undefined;
+    const attempt = Number(attemptRaw);
+    if (!Number.isInteger(attempt) || attempt < 1)
+        return undefined;
+    const relative = parts.slice(5).join("/");
+    if (relative.length === 0)
+        return undefined;
+    return {
+        stageId: parts[1],
+        attempt,
+        relative,
+    };
+}
+/**
+ * Accept a listed artifact path under a mode.
+ * - `grantable`: full run-relative path to a prior stage/attempt artifact file.
+ * - `current_attempt`: that attempt's run-relative prefix, or a bare path under
+ *   its artifacts dir; foreign `stages/...` paths are rejected.
+ */
+export function acceptArtifactListedPath(listedPath, mode) {
+    if (mode.kind === "grantable") {
+        return parseStrictGrantable(listedPath);
+    }
+    if (typeof listedPath !== "string" || listedPath.length === 0) {
+        return undefined;
+    }
+    const posixListed = listedPath.replace(/\\/g, "/");
+    if (path.isAbsolute(listedPath) || path.posix.isAbsolute(posixListed)) {
+        return undefined;
+    }
+    const prefix = attemptArtifactsPrefix(mode.stageId, mode.attempt);
+    if (posixListed === prefix || posixListed === `${prefix}/`) {
+        return undefined;
+    }
+    if (posixListed.startsWith(`${prefix}/`)) {
+        const relative = posixListed.slice(prefix.length + 1);
+        if (relative.length === 0)
+            return undefined;
+        return {
+            stageId: mode.stageId,
+            attempt: mode.attempt,
+            relative,
+        };
+    }
+    if (posixListed.startsWith("stages/")) {
+        return undefined;
+    }
+    return {
+        stageId: mode.stageId,
+        attempt: mode.attempt,
+        relative: posixListed,
+    };
+}
+export function parseArtifactListedPath(listedPath) {
+    return parseStrictGrantable(listedPath);
+}
+export function isGrantableArtifactPath(listedPath) {
+    return acceptArtifactListedPath(listedPath, { kind: "grantable" }) !== undefined;
+}

package/dist/runtime/completionCheckRunner.js

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
-import { lstat, readFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
 import { resolveBashPath } from "../preflight/bash.js";
 import { redactString } from "../logging/redact.js";
 import { getNamedSecrets } from "../logging/namedSecrets.js";
+import { inspectArtifactUnderRoot } from "./artifactDiskInspect.js";
 import { signalProcessGroup } from "./stageProcessLauncher.js";
 const MAX_COMMAND_OUTPUT_BYTES = 64 * 1024;
 const COMMAND_KILL_ESCALATE_MS = 2000;
@@ -163,56 +164,27 @@ async function runCommandCheck(check, input) {
     }
 }
 async function inspectArtifact(artifactsDir, relativePath) {
-    const target = path.resolve(artifactsDir, relativePath);
-    const relative = path.relative(artifactsDir, target);
-    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    const presence = await inspectArtifactUnderRoot(artifactsDir, relativePath);
+    if (presence.file_type === "missing") {
         return { kind: "artifact", path: relativePath, exists: false, file_type: "missing" };
     }
-    try {
-        // lstat every component rather than just the target: lstat(target) follows
-        // a symlink in a parent directory, which could otherwise prove a file that
-        // lives outside the attempt artifact root.
-        const segments = relative.split(path.sep).filter((segment) => segment !== "");
-        let current = artifactsDir;
-        let stats;
-        for (const segment of segments) {
-            current = path.join(current, segment);
-            stats = await lstat(current);
-            if (stats.isSymbolicLink()) {
-                return { kind: "artifact", path: relativePath, exists: true, file_type: "symlink" };
-            }
-            if (current !== target && !stats.isDirectory()) {
-                return { kind: "artifact", path: relativePath, exists: true, file_type: "other" };
-            }
-        }
-        if (stats === undefined) {
-            return { kind: "artifact", path: relativePath, exists: false, file_type: "missing" };
-        }
-        if (stats.isSymbolicLink()) {
-            return { kind: "artifact", path: relativePath, exists: true, file_type: "symlink" };
-        }
-        if (stats.isDirectory()) {
-            return { kind: "artifact", path: relativePath, exists: true, file_type: "directory" };
-        }
-        if (!stats.isFile()) {
-            return { kind: "artifact", path: relativePath, exists: true, file_type: "other" };
-        }
-        const content = await readFile(target);
+    if (presence.file_type !== "file" || presence.absolutePath === undefined) {
         return {
             kind: "artifact",
             path: relativePath,
             exists: true,
-            file_type: "file",
-            size_bytes: stats.size,
-            sha256: createHash("sha256").update(content).digest("hex"),
+            file_type: presence.file_type,
         };
     }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            return { kind: "artifact", path: relativePath, exists: false, file_type: "missing" };
-        }
-        throw error;
-    }
+    const content = await readFile(presence.absolutePath);
+    return {
+        kind: "artifact",
+        path: relativePath,
+        exists: true,
+        file_type: "file",
+        size_bytes: presence.size_bytes,
+        sha256: createHash("sha256").update(content).digest("hex"),
+    };
 }
 async function runArtifactCheck(check, input) {
     try {

package/dist/runtime/githubPollSource.d.ts

@@ -15,6 +15,7 @@ export type GithubPullItem = {
     user: {
         login: string;
     } | null;
+    head_sha?: string | null;
 };
 export type GithubPollResponse = {
     status: number;
@@ -35,14 +36,28 @@ export type GithubPollClient = {
 };
 export declare function defaultCreateGithubClient(token: string): GithubPollClient;
 export type NormalizedGithubEvent = {
-    action: "opened" | "merged" | "closed" | "updated";
+    action: "opened" | "synchronize" | "updated" | "merged" | "closed";
     number: number;
     title: string;
     url: string;
     author: string;
     repo: string;
     updatedAt: string;
+    headSha?: string;
 };
+type PollCursor = {
+    updatedAt: string;
+    number: number;
+};
+/**
+ * Classify a PR list delta into a normalized GitHub action.
+ *
+ * `opened` is reserved for brand-new PRs: equal created/updated timestamps, or
+ * first sight of a number whose `created_at` is after the poll cursor. A missing
+ * prior head SHA alone is not enough — that also happens on upgrade (no `heads`
+ * row yet), eviction, or a cold PR falling into the poll window.
+ */
+export declare function deriveGithubAction(item: GithubPullItem, previousHeadSha: string | undefined, cursor?: PollCursor | null): NormalizedGithubEvent["action"];
 export type GithubPollSourceOptions = {
     store: RunStore;
     cwd?: string;
@@ -59,9 +74,11 @@ export type GithubPollSourceOptions = {
  * per tick regardless of how many triggers watch it), and diffs each repo's
  * PR list against a persisted ETag + cursor to find genuinely new activity.
  *
- * The first tick for a never-before-seen repo only seeds the cursor — it
- * never fires for a repo's pre-existing PR history, mirroring how
- * `ScheduleSource` seeds `next_run_at` without firing on first sight.
+ * The first tick for a never-before-seen repo only seeds the cursor and
+ * per-PR head SHAs — it never fires for a repo's pre-existing PR history,
+ * mirroring how `ScheduleSource` seeds `next_run_at` without firing on
+ * first sight. The same quiet baseline runs when a cursor already exists
+ * but `heads` has never been written (upgrade from a pre-heads store).
  */
 export declare class GithubPollSource implements TriggerSourcePort {
     private readonly store;
@@ -84,3 +101,4 @@ export declare class GithubPollSource implements TriggerSourcePort {
     private pollRepo;
     private fireSafely;
 }
+export {};

package/dist/runtime/githubPollSource.js

@@ -50,31 +50,99 @@ export function defaultCreateGithubClient(token) {
                     created_at: pr.created_at,
                     updated_at: pr.updated_at,
                     user: pr.user ? { login: pr.user.login } : null,
+                    head_sha: pr.head?.sha ?? null,
                 })),
             };
         },
     };
 }
-function deriveAction(item) {
+const HEADS_LIMIT = 200;
+function isCreatedAfterCursor(item, cursor) {
+    const createdMs = new Date(item.created_at).getTime();
+    const cursorMs = new Date(cursor.updatedAt).getTime();
+    if (createdMs !== cursorMs)
+        return createdMs > cursorMs;
+    return item.number > cursor.number;
+}
+/**
+ * Classify a PR list delta into a normalized GitHub action.
+ *
+ * `opened` is reserved for brand-new PRs: equal created/updated timestamps, or
+ * first sight of a number whose `created_at` is after the poll cursor. A missing
+ * prior head SHA alone is not enough — that also happens on upgrade (no `heads`
+ * row yet), eviction, or a cold PR falling into the poll window.
+ */
+export function deriveGithubAction(item, previousHeadSha, cursor = null) {
     if (item.merged_at)
         return "merged";
     if (item.state === "closed")
         return "closed";
     if (item.created_at === item.updated_at)
         return "opened";
+    if (previousHeadSha === undefined) {
+        if (cursor !== null && isCreatedAfterCursor(item, cursor))
+            return "opened";
+        return "updated";
+    }
+    const currentSha = item.head_sha ?? null;
+    if (previousHeadSha !== "" &&
+        currentSha !== null &&
+        currentSha !== previousHeadSha) {
+        return "synchronize";
+    }
     return "updated";
 }
-function normalizeGithubItem(item, repo) {
+function normalizeGithubItem(item, repo, previousHeadSha, cursor) {
+    const headSha = item.head_sha ?? null;
     return {
-        action: deriveAction(item),
+        action: deriveGithubAction(item, previousHeadSha, cursor),
         number: item.number,
         title: item.title,
         url: item.html_url,
         author: item.user?.login ?? "unknown",
         repo,
         updatedAt: item.updated_at,
+        ...(headSha ? { headSha } : {}),
     };
 }
+function parseHeads(raw) {
+    if (raw === null)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const out = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === "string")
+                out[key] = value;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function seedHeadsFromItems(items) {
+    const heads = {};
+    for (const item of items) {
+        const sha = item.head_sha ?? null;
+        if (sha)
+            heads[String(item.number)] = sha;
+    }
+    return heads;
+}
+function boundHeads(heads, currentItems) {
+    if (Object.keys(heads).length <= HEADS_LIMIT)
+        return heads;
+    const currentNumbers = new Set(currentItems.map((item) => String(item.number)));
+    const next = {};
+    for (const [key, value] of Object.entries(heads)) {
+        if (currentNumbers.has(key))
+            next[key] = value;
+    }
+    return next;
+}
 function parseCursor(raw) {
     if (raw === null)
         return null;
@@ -111,9 +179,11 @@ function firstSecretRef(matches) {
  * per tick regardless of how many triggers watch it), and diffs each repo's
  * PR list against a persisted ETag + cursor to find genuinely new activity.
  *
- * The first tick for a never-before-seen repo only seeds the cursor — it
- * never fires for a repo's pre-existing PR history, mirroring how
- * `ScheduleSource` seeds `next_run_at` without firing on first sight.
+ * The first tick for a never-before-seen repo only seeds the cursor and
+ * per-PR head SHAs — it never fires for a repo's pre-existing PR history,
+ * mirroring how `ScheduleSource` seeds `next_run_at` without firing on
+ * first sight. The same quiet baseline runs when a cursor already exists
+ * but `heads` has never been written (upgrade from a pre-heads store).
  */
 export class GithubPollSource {
     store;
@@ -217,6 +287,8 @@ export class GithubPollSource {
         const adapterId = `github:${repo}`;
         const etag = await this.store.getTriggerAdapterState(adapterId, "etag");
         const cursor = parseCursor(await this.store.getTriggerAdapterState(adapterId, "cursor"));
+        const headsRaw = await this.store.getTriggerAdapterState(adapterId, "heads");
+        let heads = parseHeads(headsRaw);
         const [owner, repoName] = repo.split("/");
         let response;
         try {
@@ -239,13 +311,24 @@ export class GithubPollSource {
         if (response.items.length === 0)
             return;
         const newest = response.items[0];
-        if (cursor === null) {
+        // First sight, or upgrade from a pre-heads store (cursor present, heads absent):
+        // baseline without firing so aged PRs are not misclassified as opened.
+        if (cursor === null || headsRaw === null) {
+            heads = seedHeadsFromItems(response.items);
+            await this.store.setTriggerAdapterState(adapterId, "heads", JSON.stringify(heads));
             await this.store.setTriggerAdapterState(adapterId, "cursor", JSON.stringify({ updatedAt: newest.updated_at, number: newest.number }));
             return;
         }
         const newItems = response.items.filter((item) => isNewerThanCursor(item, cursor)).reverse();
         for (const item of newItems) {
-            const summary = normalizeGithubItem(item, repo);
+            const numberKey = String(item.number);
+            const previousHeadSha = Object.prototype.hasOwnProperty.call(heads, numberKey) ? heads[numberKey] : undefined;
+            const summary = normalizeGithubItem(item, repo, previousHeadSha, cursor);
+            const nextSha = item.head_sha ?? null;
+            if (nextSha)
+                heads[numberKey] = nextSha;
+            else if (previousHeadSha !== undefined && previousHeadSha !== "")
+                heads[numberKey] = previousHeadSha;
             for (const match of matches) {
                 const { definition } = match;
                 if (!matchesEventFilter(definition.event?.match, summary))
@@ -253,6 +336,8 @@ export class GithubPollSource {
                 await this.fireSafely(onFire, match, summary);
             }
         }
+        heads = boundHeads(heads, response.items);
+        await this.store.setTriggerAdapterState(adapterId, "heads", JSON.stringify(heads));
         await this.store.setTriggerAdapterState(adapterId, "cursor", JSON.stringify({ updatedAt: newest.updated_at, number: newest.number }));
     }
     async fireSafely(onFire, match, summary) {

package/dist/runtime/priorArtifactGrants.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvePriorEnvelopeResult } from "./envelopeRouting.js";
+import type { StageArtifactGrant } from "./stageRoots.js";
+export { isGrantableArtifactPath } from "./artifactPath.js";
+/** Sandbox path for one artifact. Colliding names from different attempts include the attempt. */
+export declare function assignGrantContainerPaths(listedPaths: readonly string[]): Map<string, string>;
+export declare function artifactGrantsFromPriors(workspaceDir: string, prior: Extract<ResolvePriorEnvelopeResult, {
+    ok: true;
+}>): Promise<StageArtifactGrant[]>;

package/dist/runtime/priorArtifactGrants.js

@@ -0,0 +1,105 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+import { acceptArtifactListedPath, isGrantableArtifactPath, } from "./artifactPath.js";
+import { inspectArtifactUnderRoot } from "./artifactDiskInspect.js";
+import { SANDBOX_MOUNT_PATH } from "./sandboxContainer.js";
+export { isGrantableArtifactPath } from "./artifactPath.js";
+function successArtifactsFromPrior(prior) {
+    const envelopes = [];
+    if (prior.prior !== null && prior.prior !== undefined) {
+        envelopes.push(prior.prior);
+    }
+    if (prior.joinPriors !== undefined) {
+        envelopes.push(...prior.joinPriors);
+    }
+    if (prior.priorEnvelopesByStage !== undefined) {
+        for (const value of Object.values(prior.priorEnvelopesByStage)) {
+            if (Array.isArray(value))
+                envelopes.push(...value);
+            else
+                envelopes.push(value);
+        }
+    }
+    const listed = [];
+    for (const envelope of envelopes) {
+        if (envelope.status !== "success")
+            continue;
+        listed.push(...envelope.artifacts);
+    }
+    return listed;
+}
+/**
+ * Soft-skip grant host resolution: missing / symlink / non-file → null.
+ * Closed-posture walk via inspect; realpath must stay inside the workspace.
+ */
+async function resolveGrantableHostFile(workspaceRoot, listedPath) {
+    try {
+        const presence = await inspectArtifactUnderRoot(workspaceRoot, listedPath);
+        if (presence.file_type !== "file" || presence.absolutePath === undefined) {
+            return null;
+        }
+        const current = presence.absolutePath;
+        if (!isInsideDir(current, workspaceRoot) || current === workspaceRoot) {
+            return null;
+        }
+        const workspaceReal = await realpath(workspaceRoot);
+        const fileReal = await realpath(current);
+        if (!isInsideDir(fileReal, workspaceReal) || fileReal === workspaceReal) {
+            return null;
+        }
+        return current;
+    }
+    catch {
+        return null;
+    }
+}
+/** Sandbox path for one artifact. Colliding names from different attempts include the attempt. */
+export function assignGrantContainerPaths(listedPaths) {
+    const parsed = listedPaths.map((listedPath) => {
+        const parts = acceptArtifactListedPath(listedPath, { kind: "grantable" });
+        const base = parts === undefined
+            ? null
+            : `${SANDBOX_MOUNT_PATH}/grants/${parts.stageId}/${parts.relative}`;
+        return { listedPath, parts, base };
+    });
+    const counts = new Map();
+    for (const item of parsed) {
+        if (item.base === null)
+            continue;
+        counts.set(item.base, (counts.get(item.base) ?? 0) + 1);
+    }
+    const assigned = new Map();
+    for (const item of parsed) {
+        if (item.parts === undefined || item.base === null)
+            continue;
+        const containerPath = (counts.get(item.base) ?? 0) > 1
+            ? `${SANDBOX_MOUNT_PATH}/grants/${item.parts.stageId}/attempt-${item.parts.attempt}/${item.parts.relative}`
+            : item.base;
+        assigned.set(item.listedPath, containerPath);
+    }
+    return assigned;
+}
+export async function artifactGrantsFromPriors(workspaceDir, prior) {
+    const workspaceRoot = path.resolve(workspaceDir);
+    const listed = successArtifactsFromPrior(prior).filter(isGrantableArtifactPath);
+    const containerPaths = assignGrantContainerPaths(listed);
+    const grants = [];
+    const seen = new Set();
+    for (const listedPath of listed) {
+        const containerPath = containerPaths.get(listedPath);
+        if (containerPath === undefined)
+            continue;
+        const hostPath = await resolveGrantableHostFile(workspaceRoot, listedPath);
+        if (hostPath === null || seen.has(hostPath))
+            continue;
+        seen.add(hostPath);
+        grants.push({
+            listedPath,
+            hostPath,
+            containerPath,
+            kind: "file",
+        });
+    }
+    return grants;
+}

package/dist/runtime/runActionEligibility.d.ts

@@ -0,0 +1,46 @@
+import { type RunDetail, type RunPipelineDagSnapshot, type RunStatus, type StageSnapshot } from "../runstore/port.js";
+export type StageRetrySubject = Pick<StageSnapshot, "stage_id" | "status" | "definition_id" | "envelope">;
+export type RunActionEligibilityInput = {
+    runStatus: RunStatus;
+    stage?: StageRetrySubject;
+    stages?: ReadonlyArray<Pick<StageSnapshot, "status" | "stage_id">>;
+    recoveryActive?: boolean;
+    dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null;
+};
+export type RunActionEligibility = {
+    canRetry: boolean;
+    canCancel: boolean;
+    canAbandon: boolean;
+    blockers: string[];
+};
+export declare function resumesRunOnStageRetry(status: RunStatus): boolean;
+export declare function canCancelRun(status: RunStatus): boolean;
+export declare function canAbandonStage(stageStatus: string): boolean;
+export declare function succeededStageRetryBlocker(stageSnap: StageRetrySubject): string | undefined;
+export declare function stageRetryBlocker(input: {
+    runStatus: RunStatus;
+    stage: StageRetrySubject;
+    stages?: ReadonlyArray<Pick<StageSnapshot, "status" | "stage_id">>;
+    recoveryActive?: boolean;
+    dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null;
+}): string | undefined;
+export declare function canRetryStage(input: {
+    runStatus: RunStatus;
+    stage: StageRetrySubject;
+    stages?: ReadonlyArray<Pick<StageSnapshot, "status" | "stage_id">>;
+    recoveryActive?: boolean;
+    dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null;
+}): boolean;
+export declare function runActionEligibility(input: RunActionEligibilityInput): RunActionEligibility;
+export declare function assertStageRetryEligible(detail: RunDetail, stageId: string, opts?: {
+    recoveryActive?: boolean;
+    persistedStatus?: RunStatus;
+    dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    status: number;
+    code: string;
+};

package/dist/runtime/runActionEligibility.js

@@ -0,0 +1,123 @@
+import { findUnhandledFailedStage, } from "../runstore/port.js";
+import { isRunClockTerminal } from "../runstore/runStatusClock.js";
+export function resumesRunOnStageRetry(status) {
+    return isRunClockTerminal(status);
+}
+export function canCancelRun(status) {
+    return status !== "succeeded" && status !== "failed";
+}
+export function canAbandonStage(stageStatus) {
+    return stageStatus === "running";
+}
+export function succeededStageRetryBlocker(stageSnap) {
+    if (stageSnap.definition_id !== undefined &&
+        stageSnap.definition_id !== stageSnap.stage_id) {
+        return `Cannot re-run a succeeded clone instance stage (stage=${stageSnap.stage_id}, definition=${stageSnap.definition_id}): clone instances are created by upstream fan-out and cannot be rebuilt in place. Use rerun to start a new run.`;
+    }
+    if (stageSnap.envelope?.fork_choice !== undefined) {
+        return `Cannot re-run a succeeded fork stage (stage=${stageSnap.stage_id}): its envelope recorded a fork_choice and skipped branches cannot be restored. Use rerun to start a new run.`;
+    }
+    return undefined;
+}
+export function stageRetryBlocker(input) {
+    const { stage, runStatus } = input;
+    if (stage.status === "waiting_for_input") {
+        return `Stage is waiting for input and cannot be retried`;
+    }
+    const recoveryActive = input.recoveryActive === true;
+    if (!resumesRunOnStageRetry(runStatus)) {
+        const stages = input.stages ?? [];
+        const acceptedPendingRetry = runStatus === "running" &&
+            stage.status === "failed" &&
+            findUnhandledFailedStage(stages, input.dag) === undefined &&
+            stages.some((s) => s.status === "pending");
+        if (!(runStatus === "running" && recoveryActive) && !acceptedPendingRetry) {
+            return `Run is not failed or succeeded (status=${runStatus})`;
+        }
+    }
+    if (stage.status !== "failed" && stage.status !== "succeeded") {
+        return `Stage is not failed or succeeded (status=${stage.status})`;
+    }
+    if (stage.status === "succeeded") {
+        return succeededStageRetryBlocker(stage);
+    }
+    return undefined;
+}
+export function canRetryStage(input) {
+    return stageRetryBlocker(input) === undefined;
+}
+export function runActionEligibility(input) {
+    const blockers = [];
+    const canCancel = canCancelRun(input.runStatus);
+    if (!canCancel) {
+        blockers.push(`Run is ${input.runStatus} and cannot be cancelled`);
+    }
+    const canAbandon = input.stage !== undefined && canAbandonStage(input.stage.status);
+    if (input.stage !== undefined && !canAbandon) {
+        blockers.push(`Stage is not running (status=${input.stage.status})`);
+    }
+    let canRetry = false;
+    if (input.stage === undefined) {
+        blockers.push("Stage is required to retry");
+    }
+    else {
+        const retryBlocker = stageRetryBlocker({
+            runStatus: input.runStatus,
+            stage: input.stage,
+            stages: input.stages,
+            recoveryActive: input.recoveryActive,
+            dag: input.dag,
+        });
+        if (retryBlocker === undefined) {
+            canRetry = true;
+        }
+        else {
+            blockers.push(retryBlocker);
+        }
+    }
+    return { canRetry, canCancel, canAbandon, blockers };
+}
+export function assertStageRetryEligible(detail, stageId, opts) {
+    const stageSnap = detail.stages.find((s) => s.stage_id === stageId);
+    if (!stageSnap) {
+        return {
+            ok: false,
+            reason: `Stage not found: ${stageId}`,
+            status: 404,
+            code: "stage_not_found",
+        };
+    }
+    const runStatus = opts?.persistedStatus ?? detail.status;
+    const blocker = stageRetryBlocker({
+        runStatus,
+        stage: stageSnap,
+        stages: detail.stages,
+        recoveryActive: opts?.recoveryActive,
+        dag: opts?.dag,
+    });
+    if (blocker === undefined) {
+        return { ok: true };
+    }
+    if (blocker.includes("waiting for input")) {
+        return {
+            ok: false,
+            reason: blocker,
+            status: 409,
+            code: "hitl_not_retriable",
+        };
+    }
+    if (blocker.startsWith("Stage is not failed or succeeded")) {
+        return {
+            ok: false,
+            reason: blocker,
+            status: 409,
+            code: "stage_not_failed",
+        };
+    }
+    return {
+        ok: false,
+        reason: blocker,
+        status: 409,
+        code: "run_not_retryable",
+    };
+}