pi-subagents 0.80.0 → 0.82.0

package/src/workflows/workflow-resources.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { stableJsonDigest } from "../shared/launch-contract.js";
 import { createWorkflowResourcePermit, } from "../shared/workflow-child-permit.js";
-import { buildStructuredWorkflowScript, isPlainRecord } from "./structured-workflow-scripts.js";
+import { buildStructuredWorkflowScript, isPlainRecord, TOP_LEVEL_CONTROLS_HINT } from "./structured-workflow-scripts.js";
 const RESOURCE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 export const MAX_ARGS_BYTES = 16 * 1024;
 export const MAX_ARGS_FIELDS = 16;
@@ -152,7 +152,7 @@ function resolveRunCi(args) {
 function resolveParallel(args) {
     const unsupported = Object.keys(args).filter((key) => key !== "tasks");
     if (unsupported.length > 0)
-        return { error: `workflow 'parallel' args contain unsupported fields: ${unsupported.join(", ")}. Pass args.tasks: [{ agent, task, cwd?, model? }, ...].` };
+        return { error: `workflow 'parallel' args contain unsupported fields: ${unsupported.join(", ")}. Pass args.tasks: [{ agent, task, cwd?, model? }, ...].${TOP_LEVEL_CONTROLS_HINT}` };
     try {
         return { script: buildStructuredWorkflowScript("tasks", args.tasks, undefined) };
     }

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 {};

package/src/workflows/workflow-resume.js

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { normalizePublicSubagentExecution } from "../extension/public-execution.js";
+import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.js";
+import { ownsRun } from "../runs/shared/run-ownership.js";
+import { readStatus } from "../shared/utils.js";
+import { readWorkflowLaunchRecord } from "./workflow-launch-record.js";
+import { claimWorkflowResume, refusalSentence, relaunchByHandText, resumeByHandText } from "./workflow-resume-claim.js";
+import { workflowScriptDigest } from "./workflow-reuse.js";
+import { isRunId } from "./workflow-revival.js";
+import { isReusableWorkflowStopCause, WORKFLOW_STOP_CAUSE_OWNER_EXITED } from "./workflow-stop-cause.js";
+/** A run may be resumed again after at most this many resumes that followed Pi exits (auto-resume only). */
+const MAX_WORKFLOW_RESUME_ATTEMPTS = 3;
+export function workflowResumeRefusal(code, reason, runId) {
+    const byHand = code === "launch-missing" || code === "launch-invalid" || code === "structured" || code === "digest" || code === "authority"
+        ? relaunchByHandText(runId)
+        : code === "capacity" || code === "attempts" || code === "launch-failed" ? resumeByHandText(runId) : "";
+    return { code, reason, byHand };
+}
+/** The tool error for a resume by id; the resume form is not repeated to a caller that just tried it. */
+export function manualWorkflowResumeRefusalText(runId, refusal) {
+    return `Cannot resume workflow '${runId}': ${refusalSentence(refusal.reason, refusal.byHand === relaunchByHandText(runId) ? refusal.byHand : "")}`;
+}
+/**
+ * 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 function workflowResumeTargetId(asyncDirRoot, params) {
+    if (params.message !== undefined || params.task !== undefined || params.index !== undefined)
+        return undefined;
+    if (Array.isArray(params.chain) && params.chain.length > 0)
+        return undefined;
+    const id = params.id ?? params.runId;
+    if (!isRunId(id))
+        return undefined;
+    let status;
+    try {
+        status = readStatus(path.join(asyncDirRoot, id));
+    }
+    catch {
+        return undefined;
+    }
+    return status?.mode === "workflow" && status.parentWorkflowRunId === undefined ? id : 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 function prepareWorkflowResume(input) {
+    const { asyncDirRoot, sourceRunId, trigger } = input;
+    const refuse = (code, reason) => ({ ok: false, ...workflowResumeRefusal(code, reason, sourceRunId) });
+    const sourceAsyncDir = path.join(asyncDirRoot, sourceRunId);
+    // Only the session that owns the run (itself or one it replaced) may resume it, and nothing is
+    // written into another session's run, so this comes before the reconcile.
+    const stored = readStatus(sourceAsyncDir);
+    if (stored && !ownsRun(input.currentSessionId, stored.sessionId))
+        return refuse("not-owned", "it was started in another session; reopen that session to resume it");
+    // Session start has already reconciled this session's runs; a resume by id may come later.
+    if (trigger === "manual")
+        reconcileAsyncRun(sourceAsyncDir);
+    const status = readStatus(sourceAsyncDir);
+    if (!status || status.mode !== "workflow" || !isReusableWorkflowStopCause(status.workflow?.stopCause))
+        return refuse("not-interrupted", "not interrupted; pass message to revive one of its children");
+    // The attempt the resumed run records: only resumes that follow a Pi exit count.
+    const attempt = (status.workflow?.resumeOrigin?.attempt ?? 0) + (status.workflow?.stopCause === WORKFLOW_STOP_CAUSE_OWNER_EXITED ? 1 : 0);
+    if (trigger === "auto" && attempt > MAX_WORKFLOW_RESUME_ATTEMPTS)
+        return refuse("attempts", `${MAX_WORKFLOW_RESUME_ATTEMPTS} resumes already followed Pi exits`);
+    const read = readWorkflowLaunchRecord(sourceAsyncDir);
+    if (!read.ok)
+        return read.missing ? refuse("launch-missing", "launch.json is missing (the run started before launches were saved)") : refuse("launch-invalid", `launch.json is invalid: ${read.error}`);
+    const record = read.record;
+    if (record.source === "structured")
+        return refuse("structured", "launched from tasks/chain");
+    if (record.source === "script" && (typeof record.params.workflowScript !== "string" || workflowScriptDigest(record.params.workflowScript) !== record.scriptDigest)) {
+        return refuse("launch-invalid", "launch.json is invalid: its script does not match its scriptDigest");
+    }
+    const normalized = normalizePublicSubagentExecution(record.params);
+    if (!normalized.ok)
+        return refuse("launch-invalid", `launch.json is invalid: ${normalized.error}`);
+    const newRunId = input.newRunId ?? randomUUID();
+    const claim = claimWorkflowResume(sourceAsyncDir, { newRunId, trigger, now: input.now });
+    if (claim.kind === "resumed")
+        return refuse("claim-resumed", `resumed as ${claim.newRunId}; wait on it or stop it`);
+    if (claim.kind === "busy")
+        return refuse("claim-busy", `being resumed by pid ${claim.pid}`);
+    if (claim.kind === "unreadable")
+        return refuse("claim-busy", "its resume claim cannot be read; wait or remove it");
+    return {
+        ok: true,
+        prepared: {
+            sourceRunId,
+            sourceAsyncDir,
+            newRunId,
+            trigger,
+            params: {
+                ...record.params,
+                async: true,
+                reuseFrom: sourceRunId,
+                ...(status.admissionCapabilityCeiling ? { capabilityCeiling: status.admissionCapabilityCeiling } : {}),
+            },
+            expectedScriptDigest: record.scriptDigest,
+            resumeOrigin: { sourceRunId, attempt },
+        },
+    };
+}

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

@@ -1,11 +1,11 @@
+import { type WorkflowResumeClaimOutcome } from "./workflow-resume-claim.ts";
 import { type WorkflowScriptChildResult } from "./scripted-workflow.ts";
-/** Stop cause recorded when the extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
-declare const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
-type WorkflowStopCause = typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED;
-export declare function workflowRuntimeReplacedRelaunchNotice(runId: string): string;
+import { WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED } from "./workflow-stop-cause.ts";
+/** What a runtime replacement left; the notice's resume line says how the run continues. */
+export declare const WORKFLOW_RUNTIME_REPLACED_STOP_NOTICE = "Async children that were still running keep running, and finished children are kept.";
 /** Abort reason for workflow controllers torn down by runtime replacement; carries the cause as data, not text. */
 export declare function runtimeReplacedAbortReason(): Error;
-export declare function workflowStopCause(reason: unknown): WorkflowStopCause | undefined;
+export declare function workflowStopCause(reason: unknown): typeof WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED | undefined;
 export declare function workflowScriptDigest(script: string): string;
 /** Hash of the canonical launch params the script host uses to detect duplicate keys. */
 export declare function workflowChildFingerprint(params: Record<string, unknown>): string;
@@ -40,16 +40,22 @@ type WorkflowReuseMatch = {
     kind: "started";
     runId: string;
 };
+/** Why a relaunch of `runId` is refused when another relaunch already continues it. */
+export declare function claimedWorkflowRunRefusal(runId: string, claim: Exclude<WorkflowResumeClaimOutcome, {
+    kind: "owner";
+}>, named: boolean): string;
 /**
  * The newest terminal workflow of this session with the same script and args,
- * when that run stopped because its runtime was replaced.
+ * when that run stopped because its runtime was replaced or its Pi process exited.
+ * Throws when another relaunch already continues that run.
  */
 export declare function findWorkflowReuseSource(asyncDirRoot: string, sessionId: string, scriptDigest: string, argsDigest: string | undefined): WorkflowReuseSource | undefined;
 /**
- * The runtime-replaced workflow run named by `options.reuseFrom`, from any session. Only the script
- * must match: each child is still reused only when its key and launch params match.
+ * The interrupted workflow run named by `options.reuseFrom`, from any session. Only the script
+ * must match: each child is still reused only when its key and launch params match. The run is
+ * reconciled first, so a run whose Pi process died is marked `owner-exited` before it is read.
  */
-export declare function readNamedWorkflowReuseSource(asyncDirRoot: string, runId: string, scriptDigest: string, cwd: string): WorkflowReuseSource;
+export declare function readNamedWorkflowReuseSource(asyncDirRoot: string, runId: string, scriptDigest: string, cwd: string, claimOwnerRunId?: string): WorkflowReuseSource;
 /** A settled match is reusable only when that child succeeded; failed or stopped children run again. */
 export declare function matchWorkflowReuse(source: WorkflowReuseSource, key: string, fingerprint: string): WorkflowReuseMatch | undefined;
 export {};

package/src/workflows/workflow-reuse.js

@@ -2,14 +2,15 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readRecentTerminalRunIndex } from "../runs/background/terminal-run-index.js";
+import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.js";
 import { readStatus } from "../shared/utils.js";
+import { workflowResumeClaimState } from "./workflow-resume-claim.js";
+import { isRunId } from "./workflow-revival.js";
 import { workflowRunParamsFingerprint } from "./scripted-workflow.js";
-/** Stop cause recorded when the extension runtime that owned the workflow was replaced (/reload, resume, project switch). */
-const WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED = "runtime-replaced";
+import { isReusableWorkflowStopCause, WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED } from "./workflow-stop-cause.js";
 const WORKFLOW_CHILD_JOURNAL_FILE = "workflow-children.jsonl";
-export function workflowRuntimeReplacedRelaunchNotice(runId) {
-    return `Async children that were still running keep running. Relaunching the same workflow script with the same args from this session reuses finished children and re-attaches to running ones; from another session, add options: { reuseFrom: "${runId}" }.`;
-}
+/** What a runtime replacement left; the notice's resume line says how the run continues. */
+export const WORKFLOW_RUNTIME_REPLACED_STOP_NOTICE = "Async children that were still running keep running, and finished children are kept.";
 /** Abort reason for workflow controllers torn down by runtime replacement; carries the cause as data, not text. */
 export function runtimeReplacedAbortReason() {
     return Object.assign(new Error("Workflow stopped because the extension session was replaced or reloaded."), { workflowStopCause: WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED });
@@ -67,9 +68,63 @@ function readWorkflowChildJournal(runId, workflowAsyncDir) {
     }
     return source;
 }
+const WORKFLOW_REUSE_CHAIN_MAX_LINKS = 16;
+/**
+ * The head run's journal plus the journals of the runs it was relaunched from (`workflow.reusedFrom`).
+ * A child's start record is written only once it gets a concurrency slot, so a key the head never
+ * reached is still in an earlier run's journal. For each key the newest run that recorded it wins. A
+ * status file is parsed, not validated, so a corrupt `reusedFrom` may be any JSON value.
+ */
+function readWorkflowReuseChain(asyncDirRoot, headRunId, headStatus) {
+    const source = readWorkflowChildJournal(headRunId, path.join(asyncDirRoot, headRunId));
+    const visited = new Set([headRunId]);
+    let next = headStatus.workflow?.reusedFrom;
+    for (let links = 0; isRunId(next) && links < WORKFLOW_REUSE_CHAIN_MAX_LINKS && !visited.has(next); links++) {
+        visited.add(next);
+        const asyncDir = path.join(asyncDirRoot, next);
+        let status;
+        try {
+            status = readStatus(asyncDir);
+        }
+        catch {
+            break;
+        }
+        if (status?.mode !== "workflow" || status.workflow?.scriptDigest !== headStatus.workflow?.scriptDigest)
+            break;
+        const link = readWorkflowChildJournal(next, asyncDir);
+        for (const key of new Set([...link.started.keys(), ...link.settled.keys()])) {
+            if (source.started.has(key) || source.settled.has(key))
+                continue;
+            const started = link.started.get(key);
+            const settled = link.settled.get(key);
+            if (started)
+                source.started.set(key, started);
+            if (settled)
+                source.settled.set(key, settled);
+        }
+        next = status.workflow?.reusedFrom;
+    }
+    return source;
+}
+/** Why a relaunch of `runId` is refused when another relaunch already continues it. */
+export function claimedWorkflowRunRefusal(runId, claim, named) {
+    const run = `${named ? "options.reuseFrom: workflow" : "Workflow"} run '${runId}'`;
+    if (claim.kind === "resumed")
+        return `${run} was resumed as ${claim.newRunId}; wait on it or stop it.`;
+    if (claim.kind === "busy")
+        return `${run} is being resumed by pid ${claim.pid}; wait for it.`;
+    return `${run} has a resume claim that cannot be read; wait or remove it.`;
+}
+function assertWorkflowRunNotClaimed(asyncDir, runId, named, claimOwnerRunId) {
+    const claim = workflowResumeClaimState(asyncDir);
+    if (claim.kind === "none" || (claim.kind !== "unreadable" && claim.newRunId === claimOwnerRunId))
+        return;
+    throw new Error(claimedWorkflowRunRefusal(runId, claim, named));
+}
 /**
  * The newest terminal workflow of this session with the same script and args,
- * when that run stopped because its runtime was replaced.
+ * when that run stopped because its runtime was replaced or its Pi process exited.
+ * Throws when another relaunch already continues that run.
  */
 export function findWorkflowReuseSource(asyncDirRoot, sessionId, scriptDigest, argsDigest) {
     let runIds;
@@ -90,28 +145,36 @@ export function findWorkflowReuseSource(asyncDirRoot, sessionId, scriptDigest, a
         }
         if (status?.mode !== "workflow" || status.workflow?.scriptDigest !== scriptDigest || status.workflow.argsDigest !== argsDigest)
             continue;
-        return status.workflow.stopCause === WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED ? readWorkflowChildJournal(runId, asyncDir) : undefined;
+        if (!isReusableWorkflowStopCause(status.workflow.stopCause))
+            return undefined;
+        assertWorkflowRunNotClaimed(asyncDir, runId, false);
+        return readWorkflowReuseChain(asyncDirRoot, runId, status);
     }
     return undefined;
 }
 /**
- * The runtime-replaced workflow run named by `options.reuseFrom`, from any session. Only the script
- * must match: each child is still reused only when its key and launch params match.
+ * The interrupted workflow run named by `options.reuseFrom`, from any session. Only the script
+ * must match: each child is still reused only when its key and launch params match. The run is
+ * reconciled first, so a run whose Pi process died is marked `owner-exited` before it is read.
  */
