@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/dist/public-cli/post-admission.js

@@ -0,0 +1,667 @@
+/**
+ * Unified post-admission Role lifecycle coordinator (stages ③–⑤; ADR 0018 / #505 / #517 / #526).
+ * Owns writer lease → running → ③ dispatch → ④ tool loop / gates → ⑤ settle / fail →
+ * terminal → release. The durable admitted mark (markRunAdmitted) is owned by the
+ * initial role facades before entering; manual resume never re-admits.
+ * Role runners supply only turn request projection and narrow settlement adapters.
+ */
+import { randomUUID } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { buildResumeContinuationPrompt, } from "./run-lifecycle.js";
+import { CliUsageError } from "./cli-errors.js";
+import { buildInstructionTransportPrompt, freezeAttachmentsIntoRun, } from "./invocation.js";
+import { pathContainedIn } from "../activation-ledger-topology.js";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.js";
+import { projectHostTransitionPriorNative } from "../host-transition-prior-native.js";
+import { missingCredentialPreDispatchFailure, postRunMissingCredentialFailure, } from "./public-run-credentials.js";
+import { acquireRunWriterLease, clearCurrentCourt, clearTypedProviderHttpObservation, markRunResumable, markRunRunning, markRunTerminal, readCurrentCourt, recordCurrentCourt, renderResumeCommand, RunWriterLeaseHeldError, } from "./run-lifecycle.js";
+import { homeFromRunDirectory } from "../activation-ledger-topology.js";
+import { readSealedSubmission } from "../submission-ledger.js";
+import { classifyPostAdmissionFailure, controlledFailureInputFromResolution, exitCodeForTerminalOutcome, explicitInternalKnownFailureClassificationInput, formatCliDiagnostic, formatTerminalResult, inspectJudgeSession, isLawfulTypedTerminalOutcome, presentFailureTerminal, presentStructuralRejection, resolveAuditedRunnerFailureResolution, resolveControlledFailureResumeObservation, settleFailureTerminalResult, sealedAcceptanceRedispatchDisposition, } from "./settlement.js";
+import {} from "./terminal.js";
+import { runWithAutoResumeLoop } from "./auto-resume.js";
+/** Previous main-session host recorded on invocation.json, if any. */
+async function readInvocationHost(runDirectory) {
+    try {
+        const raw = JSON.parse(await readFile(join(runDirectory, "invocation.json"), "utf8"));
+        return typeof raw.host === "string" && raw.host.trim() !== "" ? raw.host : undefined;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function presentControlledFailure(admitted, failureInput, adapters, authority, io) {
+    const hasThrown = Object.hasOwn(failureInput, "thrown");
+    const resumeObservation = await resolveControlledFailureResumeObservation({
+        runDirectory: admitted.runDirectory,
+        ...(failureInput.typedHttpObservationSettled === true
+            ? {
+                typedHttpObservationSettled: true,
+                ...(failureInput.typedHttpObservation === undefined
+                    ? {}
+                    : { typedHttpObservation: failureInput.typedHttpObservation }),
+            }
+            : {}),
+    });
+    const knownFailure = failureInput.knownFailure ?? resumeObservation.observationReadFailure;
+    const session = !hasThrown &&
+        !failureInput.timedOut &&
+        knownFailure === undefined &&
+        failureInput.knownCause === undefined &&
+        admitted.principal !== undefined
+        ? await inspectJudgeSession(authority.decode(admitted.principal).sessionFile)
+        : undefined;
+    // knownFailure channel owns details when present; otherwise caller knownDetails.
+    const fromKnownFailure = explicitInternalKnownFailureClassificationInput(knownFailure);
+    const failure = classifyPostAdmissionFailure({
+        timedOut: failureInput.timedOut,
+        code: failureInput.code,
+        stderr: failureInput.stderr,
+        ...(hasThrown ? { thrown: failureInput.thrown } : {}),
+        ...(failureInput.knownDetails === undefined
+            ? {}
+            : { knownDetails: failureInput.knownDetails }),
+        ...fromKnownFailure,
+        ...(failureInput.knownCause === undefined
+            ? {}
+            : { knownCause: failureInput.knownCause }),
+        ...(failureInput.knownIdentity === undefined
+            ? {}
+            : { knownIdentity: failureInput.knownIdentity }),
+        ...(failureInput.knownDiagnostic === undefined
+            ? {}
+            : { knownDiagnostic: failureInput.knownDiagnostic }),
+        ...(session === undefined ? {} : { session }),
+    });
+    // #665 / #416: resume hint is seat-uniform — principal available && typed 429 → show.
+    // Do not fork the public terminal face on per-seat hasLawful / isResumableRole (ADR 0040).
+    let resumable = false;
+    const typedHttp429 = resumeObservation.typedHttp429;
+    if (admitted.principal !== undefined) {
+        const sessionPrincipalAvailable = await authority.isAvailable(admitted.principal);
+        resumable = sessionPrincipalAvailable && typedHttp429 !== undefined;
+    }
+    if (resumable && typedHttp429 !== undefined) {
+        await markRunResumable(admitted.runDirectory, typedHttp429);
+    }
+    else {
+        await markRunTerminal(admitted.runDirectory);
+    }
+    const terminal = await settleFailureTerminalResult(admitted, failure, authority, resumable
+        ? { resume: { command: renderResumeCommand(admitted.runId) } }
+        : {});
+    presentFailureTerminal(terminal, io);
+    return {
+        exitCode: exitCodeForTerminalOutcome(terminal.roleOutcome),
+        admitted,
+        terminal,
+    };
+}
+export async function dispatchPostAdmissionTurn(input) {
+    const { admitted, env, io, request, lease, adapters, effectiveEngine } = input;
+    const shouldPresent = adapters.shouldPresentSettled ?? ((terminal) => isLawfulTypedTerminalOutcome(terminal.roleOutcome));
+    try {
+        const missingCredential = missingCredentialPreDispatchFailure(env.model, env.credentials);
+        if (missingCredential !== undefined) {
+            return (await presentControlledFailure(admitted, missingCredential, adapters, env.principalAuthority, io));
+        }
+        // #617 DK-4: capture previous invocation host before markRunRunning overwrites it.
+        // Single authority projectHostTransitionPriorNative classifies the prior native volume.
+        // Same-run resume (#637) keeps host identity on the run's invocation page.
+        let previousHost;
+        const liveHost = env.host;
+        const principalCoordinates = admitted.principal === undefined
+            ? undefined
+            : env.principalAuthority.decode(admitted.principal);
+        let turnRequest;
+        try {
+            previousHost = await readInvocationHost(admitted.runDirectory);
+            const hostTransition = previousHost !== undefined && liveHost !== undefined && principalCoordinates !== undefined
+                ? await projectHostTransitionPriorNative({
+                    previousHost,
+                    liveHost,
+                    piSessionFile: principalCoordinates.sessionFile,
+                })
+                : undefined;
+            turnRequest = env.signal === undefined ? request : { ...request, signal: env.signal };
+            if (hostTransition !== undefined) {
+                turnRequest = { ...turnRequest, hostTransition };
+            }
+        }
+        catch (error) {
+            // prior-native IO is on the public one-shot path — controlled failure, not bare throw.
+            return (await presentControlledFailure(admitted, {
+                timedOut: false,
+                code: null,
+                stderr: "",
+                thrown: error,
+            }, adapters, env.principalAuthority, io));
+        }
+        await markRunRunning(admitted.runDirectory, env.model, effectiveEngine, env.host);
+        await clearTypedProviderHttpObservation(admitted.runDirectory);
+        // beforeDispatch (seat-owned pre-turn work) runs after running is marked —
+        // its failures must settle the run, not leave it permanently running.
+        if (adapters.beforeDispatch !== undefined) {
+            try {
+                await adapters.beforeDispatch(admitted);
+            }
+            catch (error) {
+                return (await presentControlledFailure(admitted, {
+                    timedOut: false,
+                    code: null,
+                    stderr: "",
+                    thrown: error,
+                }, adapters, env.principalAuthority, io));
+            }
+        }
+        let result;
+        try {
+            result = await env.roleTurnHost.executeTurn(turnRequest);
+        }
+        catch (error) {
+            return (await presentControlledFailure(admitted, {
+                timedOut: false,
+                code: null,
+                stderr: "",
+                thrown: error,
+            }, adapters, env.principalAuthority, io));
+        }
+        try {
+            await writeFile(join(admitted.runDirectory, "stderr.log"), result.stderr, "utf8");
+        }
+        catch {
+            // continue to lawful / controlled-failure settlement
+        }
+        let settled;
+        // Same-ticket re-summons carry courtAttemptId — settle only that attempt so a
+        // prior sealed pass cannot wash this turn's missing/escalated/failed result.
+        const courtScope = request.courtAttemptId === undefined || request.courtAttemptId.length === 0
+            ? undefined
+            : { courtAttemptId: request.courtAttemptId };
+        try {
+            settled = await adapters.trySettle(admitted, env.principalAuthority, courtScope);
+        }
+        catch (error) {
+            // Settle throw is a real failure fact — never swallow into undefined.
+            return (await presentControlledFailure(admitted, {
+                timedOut: false,
+                code: result.code,
+                stderr: result.stderr,
+                thrown: error,
+            }, adapters, env.principalAuthority, io));
+        }
+        if (settled !== undefined && shouldPresent(settled)) {
+            // This court sealed — drop open-court pointer so bare resume is run-scoped idempotent.
+            if (settled.roleOutcome.kind === "accepted" &&
+                request.courtAttemptId !== undefined &&
+                request.courtAttemptId.length > 0) {
+                await clearCurrentCourt(admitted.runDirectory, request.courtAttemptId);
+            }
+            await markRunTerminal(admitted.runDirectory);
+            io.stdout(formatTerminalResult(settled));
+            return {
+                exitCode: exitCodeForTerminalOutcome(settled.roleOutcome),
+                admitted,
+                terminal: settled,
+            };
+        }
+        const sessionFile = admitted.principal !== undefined
+            ? env.principalAuthority.decode(admitted.principal).sessionFile
+            : "";
+        const runnerKnownFailure = adapters.resolveRunnerKnownFailure !== undefined && sessionFile !== ""
+            ? await adapters.resolveRunnerKnownFailure({ result, sessionFile })
+            : result.knownFailure;
+        const credentialFailure = postRunMissingCredentialFailure(result, env.model, env.credentials);
+        const resolution = await resolveAuditedRunnerFailureResolution({
+            runner: runnerKnownFailure,
+            sessionFile,
+            credential: credentialFailure,
+            runDirectory: admitted.runDirectory,
+        });
+        return (await presentControlledFailure(admitted, {
+            timedOut: result.timedOut,
+            code: result.code,
+            stderr: result.stderr,
+            ...controlledFailureInputFromResolution(resolution),
+        }, adapters, env.principalAuthority, io));
+    }
+    finally {
+        await lease.release();
+    }
+}
+/**
+ * Shared resume continuation projection (#471 / #600 / #633 / #637): seat-table
+ * model/engine/timeout axes, restored correlation, and either
+ * - manual resume: package envelope / optional caller message (unchanged), or
+ * - same-ticket summons: this turn's instruction + frozen attachment paths.
+ * Caller message and summons materials each keep their place: a resume message
+ * keeps manual-resume prompt semantics while open-court frozen attachments still
+ * ride; summons instruction is only the prompt base when no caller message.
+ * Seats add only their activation projection. Call prepareSummonsResumeMaterials
+ * first when request.summons carries attachment paths.
+ */
+export function resumeTurnRequestProjectionOptions(admitted, request, env, summonsPrepared) {
+    const engineMaterial = engineSessionMaterialFromOptions({
+        ...(env.engine === undefined ? {} : { engine: env.engine }),
+        packageRoot: env.packageRoot,
+    });
+    let prompt;
+    if (request.message !== undefined) {
+        // Manual resume caller-message semantics stay authoritative for the prompt:
+        // message present → base bytes unchanged (including blank/whitespace).
+        // Open-court frozen attachments still continue when present; attachment
+        // projection must not re-interpret the caller message as instructionEmpty.
+        if (summonsPrepared !== undefined &&
+            summonsPrepared.attachments.length > 0) {
+            prompt = buildInstructionTransportPrompt({
+                instruction: request.message,
+                instructionEmpty: false,
+                attachments: summonsPrepared.attachments,
+            }, engineMaterial);
+        }
+        else {
+            prompt = buildResumeContinuationPrompt({
+                packageRoot: env.packageRoot,
+                ...(env.engine === undefined ? {} : { engine: env.engine }),
+                message: request.message,
+            });
+        }
+    }
+    else if (summonsPrepared !== undefined) {
+        prompt = buildInstructionTransportPrompt(summonsPrepared, engineMaterial);
+    }
+    else {
+        prompt = buildResumeContinuationPrompt({
+            packageRoot: env.packageRoot,
+            ...(env.engine === undefined ? {} : { engine: env.engine }),
+        });
+    }
+    return {
+        packageRoot: env.packageRoot,
+        home: env.home,
+        agentDir: env.agentDir,
+        ...(env.model === undefined ? {} : { model: env.model }),
+        ...(env.engine === undefined ? {} : { engine: env.engine }),
+        ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+        ...(admitted.correlationId === undefined && env.correlationId === undefined
+            ? {}
+            : { correlationId: admitted.correlationId ?? env.correlationId }),
+        continuation: {
+            kind: "resume",
+            prompt,
+        },
+    };
+}
+function isAlreadyFrozenSummonsAttachment(runDirectory, attachmentPath) {
+    const absolute = isAbsolute(attachmentPath)
+        ? attachmentPath
+        : resolve(attachmentPath);
+    return pathContainedIn(join(runDirectory, "attachments"), absolute);
+}
+/**
+ * Freeze same-ticket summons attachments into the retained run directory (#637).
+ * No-op materials (no paths / instruction-only) skip the freeze.
+ * Paths already under this run's attachments/ are the accepted freeze identity —
+ * reuse them; do not re-freeze from external originals on bare resume.
+ * Manual resume never calls this — old attachment semantics stay intact.
+ */
+export async function prepareSummonsResumeMaterials(runDirectory, summons) {
+    if (summons === undefined)
+        return undefined;
+    if (summons.instruction === undefined && (summons.attachmentPaths?.length ?? 0) === 0) {
+        return undefined;
+    }
+    const instruction = summons.instruction ?? "";
+    const instructionEmpty = summons.instructionEmpty ?? instruction.trim() === "";
+    let attachments = [];
+    if (summons.attachmentPaths !== undefined && summons.attachmentPaths.length > 0) {
+        const alreadyFrozen = summons.attachmentPaths.every((path) => isAlreadyFrozenSummonsAttachment(runDirectory, path));
+        attachments = alreadyFrozen
+            ? summons.attachmentPaths.map((frozenPath) => ({ frozenPath }))
+            : await freezeAttachmentsIntoRun(summons.attachmentPaths, runDirectory);
+    }
+    return { instruction, instructionEmpty, attachments };
+}
+/**
+ * Shared manual-resume orchestration for seats whose continuation is the
+ * package resume envelope (#599 / #633): load → structural rejection → seat
+ * turn projection → runPostAdmissionManualResume. Seat-owned loader validation,
+ * turn builder, and adapters stay on the seat.
+ *
+ * Court open/recovery transaction (#637): under the existing writer lease,
+ * read currentCourt, judge seal, clear (bound to the judged court id), freeze,
+ * and record. No pre-lease clear or stale court-snapshot consumption.
+ */
+export async function runPostAdmissionSeatResume(input) {
+    let request = input.request;
+    // Load once for runDirectory / structural rejection; court identity is judged
+    // only after the writer lease is held (below).
+    let loaded;
+    try {
+        loaded = await input.load(request);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, input.io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    // Entire court recovery / open path runs after lease. forceContinuation skips
+    // the pre-lease sealed short-circuit; when the after-lease builder leaves no
+    // courtAttemptId, manual resume still presents run-scoped sealed idempotence
+    // under the same held lease.
+    try {
+        return await runPostAdmissionManualResume({
+            admitted: loaded.admitted,
+            env: input.env,
+            io: input.io,
+            adapters: input.adapters,
+            ...(input.effectiveEngine === undefined
+                ? {}
+                : { effectiveEngine: input.effectiveEngine }),
+            forceContinuation: true,
+            buildRequestAfterLease: async () => {
+                let openCourtAttemptId;
+                // Build uses the admitted judged under this lease (rehydrated when open
+                // court materials ride). Settlement identity stays on the outer admitted.
+                let admittedForBuild = loaded.admitted;
+                // Bare resume: read + seal-judge + bound clear only under the held lease.
+                if (request.summons === undefined) {
+                    const openCourt = await readCurrentCourt(admittedForBuild.runDirectory);
+                    if (openCourt !== undefined) {
+                        const sealedForOpen = await readSealedSubmission(admittedForBuild.projectRoot, admittedForBuild.runId, {
+                            home: homeFromRunDirectory(admittedForBuild.runDirectory),
+                            attemptId: openCourt.courtAttemptId,
+                        });
+                        if (sealedForOpen === undefined) {
+                            // Continue open court: same summons materials + existing courtAttemptId.
+                            // Caller message (if any) stays on the request — projection keeps it.
+                            openCourtAttemptId = openCourt.courtAttemptId;
+                            request = {
+                                runId: request.runId,
+                                ...(request.message === undefined
+                                    ? {}
+                                    : { message: request.message }),
+                                ...(openCourt.summons === undefined
+                                    ? {}
+                                    : { summons: openCourt.summons }),
+                            };
+                            if (openCourt.summons !== undefined) {
+                                const reloaded = await input.load(request);
+                                admittedForBuild = reloaded.admitted;
+                            }
+                        }
+                        else {
+                            // Open court already sealed — clear only the court id just judged.
+                            await clearCurrentCourt(admittedForBuild.runDirectory, openCourt.courtAttemptId);
+                        }
+                    }
+                }
+                // Freeze external paths once; rewrite summons to the frozen identity so
+                // currentCourt + later bare resume reuse the accepted snapshot.
+                if (request.summons !== undefined) {
+                    const prepared = await prepareSummonsResumeMaterials(admittedForBuild.runDirectory, request.summons);
+                    if (prepared !== undefined &&
+                        (request.summons.attachmentPaths?.length ?? 0) > 0) {
+                        request = {
+                            ...request,
+                            summons: {
+                                ...request.summons,
+                                attachmentPaths: prepared.attachments.map((attachment) => attachment.frozenPath),
+                            },
+                        };
+                    }
+                }
+                let turnRequest = await input.buildTurnRequest(admittedForBuild, request);
+                // Court path only when continuing an open court or opening a new summons court.
+                // Bare resume with no open court (or cleared sealed pointer) keeps no
+                // courtAttemptId so run-scoped sealed idempotence can present under lease.
+                if (openCourtAttemptId !== undefined || request.summons !== undefined) {
+                    const courtAttemptId = openCourtAttemptId ??
+                        (turnRequest.courtAttemptId !== undefined &&
+                            turnRequest.courtAttemptId.length > 0
+                            ? turnRequest.courtAttemptId
+                            : randomUUID());
+                    turnRequest = { ...turnRequest, courtAttemptId };
+                    if (openCourtAttemptId === undefined) {
+                        const court = {
+                            courtAttemptId,
+                            ...(request.summons === undefined
+                                ? {}
+                                : { summons: request.summons }),
+                        };
+                        await recordCurrentCourt(admittedForBuild.runDirectory, court);
+                    }
+                }
+                return turnRequest;
+            },
+        });
+    }
+    catch (error) {
+        // Open-court rehydrate load under lease may still surface seat structural
+        // rejection (e.g. notary rejects caller message) — same exit face as pre-lease.
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, input.io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+}
+/**
+ * Shared post-admission one-shot path: writer lease, then turn dispatch.
+ * Initial facades own the durable admitted mark (markRunAdmitted) before
+ * entering; manual resume never re-admits.
+ */
+export async function runPostAdmissionOneShot(input) {
+    const { admitted, env, io, request, adapters, effectiveEngine } = input;
+    let lease;
+    try {
+        lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
+    }
+    catch (error) {
+        if (error instanceof RunWriterLeaseHeldError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2, admitted };
+        }
+        throw error;
+    }
+    return await dispatchPostAdmissionTurn({
+        admitted,
+        env,
+        io,
+        request,
+        lease,
+        adapters,
+        ...(effectiveEngine === undefined ? {} : { effectiveEngine }),
+    });
+}
+/**
+ * Shared post-admission resumable path with auto-resume retry loop.
+ * Initial facades own the durable admitted mark before entering.
+ */
+export async function runPostAdmissionResumable(input) {
+    const { admitted, env, io, buildInitialRequest, buildResumeRequest, adapters, effectiveEngine } = input;
+    return runWithAutoResumeLoop({
+        admitted,
+        principalAuthority: env.principalAuthority,
+        io,
+        sessionAppender: env.sessionAppender,
+        autoResumeLimit: env.autoResumeLimit,
+        buildInitialPayload: buildInitialRequest,
+        buildResumePayload: buildResumeRequest,
+        sealedAcceptanceDisposition: () => sealedAcceptanceRedispatchDisposition(admitted),
+        dispatch: (request, lease, _isFirst, attemptIo) => dispatchPostAdmissionTurn({
+            admitted,
+            env: {
+                ...env,
+                ...(admitted.correlationId === undefined ? {} : { correlationId: admitted.correlationId }),
+            },
+            io: attemptIo,
+            request,
+            lease,
+            adapters,
+            // #600: every attempt (initial + auto-resume) writes seat engine when present.
+            ...(effectiveEngine === undefined ? {} : { effectiveEngine }),
+        }),
+    });
+}
+/**
+ * Single authority for manual-resume run-scoped sealed-accepted presentation
+ * (#599 / #648 / #672 / #637). Used both before lease (eager request path) and
+ * after court-recovery builder under lease when no courtAttemptId remains.
+ * Returns undefined to fall through to dispatch; never rebuilds the gate.
+ */
+async function presentSealedAcceptedManualResumeIfAny(input) {
+    const { admitted, env, io, adapters, shouldPresent } = input;
+    try {
+        const existing = await adapters.trySettle(admitted, env.principalAuthority);
+        if (existing !== undefined &&
+            existing.roleOutcome.kind === "accepted" &&
+            shouldPresent(existing)) {
+            existing.autoResumeCount = 0;
+            io.stdout(formatTerminalResult(existing));
+            return {
+                exitCode: exitCodeForTerminalOutcome(existing.roleOutcome),
+                admitted,
+                terminal: existing,
+            };
+        }
+    }
+    catch (error) {
+        // Settlement-owned sealed disposition: sealed accepted + publication/settle
+        // throw fail closed without redispatch; authority failure preserves cause.
+        const disposition = await sealedAcceptanceRedispatchDisposition(admitted);
+        if (disposition.kind === "block") {
+            return (await presentControlledFailure(admitted, {
+                timedOut: false,
+                code: null,
+                stderr: "",
+                thrown: disposition.reason === "authority-failed"
+                    ? disposition.cause
+                    : error,
+            }, adapters, env.principalAuthority, io));
+        }
+        // Pre-dispatch settle failure without a sealed accepted projection is not
+        // proof of seal; fall through to dispatch so the attempt path can settle
+        // or fail honestly.
+    }
+    return undefined;
+}
+/**
+ * Shared post-admission manual resume path: acquire writer lease and dispatch turn.
+ * When the submission ledger is already sealed, project that accepted terminal
+ * idempotently — do not dispatch a doomed turn that would append
+ * post-seal-anomaly and erase the sealed read (#599; keep #416 open load).
+ * Same-ticket re-summons (#637) pass forceContinuation + courtAttemptId so a new
+ * court turn still runs with this summons' materials despite a prior sealed
+ * acceptance, while submission-ledger sole-final stays per-attempt.
+ */
+export async function runPostAdmissionManualResume(input) {
+    const { admitted, env, io, adapters, effectiveEngine, forceContinuation, buildRequestAfterLease, } = input;
+    let request = input.request;
+    // #617 DK-3: manual resume writes the live seat/env model (same as new legs).
+    const effectiveModel = env.model;
+    const shouldPresent = adapters.shouldPresentSettled ??
+        ((terminal) => isLawfulTypedTerminalOutcome(terminal.roleOutcome));
+    const sealedIdempotenceInput = {
+        admitted,
+        env,
+        io,
+        adapters,
+        shouldPresent,
+    };
+    // Sealed accepted receipt only — audit_escalation / residual failure must not
+    // short-circuit; those still need a real continuation turn.
+    // Same-ticket re-summons / court recovery forceContinuation skips the pre-lease
+    // face; post-builder reuses the same presenter when no courtAttemptId remains.
+    if (forceContinuation !== true && request !== undefined) {
+        const presented = await presentSealedAcceptedManualResumeIfAny(sealedIdempotenceInput);
+        if (presented !== undefined)
+            return presented;
+    }
+    let lease;
+    let staleWriterLeaseReclaimed;
+    try {
+        lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic, kind) => {
+            // Record the typed fact before the fallible sink: if io.stderr throws
+            // (acquire deliberately swallows diagnostic-sink failures), the reclaim
+            // still happened and must stay observable.
+            if (kind === "stale-reclaimed")
+                staleWriterLeaseReclaimed = true;
+            io.stderr(diagnostic);
+        });
+    }
+    catch (error) {
+        if (error instanceof RunWriterLeaseHeldError) {
+            io.stderr(formatCliDiagnostic(error.message));
+            // A held rejection after our own reclaim must still carry the fact that
+            // this caller reclaimed the stale lock — e.g. another resumer re-locked
+            // before our retry create (#629).
+            return {
+                exitCode: 1,
+                ...(staleWriterLeaseReclaimed === true
+                    ? { staleWriterLeaseReclaimed: true }
+                    : {}),
+            };
+        }
+        throw error;
+    }
+    // Court open/recovery under held lease until dispatch owns release (finally
+    // below). Builder, sealed presenter, and any throw on this seam must release
+    // here — dispatch's finally only runs after handoff.
+    let handedOffToDispatch = false;
+    try {
+        if (request === undefined) {
+            if (buildRequestAfterLease === undefined) {
+                throw new Error("runPostAdmissionManualResume requires request or buildRequestAfterLease");
+            }
+            request = await buildRequestAfterLease();
+            if (request.courtAttemptId === undefined ||
+                request.courtAttemptId.length === 0) {
+                const presented = await presentSealedAcceptedManualResumeIfAny(sealedIdempotenceInput);
+                if (presented !== undefined) {
+                    return {
+                        ...presented,
+                        ...(staleWriterLeaseReclaimed === true
+                            ? { staleWriterLeaseReclaimed: true }
+                            : {}),
+                    };
+                }
+            }
+        }
+        handedOffToDispatch = true;
+        const result = await dispatchPostAdmissionTurn({
+            admitted,
+            env: {
+                ...env,
+                ...(effectiveModel === undefined ? {} : { model: effectiveModel }),
+                ...(admitted.correlationId === undefined
+                    ? {}
+                    : { correlationId: admitted.correlationId }),
+            },
+            io,
+            request,
+            lease,
+            adapters,
+            ...(effectiveEngine === undefined ? {} : { effectiveEngine }),
+        });
+        if (result.terminal !== undefined) {
+            result.terminal.autoResumeCount = 0;
+        }
+        return {
+            ...result,
+            ...(staleWriterLeaseReclaimed === true
+                ? { staleWriterLeaseReclaimed: true }
+                : {}),
+        };
+    }
+    finally {
+        if (!handedOffToDispatch) {
+            await lease.release();
+        }
+    }
+}