@akagilnc/pi-workflow-roles 0.1.3565 → 0.1.3621

package/dist/public-cli/auto-resume.js

@@ -0,0 +1,414 @@
+/**
+ * Single generic auto-resume loop for #416 (owner scope = single LLM call).
+ * Call-local retries, at most the effective autoResumeLimit times (injected once
+ * per call by the caller, #422 — never re-read from disk inside the loop),
+ * in-place (same runId/session).
+ * Unifies presentation: intermediate attempts use dummyIo, only final Terminal is presented.
+ *
+ * Owner 2026-08-23: a dispatch that exits by throwing used to bypass the entire
+ * retry mechanism (the throw escaped the while-loop before the count check ever
+ * ran). Every exception is now retained whole, in place, and the ordinary retry
+ * path continues: same budget, same call-local count semantics. No failure-type
+ * classification — every thrown value is treated identically.
+ */
+import { constants as fsConstants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, open } from "node:fs/promises";
+import { join } from "node:path";
+import { AUTO_RESUME_LIMIT, describeErrorIdentity, acquireRunWriterLease, markRunTerminal, RunWriterLeaseHeldError, } from "./run-lifecycle.js";
+import { parseAutoResumeLimit } from "./config.js";
+import { isLawfulTypedTerminalOutcome, formatTerminalResult } from "./terminal.js";
+import { presentFailureTerminal, presentStructuralRejection, } from "./settlement.js";
+const dummyIo = { stdout: () => { }, stderr: () => { } };
+function presentTerminal(terminal, io) {
+    if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
+        presentFailureTerminal(terminal, io);
+    }
+    else {
+        io.stdout(formatTerminalResult(terminal));
+    }
+}
+/**
+ * Best-effort finalization of the durable run state before an exception-path
+ * synthetic failure terminal is returned (#426 review: analyst-ledger classifies
+ * running runs as live — an exhausted invocation must not remain live
+ * indefinitely). Finalization failure must not mask the real cause.
+ */
+async function finalizeExceptionRunBestEffort(runDirectory, io) {
+    try {
+        await markRunTerminal(runDirectory);
+    }
+    catch (error) {
+        io.stderr(`run terminal-state finalization failed (best-effort continue): ${describeErrorIdentity(error)}\n`);
+    }
+}
+/** Session custom-entry type carrying the pointer to one dispatch error file. */
+export const DISPATCH_ERROR_RETENTION_ENTRY_TYPE = "ak_run_dispatch_error_retention";
+/** Artifacts subdirectory of a run directory (established run-artifacts location). */
+function runArtifactsDirectory(runDirectory) {
+    return join(runDirectory, "artifacts");
+}
+/**
+ * #182-A hardened path identity, mirrored from settlement.ts's
+ * ensureAuditEvidenceDirectory: a planted symlink at the run directory or the
+ * artifacts path must not receive the dispatch error dump (O_NOFOLLOW only
+ * protects the final file name; recursive mkdir would accept a symlinked
+ * parent). Fails loudly with the true cause instead.
+ */
+async function ensureRealArtifactsDirectory(runDirectory) {
+    const runStat = await lstat(runDirectory);
+    if (runStat.isSymbolicLink() || !runStat.isDirectory()) {
+        throw new Error("dispatch error retention: run directory is not a real directory");
+    }
+    const artifactsDir = runArtifactsDirectory(runDirectory);
+    try {
+        const existing = await lstat(artifactsDir);
+        if (existing.isSymbolicLink() || !existing.isDirectory()) {
+            throw new Error("dispatch error retention: artifacts path is not a real directory");
+        }
+    }
+    catch (error) {
+        if (!isMissingPathError(error))
+            throw error;
+        await mkdir(artifactsDir, { recursive: true });
+        const created = await lstat(artifactsDir);
+        if (created.isSymbolicLink() || !created.isDirectory()) {
+            throw new Error("dispatch error retention: artifacts directory is not a real directory");
+        }
+    }
+    return artifactsDir;
+}
+/**
+ * Whole-object transfer of a thrown value (owner 2026-08-23: 「记录所有错误信息。
+ * 不能丢详细情况」). Every own property of the Error object — enumerable or not,
+ * which is how message/stack and any attached identity land verbatim — plus the
+ * constructor name and the full cause chain. No field list is prescribed or
+ * filtered: whatever the exception object carries goes into the file as-is.
+ */
+function serializeThrownValue(value, depth = 0, seen = new WeakSet()) {
+    if (value instanceof Error) {
+        if (seen.has(value))
+            return "[circular]";
+        seen.add(value);
+        const transferred = {};
+        for (const key of Object.getOwnPropertyNames(value)) {
+            transferred[key] = transferNestedValue(value[key], depth + 1, seen);
+        }
+        return {
+            errorKind: "Error",
+            constructorName: value.constructor?.name,
+            ...transferred,
+            ...(value.cause === undefined
+                ? {}
+                : {
+                    causeChain: depth >= 10
+                        ? "[cause-chain-depth-limit]"
+                        : serializeThrownValue(value.cause, depth + 1, seen),
+                }),
+        };
+    }
+    return value;
+}
+/** ENOENT identity shared with settlement.ts's hardened audit-artifact path. */
+function isMissingPathError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+/**
+ * Recursive Error-property transfer (#426 review: nested Errors must not be
+ * passed raw to JSON.stringify — their non-enumerable message/stack would
+ * serialize as {}). Depth-limited; cycle-safe via the seen set so the recursive
+ * construction itself cannot diverge before stringify runs.
+ */
+function transferNestedValue(value, depth, seen) {
+    if (value instanceof Error)
+        return serializeThrownValue(value, depth, seen);
+    if (depth >= 10)
+        return "[nested-depth-limit]";
+    if (Array.isArray(value)) {
+        return value.map((item) => transferNestedValue(item, depth + 1, seen));
+    }
+    if (value !== null && typeof value === "object") {
+        if (seen.has(value))
+            return "[circular]";
+        seen.add(value);
+        const transferred = {};
+        for (const key of Object.getOwnPropertyNames(value)) {
+            transferred[key] = transferNestedValue(value[key], depth + 1, seen);
+        }
+        return transferred;
+    }
+    return value;
+}
+/** Cycle- and bigint-safe JSON replacer so serialization itself cannot drop data. */
+function jsonSafeReplacer() {
+    const seen = new WeakSet();
+    return (_key, value) => {
+        if (typeof value === "bigint")
+            return `${value}n`;
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value))
+                return "[circular]";
+            seen.add(value);
+        }
+        return value;
+    };
+}
+/**
+ * Retain one throwing dispatch attempt's complete exception as an independent
+ * per-attempt file under the run's artifacts directory, then leave an
+ * addressable pointer in the session principal (custom entry). Exclusive-create
+ * open (O_EXCL) with a per-attempt unique name enforces 史必追加 (#419): a later
+ * attempt can never overwrite an earlier attempt's file.
+ */
+async function retainDispatchError(admitted, principalAuthority, sessionAppender, attempt, error) {
+    const artifactsDir = await ensureRealArtifactsDirectory(admitted.runDirectory);
+    const filePath = join(artifactsDir, `dispatch-error-attempt-${attempt}-${randomUUID()}.json`);
+    // Whole-object dump: everything the thrown value carries, nothing picked.
+    const payload = `${JSON.stringify({
+        version: 1,
+        attempt,
+        recordedAt: new Date().toISOString(),
+        error: serializeThrownValue(error),
+    }, jsonSafeReplacer(), 2)}\n`;
+    // O_EXCL: exclusive create — the retention history is append-only by
+    // construction; a colliding name fails loudly instead of overwriting.
+    // O_NOFOLLOW when the platform provides it keeps a planted symlink from
+    // being followed; on platforms without it, exclusivity still holds.
+    // AK artifact owner stays here; only the session JSONL pointer uses Pi codec.
+    const noFollowFlag = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const handle = await open(filePath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollowFlag, 0o600);
+    try {
+        await handle.writeFile(payload, "utf8");
+    }
+    finally {
+        await handle.close();
+    }
+    // Addressable pointer in the dossier (卷宗): Pi session custom-entry codec
+    // (appendPiSessionCustomEntry). Lease still owned here with run-writer.
+    let pointerLease;
+    try {
+        pointerLease = await acquireRunWriterLease(admitted.runDirectory);
+    }
+    catch (error) {
+        if (error instanceof RunWriterLeaseHeldError)
+            return { file: filePath };
+        throw error;
+    }
+    // Pointer-stage failure (#426 fix_now #5) is separated from the file write:
+    // once the error file is durably on disk, a failed session append must not
+    // reject through here and orphan it — the file path is still handed back.
+    let pointerError;
+    try {
+        const timestamp = new Date().toISOString();
+        await sessionAppender(principalAuthority, admitted.principal, DISPATCH_ERROR_RETENTION_ENTRY_TYPE, { version: 1, attempt, file: filePath, recordedAt: timestamp });
+    }
+    catch (error) {
+        pointerError = error;
+    }
+    finally {
+        await pointerLease.release();
+    }
+    return pointerError === undefined ? { file: filePath } : { file: filePath, pointerError };
+}
+/**
+ * Typed failure terminal for a retry path that ended with only exceptions:
+ * loud, non-lawful, carrying the last true cause and the pointers to the
+ * full per-attempt error files. Never rethrows the raw exception at callers.
+ */
+function dispatchExceptionFailureTerminal(input) {
+    // #426 review: this terminal fires whenever the FINAL dispatch throws, not
+    // only when every attempt threw — do not misrepresent a mixed retry history.
+    const history = input.everyAttemptThrew
+        ? "dispatch threw an exception on every attempt"
+        : "the final dispatch threw an exception";
+    const diagnostic = `${history} (${input.endReason}; resumes used ${input.autoResumeAttempts}); last cause: ${describeErrorIdentity(input.causeError)}`;
+    const decisiveFacts = {
+        cause: "unrecognized",
+        diagnostic,
+        resumesUsed: input.autoResumeAttempts,
+        dispatchErrorFiles: [...input.errorFiles],
+    };
+    if (input.errorFiles.length > 0) {
+        decisiveFacts.lastDispatchErrorFile = input.errorFiles[input.errorFiles.length - 1];
+    }
+    const candidate = input.causeError;
+    if (typeof candidate?.name === "string")
+        decisiveFacts.errorName = candidate.name;
+    if (typeof candidate?.code === "string" || typeof candidate?.code === "number") {
+        decisiveFacts.errorCode = candidate.code;
+    }
+    const artifacts = input.errorFiles.map((path) => ({
+        kind: "error",
+        path,
+    }));
+    return {
+        roleOutcome: {
+            kind: "failure",
+            role: input.role,
+            cause: "unrecognized",
+            diagnostic,
+            decisiveFacts,
+        },
+        navigator: { disposition: "no-advice" },
+        artifacts,
+        runId: input.runId,
+        autoResumeCount: input.autoResumeAttempts,
+    };
+}
+export async function runWithAutoResumeLoop(options) {
+    // #422 single-point resolution + domain validation. NaN would bypass every
+    // `attempts >= limit` comparison (always false) — reject here, before any dispatch.
+    const limit = options.autoResumeLimit ?? AUTO_RESUME_LIMIT;
+    parseAutoResumeLimit(limit);
+    let autoResumeAttempts = 0;
+    let isFirst = true;
+    let currentPayload = options.buildInitialPayload();
+    let dispatchOrdinal = 0;
+    let lastThrownError;
+    let everyAttemptThrew = true;
+    const retainedErrorFiles = [];
+    while (true) {
+        let lease;
+        try {
+            lease = await acquireRunWriterLease(options.admitted.runDirectory, (diagnostic) => options.io.stderr(diagnostic));
+        }
+        catch (error) {
+            if (error instanceof RunWriterLeaseHeldError) {
+                presentStructuralRejection(error, options.io);
+                return { exitCode: 2 };
+            }
+            throw error;
+        }
+        let result;
+        try {
+            result = await options.dispatch(currentPayload, lease, isFirst, dummyIo);
+        }
+        catch (error) {
+            // Owner 2026-08-23: 「出了异常，就原地记录错误信息，然后重试。」
+            // Retain the whole exception in place (per-attempt full file + dossier
+            // pointer); recording failure must not break the retry path (PR #418
+            // diagnostic-sink-isolation precedent). The dispatcher owns lease release
+            // in its own finally, so the retry round starts with the lock free.
+            lastThrownError = error;
+            const attempt = dispatchOrdinal;
+            try {
+                // Track the file as soon as it is durably written (#426 review):
+                // a pointer-stage failure comes back separately (pointerError) and must
+                // never orphan the retained file (#426 fix_now #5).
+                const { file, pointerError } = await retainDispatchError(options.admitted, options.principalAuthority, options.sessionAppender, attempt, error);
+                retainedErrorFiles.push(file);
+                options.io.stderr(`dispatch attempt ${attempt} threw (${describeErrorIdentity(error)}); full error retained at ${file}\n`);
+                if (pointerError !== undefined) {
+                    options.io.stderr(`dispatch error retention failed (best-effort continue): ${describeErrorIdentity(pointerError)}\n`);
+                }
+            }
+            catch (retentionError) {
+                options.io.stderr(`dispatch error retention failed (best-effort continue): ${describeErrorIdentity(retentionError)}\n`);
+            }
+        }
+        dispatchOrdinal += 1;
+        if (result !== undefined) {
+            everyAttemptThrew = false;
+            const terminal = result.terminal;
+            if (terminal !== undefined) {
+                terminal.autoResumeCount = autoResumeAttempts;
+            }
+            const lawful = terminal !== undefined && isLawfulTypedTerminalOutcome(terminal.roleOutcome);
+            if (lawful) {
+                if (terminal !== undefined) {
+                    // Present lawful terminal once to real io (dummy was used inside dispatch)
+                    options.io.stdout(formatTerminalResult(terminal));
+                }
+                return result;
+            }
+        }
+        // Settlement-owned sealed disposition before any redispatch (#648 / #672):
+        // shared for non-lawful return and direct throw. Only entry presentation
+        // differs (present returned terminal vs throw-path synthetic).
+        if (options.sealedAcceptanceDisposition !== undefined) {
+            const disposition = await options.sealedAcceptanceDisposition();
+            if (disposition.kind === "block") {
+                if (disposition.reason === "sealed-accepted" && result !== undefined) {
+                    const terminal = result.terminal;
+                    if (terminal !== undefined)
+                        presentTerminal(terminal, options.io);
+                    return result;
+                }
+                const terminal = dispatchExceptionFailureTerminal({
+                    role: options.admitted.role,
+                    runId: options.admitted.runId,
+                    causeError: disposition.reason === "authority-failed"
+                        ? disposition.cause
+                        : lastThrownError,
+                    errorFiles: retainedErrorFiles,
+                    autoResumeAttempts,
+                    endReason: disposition.reason === "authority-failed"
+                        ? "sealed-acceptance authority failed closed"
+                        : "sealed accepted projection already present",
+                    everyAttemptThrew,
+                });
+                await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+                presentTerminal(terminal, options.io);
+                return {
+                    exitCode: 1,
+                    terminal,
+                };
+            }
+        }
+        if (result !== undefined) {
+            const terminal = result.terminal;
+            if (autoResumeAttempts >= limit) {
+                if (terminal !== undefined)
+                    presentTerminal(terminal, options.io);
+                return result;
+            }
+            if (!(await options.principalAuthority.isAvailable(options.admitted.principal))) {
+                if (terminal !== undefined)
+                    presentTerminal(terminal, options.io);
+                return result;
+            }
+        }
+        else {
+            // Exception path: continue through the identical budget/session gates.
+            if (autoResumeAttempts >= limit) {
+                const terminal = dispatchExceptionFailureTerminal({
+                    role: options.admitted.role,
+                    runId: options.admitted.runId,
+                    causeError: lastThrownError,
+                    errorFiles: retainedErrorFiles,
+                    autoResumeAttempts,
+                    endReason: "auto-resume budget exhausted",
+                    everyAttemptThrew,
+                });
+                await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+                presentTerminal(terminal, options.io);
+                return {
+                    exitCode: 1,
+                    terminal,
+                };
+            }
+            if (!(await options.principalAuthority.isAvailable(options.admitted.principal))) {
+                const terminal = dispatchExceptionFailureTerminal({
+                    role: options.admitted.role,
+                    runId: options.admitted.runId,
+                    causeError: lastThrownError,
+                    errorFiles: retainedErrorFiles,
+                    autoResumeAttempts,
+                    endReason: "session principal unavailable before further resume",
+                    everyAttemptThrew,
+                });
+                await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+                presentTerminal(terminal, options.io);
+                return {
+                    exitCode: 1,
+                    terminal,
+                };
+            }
+        }
+        autoResumeAttempts++;
+        currentPayload = options.buildResumePayload();
+        isFirst = false;
+    }
+}