-export function readNamedWorkflowReuseSource(asyncDirRoot, runId, scriptDigest, cwd) {
+export function readNamedWorkflowReuseSource(asyncDirRoot, runId, scriptDigest, cwd, claimOwnerRunId) {
     // A user-supplied id: it must name one run directory, never a path.
-    const status = runId === path.basename(runId) && runId !== "." && runId !== ".." ? readStatus(path.join(asyncDirRoot, runId)) : null;
+    const runName = isRunId(runId);
+    if (runName)
+        reconcileAsyncRun(path.join(asyncDirRoot, runId));
+    const status = runName ? readStatus(path.join(asyncDirRoot, runId)) : null;
     if (!status)
         throw new Error(`options.reuseFrom: workflow run '${runId}' was not found.`);
     if (status.mode !== "workflow")
         throw new Error(`options.reuseFrom: run '${runId}' is not a workflow run.`);
-    if (status.workflow?.stopCause !== WORKFLOW_STOP_CAUSE_RUNTIME_REPLACED)
-        throw new Error(`options.reuseFrom: workflow run '${runId}' did not stop because its session was replaced, so its children cannot be reused.`);
+    if (!isReusableWorkflowStopCause(status.workflow?.stopCause))
+        throw new Error(`options.reuseFrom: workflow run '${runId}' did not stop because its session was replaced or its Pi process exited, so its children cannot be reused.`);
     if (status.workflow.scriptDigest !== scriptDigest)
         throw new Error(`options.reuseFrom: workflow run '${runId}' ran a different workflow script.`);
     if (status.cwd !== cwd)
         throw new Error(`options.reuseFrom: workflow run '${runId}' ran in '${status.cwd}', not '${cwd}'.`);
-    return readWorkflowChildJournal(runId, path.join(asyncDirRoot, runId));
+    assertWorkflowRunNotClaimed(path.join(asyncDirRoot, runId), runId, true, claimOwnerRunId);
+    return readWorkflowReuseChain(asyncDirRoot, runId, status);
 }
 /** A settled match is reusable only when that child succeeded; failed or stopped children run again. */
 export function matchWorkflowReuse(source, key, fingerprint) {