pi-subagents 0.81.0 → 0.82.1

package/src/workflows/scripted-workflow.d.ts

@@ -60,7 +60,7 @@ export interface WorkflowScriptChildResult {
     };
     artifactPaths: string[];
     results?: SingleResult[];
-    /** Came from a runtime-replaced run of the same script (and args, unless named by options.reuseFrom): its saved result, or its still-running child re-attached; this run launched nothing. */
+    /** Came from a runtime-replaced or owner-exited run of the same script (and args, unless named by options.reuseFrom): its saved result, or its still-running child re-attached; this run launched nothing. */
     reused?: boolean;
 }
 export interface WorkflowScriptTraceEntry {

package/src/workflows/workflow-auto-resume.d.ts

@@ -0,0 +1,32 @@
+import { type PreparedWorkflowResume, type WorkflowResumeRefusalReason } from "./workflow-resume.ts";
+/** Custom message posted when an auto-resume launch did not start. */
+export declare const WORKFLOW_AUTO_RESUME_MESSAGE_TYPE = "subagent-auto-resume";
+/** One planned auto-resume: its claim is held from session start until the launch starts or is cancelled. */
+export interface PendingWorkflowAutoResume {
+    readonly sessionId: string;
+    /** The extension runtime that planned it. */
+    readonly owner: object;
+    readonly prepared: PreparedWorkflowResume;
+    /** `cancelled` before it started: its run id is reused by the next scan. */
+    state: "pending" | "started" | "cancelled";
+}
+/** Cancels matching launches that have not started and gives their claims back, synchronously. */
+export declare function cancelPendingWorkflowAutoResumes(match: (entry: PendingWorkflowAutoResume) => boolean): void;
+/** A cancelled entry stays recorded until its session's next scan reuses its run id. */
+export declare function finishWorkflowAutoResume(entry: PendingWorkflowAutoResume): void;
+/**
+ * Claims this session's interrupted top-level workflows for auto-resume. Synchronous and bounded:
+ * one listing of the session's terminal index, reads only for runs that ended in the last 24 h,
+ * then the cheap filters before any claim. A refusal is recorded in the run, so each run gets one
+ * automatic attempt; the launch itself happens later, off session start. Launches of this session
+ * that another runtime (or an earlier session start) planned but did not start are cancelled first,
+ * so their claims do not hide the runs from this scan.
+ */
+export declare function planWorkflowAutoResumes(input: {
+    asyncDirRoot: string;
+    currentSessionId: string;
+    now: number;
+    owner: object;
+}): PendingWorkflowAutoResume[];
+/** The one line posted when an auto-resume launch did not start. */
+export declare function autoResumeFailureText(sourceRunId: string, refusal: Pick<WorkflowResumeRefusalReason, "reason" | "byHand">): string;

package/src/workflows/workflow-auto-resume.js

@@ -0,0 +1,102 @@
+import * as path from "node:path";
+import { readRecentTerminalRunIndex } from "../runs/background/terminal-run-index.js";
+import { readStatus } from "../shared/utils.js";
+import { hasWorkflowResumeRefusal, recordWorkflowResumeRefusal, refusalSentence, releaseWorkflowResumeClaim, workflowResumeClaimState } from "./workflow-resume-claim.js";
+import { prepareWorkflowResume } from "./workflow-resume.js";
+import { isReusableWorkflowStopCause, WORKFLOW_STOP_CAUSE_OWNER_EXITED } from "./workflow-stop-cause.js";
+/** Custom message posted when an auto-resume launch did not start. */
+export const WORKFLOW_AUTO_RESUME_MESSAGE_TYPE = "subagent-auto-resume";
+/** Interrupted workflows older than this are left for a resume by hand. */
+const AUTO_RESUME_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const AUTO_RESUME_SCAN_LIMIT = 50;
+/** When the run was interrupted: the dead owner's last update, or the runtime replacement. */
+function interruptedAt(status) {
+    return status.workflow?.stopCause === WORKFLOW_STOP_CAUSE_OWNER_EXITED ? status.workflow.ownerExitedAt : status.endedAt;
+}
+// Shared by every runtime in the process: a reload's new runtime must see the old runtime's pending claims.
+const registryKey = Symbol.for("pi-subagents.workflow-auto-resume.v1");
+const registryGlobal = globalThis;
+const pendingAutoResumes = registryGlobal[registryKey] ?? (registryGlobal[registryKey] = new Set());
+/** Cancels matching launches that have not started and gives their claims back, synchronously. */
+export function cancelPendingWorkflowAutoResumes(match) {
+    for (const entry of pendingAutoResumes) {
+        if (entry.state !== "pending" || !match(entry))
+            continue;
+        // It stays in the set, so the next scan of its session claims the run again under the same id and
+        // a notice that already said `Auto-resumed as <id>.` stays true.
+        entry.state = "cancelled";
+        try {
+            releaseWorkflowResumeClaim(entry.prepared.sourceAsyncDir, entry.prepared.newRunId);
+        }
+        catch (error) {
+            console.error(`Failed to give back the auto-resume claim of workflow ${entry.prepared.sourceRunId}:`, error);
+        }
+    }
+}
+/** A cancelled entry stays recorded until its session's next scan reuses its run id. */
+export function finishWorkflowAutoResume(entry) {
+    if (entry.state !== "cancelled")
+        pendingAutoResumes.delete(entry);
+}
+/**
+ * Claims this session's interrupted top-level workflows for auto-resume. Synchronous and bounded:
+ * one listing of the session's terminal index, reads only for runs that ended in the last 24 h,
+ * then the cheap filters before any claim. A refusal is recorded in the run, so each run gets one
+ * automatic attempt; the launch itself happens later, off session start. Launches of this session
+ * that another runtime (or an earlier session start) planned but did not start are cancelled first,
+ * so their claims do not hide the runs from this scan.
+ */
+export function planWorkflowAutoResumes(input) {
+    const { asyncDirRoot, currentSessionId, now } = input;
+    cancelPendingWorkflowAutoResumes((entry) => entry.sessionId === currentSessionId);
+    const reusableRunIds = new Map();
+    for (const entry of pendingAutoResumes) {
+        if (entry.sessionId !== currentSessionId || entry.state !== "cancelled")
+            continue;
+        reusableRunIds.set(entry.prepared.sourceRunId, entry.prepared.newRunId);
+        pendingAutoResumes.delete(entry);
+    }
+    let runIds;
+    try {
+        runIds = readRecentTerminalRunIndex(asyncDirRoot, { sessionId: currentSessionId, limit: AUTO_RESUME_SCAN_LIMIT, endedAfter: now - AUTO_RESUME_MAX_AGE_MS });
+    }
+    catch (error) {
+        console.error("Failed to read interrupted workflows for auto-resume:", error);
+        return [];
+    }
+    const planned = [];
+    for (const runId of runIds) {
+        const asyncDir = path.join(asyncDirRoot, runId);
+        try {
+            const status = readStatus(asyncDir);
+            if (!status || status.mode !== "workflow" || status.parentWorkflowRunId !== undefined || status.sessionId !== currentSessionId)
+                continue;
+            if (!isReusableWorkflowStopCause(status.workflow?.stopCause))
+                continue;
+            const at = interruptedAt(status);
+            if (at === undefined || now - at > AUTO_RESUME_MAX_AGE_MS)
+                continue;
+            if (workflowResumeClaimState(asyncDir).kind !== "none" || hasWorkflowResumeRefusal(asyncDir))
+                continue;
+            const preparation = prepareWorkflowResume({ asyncDirRoot, sourceRunId: runId, trigger: "auto", now, currentSessionId, newRunId: reusableRunIds.get(runId) });
+            if (preparation.ok) {
+                const entry = { sessionId: currentSessionId, owner: input.owner, prepared: preparation.prepared, state: "pending" };
+                pendingAutoResumes.add(entry);
+                planned.push(entry);
+                continue;
+            }
+            // Another claimant continues it; nothing to record.
+            if (preparation.code === "claim-busy" || preparation.code === "claim-resumed")
+                continue;
+            recordWorkflowResumeRefusal(asyncDir, { reason: preparation.reason, byHand: preparation.byHand }, now);
+        }
+        catch (error) {
+            console.error(`Failed to prepare auto-resume of workflow ${runId}:`, error);
+        }
+    }
+    return planned;
+}
+/** The one line posted when an auto-resume launch did not start. */
+export function autoResumeFailureText(sourceRunId, refusal) {
+    return `Workflow ${sourceRunId} was not auto-resumed: ${refusalSentence(refusal.reason, refusal.byHand)}`;
+}

package/src/workflows/workflow-launch-record.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The public launch of an async top-level workflow, saved in its run directory so the run can be
+ * relaunched later. A named resource is saved by name (its `runs.host` permit cannot be saved);
+ * structured tasks/chain launches save no params, so they cannot be relaunched from this record.
+ */
+export type WorkflowLaunch = {
+    source: "script" | "resource";
+    params: Record<string, unknown>;
+} | {
+    source: "structured";
+};
+export type WorkflowLaunchRecord = WorkflowLaunch & {
+    version: 1;
+    scriptDigest: string;
+};
+type WorkflowLaunchRecordRead = {
+    ok: true;
+    record: WorkflowLaunchRecord;
+} | {
+    ok: false;
+    missing: boolean;
+    error: string;
+};
+/** Throws on a write failure; the launch must fail rather than start a run it cannot relaunch. */
+export declare function writeWorkflowLaunchRecord(asyncDir: string, record: WorkflowLaunchRecord): void;
+export declare function readWorkflowLaunchRecord(asyncDir: string): WorkflowLaunchRecordRead;
+export {};

package/src/workflows/workflow-launch-record.js

@@ -0,0 +1,48 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../shared/atomic-json.js";
+const WORKFLOW_LAUNCH_RECORD_FILE = "launch.json";
+function launchRecordPath(asyncDir) {
+    return path.join(asyncDir, WORKFLOW_LAUNCH_RECORD_FILE);
+}
+/** Throws on a write failure; the launch must fail rather than start a run it cannot relaunch. */
+export function writeWorkflowLaunchRecord(asyncDir, record) {
+    writeAtomicJson(launchRecordPath(asyncDir), record);
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function invalid(error) {
+    return { ok: false, missing: false, error };
+}
+export function readWorkflowLaunchRecord(asyncDir) {
+    let text;
+    try {
+        text = fs.readFileSync(launchRecordPath(asyncDir), "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { ok: false, missing: true, error: "launch.json is missing" };
+        return invalid(`could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        return invalid(`not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isPlainObject(value))
+        return invalid("not a JSON object");
+    if (value.version !== 1)
+        return invalid("version must be 1");
+    if (typeof value.scriptDigest !== "string" || !value.scriptDigest)
+        return invalid("scriptDigest must be a non-empty string");
+    if (value.source === "structured")
+        return { ok: true, record: { version: 1, source: "structured", scriptDigest: value.scriptDigest } };
+    if (value.source !== "script" && value.source !== "resource")
+        return invalid("source must be \"script\", \"resource\", or \"structured\"");
+    if (!isPlainObject(value.params))
+        return invalid("params must be an object");
+    return { ok: true, record: { version: 1, source: value.source, params: value.params, scriptDigest: value.scriptDigest } };
+}

package/src/workflows/workflow-resume-claim.d.ts

@@ -0,0 +1,82 @@
+import { type PidLiveness, type RecordedPid } from "../runs/background/stale-run-reconciler.ts";
+/**
+ * Who continues a stopped workflow run. Claims are generation files `resumed-by.<n>.json` in the
+ * stopped run's directory, and the highest n is the current claim. A claimant whose process is dead
+ * is superseded by creating the next generation, so a takeover never moves a file another taker
+ * may have just created. An owner whose launch did not start renames its own claim to
+ * `resumed-by.<n>.json.released-<uuid>`; a released top means no claim, and the next taker creates
+ * n+1, so claims below it are never judged again. Only the owner launches; once the claimed new
+ * run's status.json exists the claim is permanent.
+ */
+interface WorkflowResumeClaim extends RecordedPid {
+    version: 1;
+    claimedAt: number;
+    newRunId: string;
+    trigger: "auto" | "manual" | "reuse";
+}
+interface WorkflowResumeRefusal {
+    version: 1;
+    reason: string;
+    byHand: string;
+    newRunId?: string;
+    refusedAt: number;
+}
+export type WorkflowResumeClaimOutcome = {
+    kind: "owner";
+} | {
+    kind: "resumed";
+    newRunId: string;
+} | {
+    kind: "busy";
+    pid: number;
+}
+/** The current claim file exists but cannot be read, so nothing proves its claimant dead. */
+ | {
+    kind: "unreadable";
+};
+type WorkflowResumeClaimState = {
+    kind: "none";
+} | {
+    kind: "resumed";
+    newRunId: string;
+} | {
+    kind: "busy";
+    pid: number;
+    newRunId: string;
+} | {
+    kind: "unreadable";
+};
+type ClaimLiveness = (claim: WorkflowResumeClaim) => PidLiveness;
+export declare function readWorkflowResumeClaim(asyncDir: string): WorkflowResumeClaim | undefined;
+/** True once the run that resumes the run in `sourceAsyncDir` as `newRunId` has written its first status. */
+export declare function resumedRunStarted(sourceAsyncDir: string, newRunId: string): boolean;
+/** Read-only view for reuse readers and auto-resume: a dead, corrupt, or missing claim blocks nothing. */
+export declare function workflowResumeClaimState(asyncDir: string, options?: {
+    liveness?: ClaimLiveness;
+}): WorkflowResumeClaimState;
+/**
+ * Claims the right to continue the stopped run in `asyncDir` as `newRunId`. A dead claimant is
+ * superseded by the next generation file; of several takers, the one whose exclusive create
+ * succeeds owns the run, and the others see its live claim on their next read.
+ */
+export declare function claimWorkflowResume(asyncDir: string, input: {
+    newRunId: string;
+    trigger: WorkflowResumeClaim["trigger"];
+    now?: number;
+    liveness?: ClaimLiveness;
+}): WorkflowResumeClaimOutcome;
+/** Gives up this process's claim on a launch that did not start, so the run can be continued again. */
+export declare function releaseWorkflowResumeClaim(asyncDir: string, newRunId: string): void;
+export declare function recordWorkflowResumeRefusal(asyncDir: string, refusal: Omit<WorkflowResumeRefusal, "version" | "refusedAt">, now?: number): void;
+export declare function resumeByHandText(runId: string): string;
+export declare function relaunchByHandText(runId: string): string;
+/** `<reason>. <byHand>`; some reasons quote a message that already ends in a period. */
+export declare function refusalSentence(reason: string, byHand: string): string;
+/** A refusal was recorded for this run; the run is not tried again automatically. */
+export declare function hasWorkflowResumeRefusal(asyncDir: string): boolean;
+/**
+ * The one line an interrupted workflow's notice carries about what happens next: the recorded
+ * auto-resume refusal, else who continues the run, else how to continue it by hand.
+ */
+export declare function describeWorkflowResume(asyncDir: string, runId: string): string;
+export {};

package/src/workflows/workflow-resume-claim.js

@@ -0,0 +1,210 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../shared/atomic-json.js";
+import { currentBootId, currentRecordedPid } from "../runs/background/boot-id.js";
+import { currentPidNamespaceScope } from "../runs/background/pid-namespace.js";
+import { checkRecordedPidLiveness, isRecordedPid } from "../runs/background/stale-run-reconciler.js";
+import { readWorkflowLaunchRecord } from "./workflow-launch-record.js";
+const CLAIM_FILE_PATTERN = /^resumed-by\.([1-9][0-9]*)\.json$/;
+const RELEASED_CLAIM_FILE_PATTERN = /^resumed-by\.([1-9][0-9]*)\.json\.released-/;
+const REFUSAL_FILE = "resume-refused.json";
+const MAX_CLAIM_ROUNDS = 8;
+// Claims this process holds, shared by every runtime in the process so a reload keeps them.
+const heldClaimsKey = Symbol.for("pi-subagents.workflow-resume-claims.v1");
+const heldClaimsGlobal = globalThis;
+const heldClaims = heldClaimsGlobal[heldClaimsKey] ?? (heldClaimsGlobal[heldClaimsKey] = new Set());
+function claimFilePath(asyncDir, generation) {
+    return path.join(asyncDir, `resumed-by.${generation}.json`);
+}
+function isClaim(value) {
+    if (!isRecordedPid(value) || Array.isArray(value))
+        return false;
+    const claim = value;
+    return claim.version === 1
+        && typeof claim.claimedAt === "number"
+        && typeof claim.newRunId === "string" && claim.newRunId.length > 0
+        && (claim.trigger === "auto" || claim.trigger === "manual" || claim.trigger === "reuse");
+}
+function readTopClaim(asyncDir, retries = 3) {
+    let generation = 0;
+    let releasedGeneration = 0;
+    try {
+        for (const name of fs.readdirSync(asyncDir)) {
+            const live = CLAIM_FILE_PATTERN.exec(name);
+            if (live)
+                generation = Math.max(generation, Number(live[1]));
+            const released = RELEASED_CLAIM_FILE_PATTERN.exec(name);
+            if (released)
+                releasedGeneration = Math.max(releasedGeneration, Number(released[1]));
+        }
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? { kind: "open", generation: 0 } : { kind: "unreadable" };
+    }
+    // A live file and a released one with the same n: the live one was created after the release.
+    if (releasedGeneration > generation || generation === 0)
+        return { kind: "open", generation: Math.max(releasedGeneration, generation) };
+    const filePath = claimFilePath(asyncDir, generation);
+    let text;
+    try {
+        text = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        // A release renamed it after the listing: look again.
+        if (error.code === "ENOENT" && retries > 0)
+            return readTopClaim(asyncDir, retries - 1);
+        return { kind: "unreadable" };
+    }
+    try {
+        const value = JSON.parse(text);
+        // The file is created whole, so a body that does not parse is corrupt, not half-written.
+        return isClaim(value) ? { kind: "claim", generation, filePath, claim: value } : { kind: "open", generation };
+    }
+    catch {
+        return { kind: "open", generation };
+    }
+}
+export function readWorkflowResumeClaim(asyncDir) {
+    const top = readTopClaim(asyncDir);
+    return top.kind === "claim" ? top.claim : undefined;
+}
+/** True once the run that resumes the run in `sourceAsyncDir` as `newRunId` has written its first status. */
+export function resumedRunStarted(sourceAsyncDir, newRunId) {
+    return path.basename(newRunId) === newRunId
+        && fs.existsSync(path.join(path.dirname(sourceAsyncDir), newRunId, "status.json"));
+}
+function claimantLiveness(filePath, claim, liveness) {
+    // A reload keeps the pid, so this process's own claim counts only while one of its runtimes holds
+    // it. The same pid in another pid namespace (a container sharing the temp root) is another process.
+    if (claim.pid === process.pid && claim.bootId === currentBootId() && claim.pidNamespaceScope === currentPidNamespaceScope())
+        return heldClaims.has(filePath) ? "alive" : "dead";
+    return liveness ? liveness(claim) : checkRecordedPidLiveness(claim);
+}
+/** Read-only view for reuse readers and auto-resume: a dead, corrupt, or missing claim blocks nothing. */
+export function workflowResumeClaimState(asyncDir, options = {}) {
+    const top = readTopClaim(asyncDir);
+    if (top.kind === "unreadable")
+        return { kind: "unreadable" };
+    if (top.kind !== "claim")
+        return { kind: "none" };
+    if (resumedRunStarted(asyncDir, top.claim.newRunId))
+        return { kind: "resumed", newRunId: top.claim.newRunId };
+    return claimantLiveness(top.filePath, top.claim, options.liveness) === "dead" ? { kind: "none" } : { kind: "busy", pid: top.claim.pid, newRunId: top.claim.newRunId };
+}
+/** Creates the claim file only if none exists, with its whole body in place at once. */
+function createClaimFile(filePath, claim) {
+    const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(tempPath, JSON.stringify(claim, null, 2), "utf-8");
+        fs.linkSync(tempPath, filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    finally {
+        fs.rmSync(tempPath, { force: true });
+    }
+}
+/**
+ * Claims the right to continue the stopped run in `asyncDir` as `newRunId`. A dead claimant is
+ * superseded by the next generation file; of several takers, the one whose exclusive create
+ * succeeds owns the run, and the others see its live claim on their next read.
+ */
+export function claimWorkflowResume(asyncDir, input) {
+    const claim = {
+        version: 1,
+        ...currentRecordedPid(),
+        claimedAt: input.now ?? Date.now(),
+        newRunId: input.newRunId,
+        trigger: input.trigger,
+    };
+    for (let round = 0; round < MAX_CLAIM_ROUNDS; round++) {
+        const top = readTopClaim(asyncDir);
+        if (top.kind === "unreadable")
+            return { kind: "unreadable" };
+        if (top.kind === "claim") {
+            // Already claimed for this exact new run, as a resume does before it launches.
+            if (top.claim.newRunId === input.newRunId && top.claim.pid === process.pid) {
+                heldClaims.add(top.filePath);
+                return { kind: "owner" };
+            }
+            if (resumedRunStarted(asyncDir, top.claim.newRunId))
+                return { kind: "resumed", newRunId: top.claim.newRunId };
+            if (claimantLiveness(top.filePath, top.claim, input.liveness) !== "dead")
+                return { kind: "busy", pid: top.claim.pid };
+        }
+        const filePath = claimFilePath(asyncDir, top.generation + 1);
+        if (createClaimFile(filePath, claim)) {
+            heldClaims.add(filePath);
+            return { kind: "owner" };
+        }
+        // Another taker created that generation first: decide again from its claim.
+    }
+    // Every round lost to another taker; fail closed with whatever claim is there now.
+    const top = readTopClaim(asyncDir);
+    return top.kind === "claim" ? { kind: "busy", pid: top.claim.pid } : { kind: "unreadable" };
+}
+/** Gives up this process's claim on a launch that did not start, so the run can be continued again. */
+export function releaseWorkflowResumeClaim(asyncDir, newRunId) {
+    const top = readTopClaim(asyncDir);
+    if (top.kind !== "claim" || top.claim.newRunId !== newRunId || top.claim.pid !== process.pid)
+        return;
+    // The only rename in the protocol: the owner moves its own claim aside.
+    try {
+        fs.renameSync(top.filePath, `${top.filePath}.released-${randomUUID()}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    heldClaims.delete(top.filePath);
+}
+export function recordWorkflowResumeRefusal(asyncDir, refusal, now = Date.now()) {
+    writeAtomicJson(path.join(asyncDir, REFUSAL_FILE), { version: 1, ...refusal, refusedAt: now });
+}
+function readWorkflowResumeRefusal(asyncDir) {
+    try {
+        const value = JSON.parse(fs.readFileSync(path.join(asyncDir, REFUSAL_FILE), "utf-8"));
+        return value?.version === 1 && typeof value.reason === "string" && typeof value.byHand === "string" && typeof value.refusedAt === "number"
+            && (value.newRunId === undefined || typeof value.newRunId === "string")
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resumeByHandText(runId) {
+    return `Resume by hand: subagent({ action: "resume", id: "${runId}" })`;
+}
+export function relaunchByHandText(runId) {
+    return `Relaunch it by hand with options: { reuseFrom: "${runId}" }.`;
+}
+/** `<reason>. <byHand>`; some reasons quote a message that already ends in a period. */
+export function refusalSentence(reason, byHand) {
+    return `${reason.replace(/\.$/, "")}.${byHand ? ` ${byHand}` : ""}`;
+}
+/** A refusal was recorded for this run; the run is not tried again automatically. */
+export function hasWorkflowResumeRefusal(asyncDir) {
+    return fs.existsSync(path.join(asyncDir, REFUSAL_FILE));
+}
+const RESUMED_AS = { auto: "Auto-resumed as", manual: "Resumed as", reuse: "Relaunched as" };
+/**
+ * The one line an interrupted workflow's notice carries about what happens next: the recorded
+ * auto-resume refusal, else who continues the run, else how to continue it by hand.
+ */
+export function describeWorkflowResume(asyncDir, runId) {
+    const claim = readWorkflowResumeClaim(asyncDir);
+    const refusal = readWorkflowResumeRefusal(asyncDir);
+    if (refusal && (!claim || refusal.newRunId === claim.newRunId)) {
+        return `Not auto-resumed: ${refusalSentence(refusal.reason, refusal.byHand)}`;
+    }
+    if (claim)
+        return `${RESUMED_AS[claim.trigger]} ${claim.newRunId}.`;
+    const launch = readWorkflowLaunchRecord(asyncDir);
+    return launch.ok && launch.record.source !== "structured" ? resumeByHandText(runId) : relaunchByHandText(runId);
+}

package/src/workflows/workflow-resume.d.ts

@@ -0,0 +1,56 @@
+type WorkflowResumeTrigger = "auto" | "manual";
+export type WorkflowResumeRefusalCode = "not-owned" | "not-interrupted" | "claim-busy" | "claim-resumed" | "launch-missing" | "launch-invalid" | "structured" | "digest" | "authority" | "capacity" | "attempts" | "launch-failed";
+export interface WorkflowResumeRefusalReason {
+    code: WorkflowResumeRefusalCode;
+    reason: string;
+    /** How to continue the run by hand; empty when there is nothing to add. */
+    byHand: string;
+}
+export interface PreparedWorkflowResume {
+    sourceRunId: string;
+    sourceAsyncDir: string;
+    newRunId: string;
+    trigger: WorkflowResumeTrigger;
+    /** Public launch params for executePublic: the saved launch with async, reuseFrom and the source's ceiling. */
+    params: Record<string, unknown>;
+    expectedScriptDigest: string;
+    resumeOrigin: {
+        sourceRunId: string;
+        attempt: number;
+    };
+}
+type WorkflowResumePreparation = {
+    ok: true;
+    prepared: PreparedWorkflowResume;
+} | ({
+    ok: false;
+} & WorkflowResumeRefusalReason);
+export declare function workflowResumeRefusal(code: WorkflowResumeRefusalCode, reason: string, runId: string): WorkflowResumeRefusalReason;
+/** The tool error for a resume by id; the resume form is not repeated to a caller that just tried it. */
+export declare function manualWorkflowResumeRefusalText(runId: string, refusal: Pick<WorkflowResumeRefusalReason, "reason" | "byHand">): string;
+/**
+ * The run id a resume action relaunches: no message, task, chain or index, and an id naming a
+ * top-level workflow run. Anything else is a child resume.
+ */
+export declare function workflowResumeTargetId(asyncDirRoot: string, params: {
+    id?: unknown;
+    runId?: unknown;
+    message?: unknown;
+    task?: unknown;
+    chain?: unknown;
+    index?: unknown;
+}): string | undefined;
+/**
+ * Checks a stopped workflow run can be resumed and claims it for a new run id. Synchronous and
+ * cheap: the launch itself happens in the executor.
+ * `newRunId` presets the new run's id: a reload claims a run again under the id of the launch it cancelled.
+ */
+export declare function prepareWorkflowResume(input: {
+    asyncDirRoot: string;
+    sourceRunId: string;
+    trigger: WorkflowResumeTrigger;
+    now: number;
+    currentSessionId: string;
+    newRunId?: string;
+}): WorkflowResumePreparation;
+export {};