package/dist/public-cli/cli-errors.js

@@ -0,0 +1,8 @@
+/** Shared public CLI usage error (structural reject before admission). */
+export class CliUsageError extends Error {
+    code = "AK_ROLE_USAGE";
+    constructor(message, options) {
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "CliUsageError";
+    }
+}

package/dist/public-cli/cli-io.js

@@ -0,0 +1 @@
+export {};

package/dist/public-cli/command-renderer.js

@@ -0,0 +1,5 @@
+/**
+ * Public CLI re-export of the shared registry-owned command renderer.
+ * Single implementation lives in src/public-command-renderer.ts.
+ */
+export { isPublicCallableRole, renderPublicAkRoleCommand, } from "../public-command-renderer.js";

package/dist/public-cli/doctor-run.js

@@ -0,0 +1,84 @@
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.js";
+import { CliUsageError } from "./cli-errors.js";
+import { admitDoctorInvocation, buildDoctorTransportPrompt } from "./invocation.js";
+import { runPostAdmissionOneShot, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
+import { loadResumableDoctorRun, markRunAdmitted, } from "./run-lifecycle.js";
+import { presentStructuralRejection, trySettleDoctorTerminalResult, } from "./settlement.js";
+import { isLawfulTypedTerminalOutcome, } from "./terminal.js";
+import { projectRoleTurnRequest, } from "./turn-request.js";
+/** Project admitted invocation onto the host-neutral turn request. */
+export function buildDoctorTurnRequest(admitted, options) {
+    return projectRoleTurnRequest(admitted, {
+        activation: { role: "doctor", casePath: admitted.caseRunsPath },
+    }, options);
+}
+export async function runPublicDoctor(argv, env, io, parseDoctorArgv) {
+    let admitted;
+    try {
+        const parsed = parseDoctorArgv(argv);
+        admitted = await admitDoctorInvocation({
+            home: env.home,
+            principalAuthority: env.principalAuthority,
+            cwd: env.cwd,
+            issueNumber: parsed.issueNumber,
+            instruction: parsed.instruction,
+            attachmentPaths: parsed.attachmentPaths,
+            ...(parsed.project === undefined ? {} : { project: parsed.project }),
+            ...(parsed.runs === undefined ? {} : { runs: parsed.runs }),
+            ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+            ...(env.model === undefined ? {} : { model: env.model }),
+        });
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    await markRunAdmitted(admitted, env.principalAuthority);
+    const turnRequest = buildDoctorTurnRequest(admitted, {
+        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 }),
+        ...(env.correlationId === undefined || env.correlationId.trim() === ""
+            ? {}
+            : { correlationId: env.correlationId }),
+        continuation: {
+            kind: "initial",
+            prompt: buildDoctorTransportPrompt(admitted, engineSessionMaterialFromOptions({ ...(env.engine === undefined ? {} : { engine: env.engine }), packageRoot: env.packageRoot })),
+        },
+    });
+    return await runPostAdmissionOneShot({
+        admitted,
+        env,
+        io,
+        request: turnRequest,
+        adapters: doctorAdapters(),
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+    });
+}
+function doctorAdapters() {
+    return {
+        trySettle: (admitted, authority) => trySettleDoctorTerminalResult(admitted, authority),
+        shouldPresentSettled: (terminal) => isLawfulTypedTerminalOutcome(terminal.roleOutcome),
+    };
+}
+/**
+ * Resume a previously admitted Doctor run (#633). Issue + retained case
+ * identity restore from the durable admitted request; the session principal reopens.
+ */
+export async function runPublicDoctorResume(request, env, io) {
+    return await runPostAdmissionSeatResume({
+        request,
+        env,
+        io,
+        load: (effective) => loadResumableDoctorRun(env.home, effective.runId, env.principalAuthority),
+        buildTurnRequest: (admitted, effective) => buildDoctorTurnRequest(admitted, resumeTurnRequestProjectionOptions(admitted, effective, env)),
+        adapters: doctorAdapters(),
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+    });
+}

package/dist/public-cli/inspector-run.js

@@ -0,0 +1,136 @@
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.js";
+import { CliUsageError } from "./cli-errors.js";
+import { applyInstructionTicketProbe, probeInstructionTicket, ticketNumberFromProbe, tryResumeSameTicketSeatRun, } from "./seat-ticket-binding.js";
+import { admitInspectorInvocation, buildInspectorTransportPrompt, } from "./invocation.js";
+import { prepareSummonsResumeMaterials, runPostAdmissionOneShot, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
+import { loadResumableInspectorRun, markRunAdmitted, } from "./run-lifecycle.js";
+import { presentStructuralRejection, trySettleInspectorTerminalResult, } from "./settlement.js";
+import { projectRoleTurnRequest, } from "./turn-request.js";
+/** Project admitted invocation onto the host-neutral turn request. */
+export function buildInspectorTurnRequest(admitted, options) {
+    return projectRoleTurnRequest(admitted, {
+        activation: {
+            role: "inspector",
+        },
+    }, options);
+}
+export async function runPublicInspector(argv, env, io, parseInspectorArgv) {
+    let parsed;
+    try {
+        parsed = parseInspectorArgv(argv);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    // #637: same ticket → resume prior inspector run with this summons' materials.
+    // Probe captures DiaristTicketResolutionError so admit+beforeDispatch can settle
+    // controlled failure (bare pre-admit throw skips terminal settlement).
+    // No bare catch→fresh: lookup/resume failures surface; only true absence mints new.
+    const projectRoot = parsed.project ?? env.cwd;
+    const ticketProbe = await probeInstructionTicket(parsed.instruction, projectRoot, env);
+    const probedTicketNumber = ticketNumberFromProbe(ticketProbe);
+    if (probedTicketNumber !== undefined) {
+        const summons = {
+            instruction: parsed.instruction,
+            instructionEmpty: parsed.instruction.trim() === "",
+            attachmentPaths: parsed.attachmentPaths,
+        };
+        const resumed = await tryResumeSameTicketSeatRun({
+            home: env.home,
+            projectRoot,
+            role: "inspector",
+            ticketNumber: probedTicketNumber,
+            freshSummons: env.freshSummons,
+            summons,
+            resume: (runId, materials) => runPublicInspectorResume({ runId, ...(materials === undefined ? {} : { summons: materials }) }, env, io),
+        });
+        if (resumed !== undefined)
+            return resumed;
+    }
+    let admitted;
+    try {
+        admitted = await admitInspectorInvocation({
+            home: env.home,
+            principalAuthority: env.principalAuthority,
+            cwd: env.cwd,
+            instruction: parsed.instruction,
+            attachmentPaths: parsed.attachmentPaths,
+            ...(parsed.project === undefined ? {} : { project: parsed.project }),
+            ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+            ...(env.model === undefined ? {} : { model: env.model }),
+            ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
+        });
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    await markRunAdmitted(admitted, env.principalAuthority);
+    const engineMaterial = engineSessionMaterialFromOptions({
+        ...(env.engine === undefined ? {} : { engine: env.engine }),
+        packageRoot: env.packageRoot,
+    });
+    const turnRequest = buildInspectorTurnRequest(admitted, {
+        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 }),
+        ...(env.correlationId === undefined || env.correlationId.trim() === ""
+            ? {}
+            : { correlationId: env.correlationId }),
+        continuation: {
+            kind: "initial",
+            prompt: buildInspectorTransportPrompt(admitted, engineMaterial),
+        },
+    });
+    return await runPostAdmissionOneShot({
+        admitted,
+        env,
+        io,
+        request: turnRequest,
+        adapters: inspectorAdapters({
+            beforeDispatch: async (admittedSeat) => {
+                // #635/#637: apply pre-admit probe inside controlled-failure boundary.
+                await applyInstructionTicketProbe(admittedSeat, ticketProbe);
+            },
+        }),
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+    });
+}
+function inspectorAdapters(options) {
+    return {
+        trySettle: (admitted, authority, scope) => trySettleInspectorTerminalResult(admitted, authority, scope),
+        shouldPresentSettled: () => true,
+        ...(options?.beforeDispatch === undefined
+            ? {}
+            : { beforeDispatch: options.beforeDispatch }),
+    };
+}
+/**
+ * Resume a previously admitted Inspector run (#633 / #637); the session principal reopens.
+ * Same-ticket summons deliver this turn's instruction + frozen attachments; manual
+ * resume keeps package-envelope / caller-message semantics and birth attachments.
+ */
+export async function runPublicInspectorResume(request, env, io) {
+    return await runPostAdmissionSeatResume({
+        request,
+        env,
+        io,
+        load: (effective) => loadResumableInspectorRun(env.home, effective.runId, env.principalAuthority),
+        buildTurnRequest: async (admitted, effective) => {
+            const summonsPrepared = await prepareSummonsResumeMaterials(admitted.runDirectory, effective.summons);
+            return buildInspectorTurnRequest(admitted, resumeTurnRequestProjectionOptions(admitted, effective, env, summonsPrepared));
+        },
+        adapters: inspectorAdapters(),
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+    });
+}