@sema-agent/core 7.16.0 → 7.17.1

package/dist/orchestration/workflow.js

@@ -3,6 +3,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import { availableParallelism } from "node:os";
 import { uuidv7 } from "../internal/harness.js";
+import { applyParentSpecSeat } from "../core/parent-spec-seat.js";
 import { TERMINAL_CAUSE_IS_REPLAYABLE, isTerminalCauseKind } from "../core/terminal-cause.js";
 import { terminalProjection } from "../core/runner/terminal-projection.js";
 import { builtinAgentDefinitions } from "../agents/builtin-agents.js";
@@ -219,14 +220,24 @@ export class WorkflowJournalIncompatibleError extends Error {
     fromRunId;
     ordinal;
     code = "workflow.journal_incompatible";
-    constructor(fromRunId, ordinal, reason) {
-        super(`startWorkflow: resume from "${fromRunId}" was REFUSED — ${reason ?? `journal entry #${ordinal} carries no terminal cause (a journal written before TaskResult.terminal, or a malformed entry)`}. ` +
+    constructor(fromRunId, ordinal) {
+        super(`startWorkflow: resume from "${fromRunId}" was REFUSED — journal entry #${ordinal} carries no terminal cause (a journal written before TaskResult.terminal, or a malformed entry). ` +
             "Completed work must not run again; start a fresh run instead of resuming this journal.");
         this.fromRunId = fromRunId;
         this.ordinal = ordinal;
         this.name = "WorkflowJournalIncompatibleError";
     }
 }
+class WorkflowParkRefusal extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = "WorkflowParkRefusal";
+    }
+}
 const workflowDepthStore = new AsyncLocalStorage();
 function currentWorkflowDepth() {
     return workflowDepthStore.getStore()?.depth ?? 0;
@@ -449,6 +460,9 @@ export const workflowResumeClaimFallback = {
             table.delete(key);
     },
 };
+function parkLaneArmed(opts) {
+    return opts.store !== undefined && opts.checkpointStore !== undefined;
+}
 export function startWorkflow(runner, fn, opts = {}, internals) {
     const alsDepth = currentWorkflowDepth();
     const internalDepth = internals?.workflowDepth;
@@ -461,8 +475,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     if (opts.resumeFromRunId !== undefined && opts.journalStore === undefined) {
         throw new Error("runWorkflow: resumeFromRunId requires a journalStore to load the prior run's journal");
     }
-    if (opts.defaultDurableApproval !== undefined && opts.store === undefined) {
-        throw new Error("runWorkflow: defaultDurableApproval requires a WorkflowRunStore — a workflow child's park is recorded on its wa* row, and without a store there is no durable row for a host to route the parked approval by");
+    if (opts.checkpointStore !== undefined && !parkLaneArmed(opts)) {
+        throw new WorkflowParkRefusal("workflow.park_requires_run_store", "runWorkflow: checkpointStore (the store this run's children park in) requires a WorkflowRunStore — a workflow child's park is recorded on its wa* row and proven against the checkpoint store at the next resume, and without a run store there is no durable row for a host to route the parked approval by", {});
+    }
+    if (opts.defaultDurableApproval !== undefined && !parkLaneArmed(opts)) {
+        throw new WorkflowParkRefusal("workflow.park_requires_run_store", "runWorkflow: defaultDurableApproval requires a WorkflowRunStore and a checkpointStore — a workflow child's park is recorded on its wa* row and read back from the checkpoint store at the next resume; without both there is no durable row for a host to route the parked approval by, or no way for a resume to prove the park", {});
     }
     if (opts.parkedResume !== undefined && opts.resumeFromRunId === undefined) {
         throw new Error("runWorkflow: parkedResume drives a PARKED ordinal of a prior run and requires resumeFromRunId");
@@ -507,22 +524,23 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     let persistTail = Promise.resolve();
     const persist = (mode) => {
         if (!store)
-            return persistTail;
+            return Promise.resolve({ ok: true });
         const snapshot = structuredClone(run);
         const next = persistTail.then(async () => {
             try {
                 if (mode === "create") {
                     snapshot.rev = storeRev;
                     await store.put(runId, snapshot);
+                    return { ok: true };
                 }
-                else {
-                    snapshot.rev = storeRev;
-                    const won = await store.update(runId, scope, snapshot, { rev: storeRev });
-                    if (won)
-                        storeRev += 1;
-                }
+                snapshot.rev = storeRev;
+                const won = await store.update(runId, scope, snapshot, { rev: storeRev });
+                if (won)
+                    storeRev += 1;
+                return won ? { ok: true } : { ok: false, cause: "cas_lost" };
             }
             catch {
+                return { ok: false, cause: "threw" };
             }
         });
         persistTail = next;
@@ -546,6 +564,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             startedAt: 0,
         })),
         agents: [],
+        ...(opts.resumeFromRunId === undefined ? { parks: [] } : {}),
         groups: [],
         stats: { tokens: 0, turns: 0, costMicroUsd: 0, nested: { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0 } },
         startedAt: t0,
@@ -642,6 +661,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const sem = createSemaphore(concurrency);
     const spawnAttribution = {
         isDelegatedChild: true,
+        ...(opts.questionFaceStripped === true ? { questionFaceStripped: true } : {}),
         ...(opts.interactionPosture !== undefined ? { parentInteractionPosture: opts.interactionPosture } : {}),
         ...(opts.parentToolCallId !== undefined ? { parentToolCallId: opts.parentToolCallId } : {}),
         ...(opts.parentTaskId !== undefined ? { parentTaskId: opts.parentTaskId } : {}),
@@ -819,25 +839,92 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             });
         }
     };
-    const writtenOrdinals = new Set();
-    const carryUnresolvedParks = async () => {
-        if (opts.resumeFromRunId === undefined || !journalStore)
-            return;
-        for (const e of replayByOrdinal) {
-            if (e?.parked === undefined)
-                continue;
-            const ord = callKeyOrdinal(e.callKey);
-            if (writtenOrdinals.has(ord))
-                continue;
-            if (workflowSignal.aborted) {
-                emitLogLine(`resume-journal: the prior run's PARKED leg at ordinal ${ord} was NOT carried into this run's journal (the run was cancelled or timed out first) — resume from the prior run, not from this one.`);
-                continue;
+    const parkSeat = opts.checkpointStore;
+    const parkedByOrdinal = [];
+    const errText = (err) => (err instanceof Error ? err.message : String(err));
+    const withoutToken = (text, token) => (token === "" ? text : text.split(token).join("<token>"));
+    const parkBindingBroken = (ordinal, why) => new WorkflowParkRefusal("workflow.park_binding_broken", `workflow resume: ordinal ${ordinal}'s park cannot be bound to its checkpoint (${why}) — the recorded park is inconsistent. Decide the checkpoint through the deployment's approval channel and start a fresh run.`, { ordinal });
+    const readParkTruth = async (seat, key, ordinal) => {
+        if (key.token === "" || key.sessionId === "")
+            throw parkBindingBroken(ordinal, "the record names no token or no session for it");
+        const read = await finalizeWithin(timers, new Promise((resolve) => resolve(seat.get(key.token))).then((cp) => ({ cp }), (err) => ({ err })), "timeout");
+        if (read === "timeout" || "err" in read) {
+            throw new WorkflowParkRefusal("workflow.park_truth_unreadable", `workflow resume: ordinal ${ordinal} is recorded as PARKED and its checkpoint could not be read from the checkpoint store (${read === "timeout" ? `the read did not settle within ${WORKFLOW_RESUME_CLAIM_FINALIZE_TIMEOUT_MS}ms` : withoutToken(errText(read.err), key.token)}); the resume is refused rather than run beside a pinned child.`, { reason: "checkpoint_store_threw" });
+        }
+        const cp = read.cp;
+        if (cp === null)
+            return { kind: "not_pending", key, status: "absent" };
+        if (cp.token !== key.token)
+            throw parkBindingBroken(ordinal, "the checkpoint store answered a row under another token");
+        if (cp.sessionId !== key.sessionId)
+            throw parkBindingBroken(ordinal, "the checkpoint belongs to another session than the parked row");
+        if (cp.status !== "pending")
+            return { kind: "not_pending", key, status: cp.status, ...(cp.checkpointId !== undefined ? { checkpointId: cp.checkpointId } : {}) };
+        return { kind: "pending", key, cp };
+    };
+    const parkMaterialOf = async (key, ordinal) => {
+        let entry;
+        if (key.originRunId === opts.resumeFromRunId)
+            entry = replayByOrdinal[ordinal];
+        else if (journalStore) {
+            const loaded = await finalizeWithin(timers, new Promise((resolve) => resolve(journalStore.load(key.originRunId, scope))).then((entries) => ({ entries }), (err) => ({ err })), "timeout");
+            if (loaded === "timeout" || "err" in loaded) {
+                emitRunLog(`resume: the journal of run "${clampRunIdText(key.originRunId)}" (the origin of the park at ordinal ${ordinal}) could not be read (${loaded === "timeout" ? `the load did not settle within ${WORKFLOW_RESUME_CLAIM_FINALIZE_TIMEOUT_MS}ms` : withoutToken(errText(loaded.err), key.token)}).`);
+            }
+            else {
+                entry = loaded.entries.filter((e) => e.parked !== undefined && callKeyOrdinal(e.callKey) === ordinal).at(-1);
             }
-            const outcome = await finalizeWithin(timers, journalAppendParked(e.callKey, e.parked).then(() => "ok", (err) => ({ err })), "timeout");
-            if (outcome !== "ok") {
-                const why = outcome === "timeout" ? `the append did not settle within ${WORKFLOW_RESUME_CLAIM_FINALIZE_TIMEOUT_MS}ms` : outcome.err instanceof Error ? outcome.err.message : String(outcome.err);
-                emitLogLine(`resume-journal: the prior run's PARKED leg at ordinal ${ord} could not be carried into this run's journal (${why}) — resume from the prior run, not from this one.`);
+        }
+        const p = entry?.parked;
+        if (p === undefined || entry === undefined || p.terminal.token !== key.token || p.sessionId !== key.sessionId || entry.callKey !== key.callKey)
+            return undefined;
+        return p;
+    };
+    const degradedParkMaterial = (cp) => ({
+        taskId: cp.sourceTaskId ?? "",
+        sessionId: cp.sessionId,
+        result: "",
+        stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
+        terminal: { kind: "paused", gate: cp.gate, token: cp.token, ...(cp.checkpointId !== undefined ? { checkpointId: cp.checkpointId } : {}) },
+    });
+    const disposeParkedOrdinal = (truth, ordinal, callKey) => {
+        if (truth.key.callKey !== callKey)
+            throw parkedCallChangedError(ordinal);
+        const entry = parkedResumeFor(truth.key.token);
+        if (truth.kind === "not_pending") {
+            if (entry === undefined) {
+                throw new WorkflowParkRefusal("workflow.park_not_pending", `workflow resume: ordinal ${ordinal} is recorded as PARKED, but the checkpoint store says its approval checkpoint is ${truth.status}${truth.checkpointId !== undefined ? ` (checkpoint ${truth.checkpointId})` : ""} — decided, expired or reaped outside this workflow. Hand the resume a parkedResume entry for this ordinal's token to settle the ordinal as failed and continue the script, or start a fresh run.`, { ...(truth.checkpointId !== undefined ? { checkpointId: truth.checkpointId } : {}), ordinal, status: truth.status === "absent" ? "absent" : truth.status === "expired" ? "expired" : "resolved" });
             }
+            const result = {
+                taskId: callKey,
+                sessionId: truth.key.sessionId,
+                terminal: {
+                    kind: "failed",
+                    code: "workflow.park_not_pending",
+                    message: `the approval checkpoint this call was parked on is ${truth.status}${truth.checkpointId !== undefined ? ` (checkpoint ${truth.checkpointId})` : ""} — decided, expired or reaped outside this workflow; settled as failed on the resume's acknowledgement. The call did not run.`,
+                },
+                result: "",
+                stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
+            };
+            return { kind: "settle", result };
+        }
+        const paused = truth.material ?? degradedParkMaterial(truth.cp);
+        if (truth.material === undefined)
+            emitRunLog(`resume: ordinal ${ordinal} re-parks from its checkpoint row alone — the origin run's journal entry for the park was not readable or did not match the recorded park (empty result, zero stats).`);
+        if (entry?.outcome !== undefined) {
+            return { kind: "drive", drive: { token: entry.token, outcome: entry.outcome, ...(entry.inheritedGate !== undefined ? { inheritedGate: entry.inheritedGate } : {}), sessionId: paused.sessionId || undefined, paused } };
+        }
+        return { kind: "repark", paused };
+    };
+    const assertChildParkSeat = (s) => {
+        const seat = s.checkpointStore;
+        if (seat === undefined || seat === "disabled")
+            return;
+        if (!parkLaneArmed(opts)) {
+            throw new WorkflowParkRefusal("workflow.park_requires_run_store", "workflow agent: the child's checkpointStore would let it park where this workflow cannot read the park back — a workflow whose children can park needs a WorkflowRunStore and that checkpoint store as its read seat (RunWorkflowOptions.store + checkpointStore); wire both, or leave the child's seat unset.", {});
+        }
+        if (seat !== parkSeat) {
+            throw Object.assign(new Error("agent.checkpointStore is not the store this run's children park in (the workflow's resolved checkpoint seat, RunWorkflowOptions.checkpointStore) — wire the one store, or leave the field unset and let the seat ride."), { code: "config.invalid_checkpoint_store" });
         }
     };
     const driveNeverStarted = (r) => r.terminal.kind === "failed" && (r.terminal.code === "resume.reopened_unstarted" || r.terminal.code === "resume.reopen_failed_unstarted");
@@ -895,10 +982,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if (dbg)
                     console.error(`[sema:wf-journal] runId=${runId} callKey=${callKey} TOMBSTONE-ERROR ${err instanceof Error ? err.message : String(err)}`);
             }
-            writtenOrdinals.add(callKeyOrdinal(callKey));
             return;
         }
-        writtenOrdinals.add(callKeyOrdinal(callKey));
         const p = journalStore.append(runId, scope, { callKey, result: stored });
         journalTail = journalTail.then(() => p).catch(() => undefined);
         try {
@@ -915,24 +1000,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const journalAppendParked = async (callKey, paused) => {
         if (!journalStore)
             return;
-        writtenOrdinals.add(callKeyOrdinal(callKey));
-        let lastErr;
-        for (let attempt = 0; attempt < 3; attempt++) {
-            const p = journalStore.append(runId, scope, { callKey, parked: paused });
-            journalTail = journalTail.then(() => p).catch(() => undefined);
-            try {
-                await p;
-                return;
-            }
-            catch (err) {
-                lastErr = err;
-                if (err?.code === JOURNAL_OVERSIZE_ERROR_CODE)
-                    break;
-                if (attempt < 2)
-                    await new Promise((r) => timers.setTimeout(r, 25 * (attempt + 1)));
-            }
-        }
-        throw lastErr;
+        const p = journalStore.append(runId, scope, { callKey, parked: paused });
+        journalTail = journalTail.then(() => p).catch(() => undefined);
+        await p;
     };
     const parkAgentLeg = async (rec, paused, activityTail, chargeLive) => {
         const s = paused.stats;
@@ -951,19 +1021,50 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             rec.activity = activityTail.slice();
         foldLegApprovalReport(rec, paused);
         emit({ type: "agent_end", runId, label: rec.label, phase: rec.phase, ...(rec.groupId !== undefined ? { groupId: rec.groupId } : {}), status: "parked", ...(paused.model !== undefined ? { modelResolved: paused.model } : {}), ts: rec.endedAt });
-        void persist("update");
         bceLive.delete(waIdOf(rec.callKey));
         if (parkedLeg === undefined)
             parkedLeg = { label: rec.label, callKey: rec.callKey, paused };
+        const ordinal = callKeyOrdinal(rec.callKey);
+        const parks = run.parks ?? (run.parks = []);
+        const at = parks.findIndex((e) => e.callKey === rec.callKey);
+        const key = { callKey: rec.callKey, sessionId: paused.sessionId, token: paused.terminal.token, originRunId: at === -1 ? runId : parks[at].originRunId };
+        if (at === -1)
+            parks.push(key);
+        else
+            parks[at] = key;
+        void persist("update");
         try {
             await journalAppendParked(rec.callKey, paused);
+            key.originRunId = runId;
         }
         catch (err) {
-            emitRunLog(`resume-journal: the PARKED leg at ordinal ${callKeyOrdinal(rec.callKey)} ("${rec.label.slice(0, 80)}") could not be recorded (${err instanceof Error ? err.message : String(err)}) — ` +
-                "a resume of this run will NOT find the park at its ordinal; decide the checkpoint through the deployment's approval channel and start a fresh run instead of resuming this one.");
+            emitRunLog(`resume-journal: the PARKED leg at ordinal ${ordinal} ("${rec.label.slice(0, 80)}") could not be recorded in this run's journal (${withoutToken(errText(err), key.token)}) — ` +
+                "the park stands: a resume of this run finds it through the run record and the checkpoint store.");
+        }
+        const persisted = await finalizeWithin(timers, persist("update"), { ok: false, cause: "timeout" });
+        if (!persisted.ok) {
+            emitRunLog(`resume-journal: the PARKED leg at ordinal ${ordinal} ("${rec.label.slice(0, 80)}") could not be persisted on the run record (${persisted.cause}) — ` +
+                "the park stands: a resume of this run finds it through the journal and the checkpoint store.");
         }
         throw parkedError();
     };
+    const recordParkDisposition = async (d, call, agentOpts) => {
+        const { label, callKey, groupId, phase, phaseInstance, prompt } = call;
+        const at = now();
+        const model = d.kind === "repark" ? d.paused.model : undefined;
+        const rec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(model !== undefined ? { model } : {}), ...(d.kind === "repark" ? { replayed: true } : {}), status: "running", queuedAt: at, startedAt: at };
+        if (d.kind === "repark" && run.resume)
+            run.resume.replayed += 1;
+        run.agents.push(rec);
+        if (phaseInstance)
+            agentPhaseOf.set(rec, phaseInstance);
+        emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(model !== undefined ? { model } : {}), ...(d.kind === "repark" ? { replayed: true } : {}), ts: at });
+        bceSpawn(callKey, label, agentOpts.agentType, d.kind === "repark", (d.kind === "repark" ? d.paused.sessionId : d.result.sessionId) || undefined, model);
+        if (d.kind === "repark")
+            return await parkAgentLeg(rec, d.paused, [], false);
+        await settleAgentResult(rec, d.result, [], agentOpts, "awaited");
+        return d.result;
+    };
     const createActivityCapture = (callKey, label, groupId, rec) => {
         const tail = [];
         let beatCount = 0;
@@ -1168,10 +1269,12 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
         }
         const inheritedThinkingSnap = spec.thinking === undefined ? opts.defaultThinking?.() : undefined;
+        const inheritedPrincipal = spec.principal === undefined ? opts.parentSpecSeat?.principal : undefined;
         const specForIdentity = {
             ...spec,
             ...(inheritedModelSnap !== undefined ? { model: inheritedModelSnap } : {}),
             ...(inheritedThinkingSnap !== undefined ? { thinking: inheritedThinkingSnap } : {}),
+            ...(inheritedPrincipal !== undefined ? { principal: inheritedPrincipal } : {}),
         };
         const callKey = workflowAgentCallKey(run.agents.length, specForIdentity, agentOpts);
         const prompt = boundedRedactedSummary(spec.systemPrompt ? `${spec.systemPrompt}\n\n${spec.objective}` : spec.objective, MAX_TRANSCRIPT_CHARS);
@@ -1327,27 +1430,12 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             const { label, phase, phaseInstance, groupId, inheritedModelSnap, inheritedModelError, inheritedThinkingSnap, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
             let drive;
             const cached = opts.resumeFromRunId !== undefined ? replayByOrdinal[run.agents.length] : undefined;
-            if (cached?.parked !== undefined) {
-                if (cached.callKey !== callKey)
-                    throw parkedCallChangedError(run.agents.length);
-                {
-                    const decision = parkedResumeFor(cached.parked.terminal.token);
-                    if (decision === undefined) {
-                        if (finalized)
-                            return cached.parked;
-                        const at = now();
-                        const reparkRec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(cached.parked.model !== undefined ? { model: cached.parked.model } : {}), replayed: true, status: "running", queuedAt: at, startedAt: at };
-                        if (run.resume)
-                            run.resume.replayed += 1;
-                        run.agents.push(reparkRec);
-                        if (phaseInstance)
-                            agentPhaseOf.set(reparkRec, phaseInstance);
-                        emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(cached.parked.model !== undefined ? { model: cached.parked.model } : {}), replayed: true, ts: at });
-                        bceSpawn(callKey, label, agentOpts.agentType, true, cached.parked.sessionId || undefined, cached.parked.model);
-                        return await parkAgentLeg(reparkRec, cached.parked, [], false);
-                    }
-                    drive = { token: decision.token, outcome: decision.outcome, ...(decision.inheritedGate !== undefined ? { inheritedGate: decision.inheritedGate } : {}), sessionId: cached.parked.sessionId || undefined, paused: cached.parked };
-                }
+            const truth = opts.resumeFromRunId !== undefined ? parkedByOrdinal[run.agents.length] : undefined;
+            if (truth !== undefined) {
+                const d = disposeParkedOrdinal(truth, run.agents.length, callKey);
+                if (d.kind !== "drive")
+                    return await recordParkDisposition(d, { label, callKey, groupId, phase, phaseInstance, prompt }, agentOpts);
+                drive = d.drive;
             }
             if (parkedLeg !== undefined && drive === undefined)
                 throw parkedError();
@@ -1442,12 +1530,13 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     throw inheritedModelError;
                 const typedSpec0 = applyWorkflowAgentType(spec, agentOpts.agentType, agentRegistry);
                 const typedSpec = withWorkflowChildSeats(typedSpec0, inheritedModelSnap, inheritedThinkingSnap, runnerRoleMap(runner));
-                const framedSpec = withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema);
-                const authInherit = framedSpec.getApiKeyAndHeaders === undefined && opts.defaultGetApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.defaultGetApiKeyAndHeaders } : {};
-                const parkInherit = durableApprovalInherit(framedSpec);
+                const seatedSpec = applyParentSpecSeat(withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema), opts.parentSpecSeat);
+                const authInherit = seatedSpec.getApiKeyAndHeaders === undefined && opts.defaultGetApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.defaultGetApiKeyAndHeaders } : {};
+                assertChildParkSeat(seatedSpec);
+                const parkInherit = durableApprovalInherit(seatedSpec);
                 const preReviewSpec = agentOpts.schema
-                    ? { ...framedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
-                    : { ...framedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal };
+                    ? { ...seatedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
+                    : { ...seatedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal };
                 const runSpec = await reviewSpawnBeforeLaunch("ctx.agent", label, callKey, preReviewSpec, effectiveSignal);
                 const enrichedForward = opts.onForwardEvent !== undefined
                     ? (e) => {
@@ -1645,7 +1734,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
             catch (err) {
                 if (drive !== undefined && !finalized && !(err instanceof WorkflowAgentParkedError)) {
-                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${err instanceof Error ? err.message : String(err)}); the park stands.`);
+                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${withoutToken(errText(err), drive.token)}); the park stands.`);
                     return await parkAgentLeg(rec, drive.paused, activityTail, false);
                 }
                 if (!finalized) {
@@ -1723,24 +1812,14 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
             const { label, phase, phaseInstance, groupId, inheritedModelSnap, inheritedModelError, inheritedThinkingSnap, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
             let drive;
-            const parkedHere = opts.resumeFromRunId !== undefined ? replayByOrdinal[run.agents.length] : undefined;
-            if (parkedHere?.parked !== undefined) {
-                if (parkedHere.callKey !== callKey)
-                    throw parkedCallChangedError(run.agents.length);
-                const decision = parkedResumeFor(parkedHere.parked.terminal.token);
-                if (decision === undefined) {
-                    const at = now();
-                    const reparkRec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(parkedHere.parked.model !== undefined ? { model: parkedHere.parked.model } : {}), replayed: true, status: "running", queuedAt: at, startedAt: at };
-                    if (run.resume)
-                        run.resume.replayed += 1;
-                    run.agents.push(reparkRec);
-                    if (phaseInstance)
-                        agentPhaseOf.set(reparkRec, phaseInstance);
-                    emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(parkedHere.parked.model !== undefined ? { model: parkedHere.parked.model } : {}), replayed: true, ts: at });
-                    bceSpawn(callKey, label, agentOpts.agentType, true, parkedHere.parked.sessionId || undefined, parkedHere.parked.model);
-                    return await parkAgentLeg(reparkRec, parkedHere.parked, [], false);
+            const truth = opts.resumeFromRunId !== undefined ? parkedByOrdinal[run.agents.length] : undefined;
+            if (truth !== undefined) {
+                const d = disposeParkedOrdinal(truth, run.agents.length, callKey);
+                if (d.kind !== "drive") {
+                    const settled = await recordParkDisposition(d, { label, callKey, groupId, phase, phaseInstance, prompt }, agentOpts);
+                    return { runId, label, callKey, steer: async () => Promise.reject(new Error(`workflow agent "${label}" settled at its parked ordinal — nothing to steer`)), result: async () => settled };
                 }
-                drive = { token: decision.token, outcome: decision.outcome, ...(decision.inheritedGate !== undefined ? { inheritedGate: decision.inheritedGate } : {}), sessionId: parkedHere.parked.sessionId || undefined, paused: parkedHere.parked };
+                drive = d.drive;
             }
             if (drive === undefined) {
                 noteDivergence(run.agents.length, "ctx.agentStream results are never replayed");
@@ -1817,12 +1896,13 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     throw inheritedModelError;
                 const typedSpec0 = applyWorkflowAgentType(spec, agentOpts.agentType, agentRegistry);
                 const typedSpec = withWorkflowChildSeats(typedSpec0, inheritedModelSnap, inheritedThinkingSnap, runnerRoleMap(runner));
-                const framedSpec = withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema);
-                const authInherit = framedSpec.getApiKeyAndHeaders === undefined && opts.defaultGetApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.defaultGetApiKeyAndHeaders } : {};
-                const parkInherit = durableApprovalInherit(framedSpec);
+                const seatedSpec = applyParentSpecSeat(withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema), opts.parentSpecSeat);
+                const authInherit = seatedSpec.getApiKeyAndHeaders === undefined && opts.defaultGetApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.defaultGetApiKeyAndHeaders } : {};
+                assertChildParkSeat(seatedSpec);
+                const parkInherit = durableApprovalInherit(seatedSpec);
                 const baseRunSpec = agentOpts.schema
-                    ? { ...framedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
-                    : { ...framedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal };
+                    ? { ...seatedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
+                    : { ...seatedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal };
                 const preReviewSpec = childSessionId !== undefined ? { ...baseRunSpec, sessionId: childSessionId } : baseRunSpec;
                 const runSpec = await reviewSpawnBeforeLaunch("ctx.agentStream", label, callKey, preReviewSpec, effectiveSignal);
                 const enrichedForwardS = opts.onForwardEvent !== undefined
@@ -1864,7 +1944,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
             catch (err) {
                 if (drive !== undefined && !finalized) {
-                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${err instanceof Error ? err.message : String(err)}); the park stands.`);
+                    emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${withoutToken(errText(err), drive.token)}); the park stands.`);
                     releaseLeg();
                     return await parkAgentLeg(rec, drive.paused, [], false);
                 }
@@ -2116,23 +2196,69 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         }
                         replayByOrdinal[callKeyOrdinal(e.callKey)] = e;
                     }
+                    const fromRunId = clampRunIdText(opts.resumeFromRunId);
+                    let prior = null;
                     if (opts.store !== undefined) {
-                        let prior;
                         try {
                             prior = await opts.store.get(opts.resumeFromRunId);
                         }
                         catch (err) {
-                            throw new WorkflowJournalIncompatibleError(clampRunIdText(opts.resumeFromRunId), -1, `the prior run's record could not be read from the run store (${err instanceof Error ? err.message : String(err)}), so a lost park cannot be ruled out`);
+                            const errCode = err instanceof Error ? err.code : undefined;
+                            const errClass = err instanceof Error ? `${err.name}${typeof errCode === "string" ? `/${errCode}` : ""}` : typeof err;
+                            throw new WorkflowParkRefusal("workflow.park_truth_unreadable", `startWorkflow: resume from "${fromRunId}" was REFUSED — the prior run's record could not be read from the run store (${errClass}), so its parks cannot be proven.`, { reason: "store_threw" });
                         }
-                        if (prior !== null && prior.scope === scope) {
-                            for (const row of prior.agents) {
-                                if (row.status !== "parked")
-                                    continue;
-                                const ord = callKeyOrdinal(row.callKey);
-                                if (replayByOrdinal[ord]?.parked === undefined) {
-                                    throw new WorkflowJournalIncompatibleError(clampRunIdText(opts.resumeFromRunId), ord, `the prior run's agent #${ord} ("${row.label.slice(0, 80)}") is PARKED on an approval checkpoint but its journal entry is missing (the park was not recorded) — a resume would run that call live beside the pinned child`);
-                                }
+                        if (prior !== null && prior.scope !== scope)
+                            prior = null;
+                    }
+                    if (opts.store !== undefined && prior === null)
+                        throw new WorkflowParkRefusal("workflow.park_truth_unreadable", `startWorkflow: resume from "${fromRunId}" was REFUSED — the prior run's record is not in the run store under this scope, so its parks cannot be proven.`, { reason: "record_missing" });
+                    if (parkSeat !== undefined && prior !== null && prior.status === "running")
+                        throw new WorkflowParkRefusal("workflow.park_truth_unreadable", `startWorkflow: resume from "${fromRunId}" was REFUSED — the prior run is still recorded as running; a run that could park must have finished before it is resumed (a crashed park-capable run is decided through the deployment's approval channel, not resumed).`, { reason: "record_not_terminal" });
+                    if (prior !== null && !Array.isArray(prior.parks))
+                        throw new WorkflowParkRefusal("workflow.park_truth_unreadable", `startWorkflow: resume from "${fromRunId}" was REFUSED — the prior run's record carries no parks list (written by an older engine, or stripped by the store's projection), so its parks cannot be proven.`, { reason: "parks_unreadable" });
+                    const candidates = new Map();
+                    const recordParks = prior !== null && Array.isArray(prior.parks) ? prior.parks : [];
+                    for (const raw of recordParks) {
+                        const e = raw;
+                        if (e === null || typeof e !== "object" || typeof e.callKey !== "string" || typeof e.sessionId !== "string" || typeof e.token !== "string" || typeof e.originRunId !== "string" || !/^\d+:/.test(e.callKey)) {
+                            throw parkBindingBroken(-1, "a recorded park entry is malformed or its call key has no ordinal");
+                        }
+                        candidates.set(callKeyOrdinal(e.callKey), { callKey: e.callKey, sessionId: e.sessionId, token: e.token, originRunId: e.originRunId });
+                    }
+                    for (const [ord, e] of replayByOrdinal.entries()) {
+                        if (e?.parked === undefined)
+                            continue;
+                        const fromJournal = { callKey: e.callKey, sessionId: e.parked.sessionId, token: e.parked.terminal.token, originRunId: opts.resumeFromRunId };
+                        const recorded = candidates.get(ord);
+                        if (recorded === undefined)
+                            candidates.set(ord, fromJournal);
+                        else if (recorded.token !== fromJournal.token || recorded.sessionId !== fromJournal.sessionId || recorded.callKey !== fromJournal.callKey)
+                            throw parkBindingBroken(ord, "the run record and the journal name different tokens, sessions or calls for it");
+                    }
+                    const inherited = [];
+                    for (const [ord, key] of [...candidates.entries()].sort((a, b) => a[0] - b[0])) {
+                        if (replayByOrdinal[ord]?.result !== undefined)
+                            continue;
+                        inherited.push(key);
+                    }
+                    run.parks = inherited;
+                    if (parkSeat === undefined) {
+                        if (inherited.length > 0) {
+                            throw new WorkflowParkRefusal("workflow.park_truth_unreadable", `startWorkflow: resume from "${fromRunId}" was REFUSED — it is responsible for ${inherited.length} recorded park(s) and this workflow holds no checkpoint store to prove them against (RunWorkflowOptions.checkpointStore); without the seat a parked call would run live beside its pinned child.`, { reason: "capability_not_armed" });
+                        }
+                    }
+                    else {
+                        for (const key of inherited) {
+                            const ord = callKeyOrdinal(key.callKey);
+                            let truth = await readParkTruth(parkSeat, key, ord);
+                            if (truth.kind === "not_pending" && parkedResumeFor(key.token) !== undefined)
+                                truth = await readParkTruth(parkSeat, key, ord);
+                            if (truth.kind === "pending") {
+                                const material = await parkMaterialOf(key, ord);
+                                if (material !== undefined)
+                                    truth = { ...truth, material };
                             }
+                            parkedByOrdinal[ord] = truth;
                         }
                     }
                     run.resume = {
@@ -2179,7 +2305,6 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 await awaitLegsIdle(workflowSignal);
                 throw parkedError();
             }
-            await carryUnresolvedParks();
             if (maxResultChars !== undefined) {
                 let size = 0;
                 try {
@@ -2214,7 +2339,6 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         catch (err) {
             if (parkedLeg !== undefined)
                 await awaitLegsIdle(workflowSignal);
-            await carryUnresolvedParks();
             finalized = true;
             const unsettledOnFailure = settleActiveUsageBeats();
             stampBudgetOvershoot(unsettledOnFailure);

package/dist/prompt-assembly/assemble.d.ts

@@ -37,8 +37,8 @@ export interface AssembledPrompt {
     renderWithDate?: (date: string) => string;
     /** The initially-rendered system prompt. */
     systemPrompt: string;
-    /** v1 `prompt.assembled` block view (id wordlist contract preserved). */
-    legacyBlocks: Array<{
+    /** The `prompt.assembled` block view (the id wordlist is a downstream contract). */
+    blocks: Array<{
         id: string;
         text: string;
     }>;

package/dist/prompt-assembly/assemble.js

@@ -23,7 +23,7 @@ function subsetPack(base, opts) {
         ...base,
         sections: base.sections
             .filter((s) => (opts.keep ? opts.keep.has(s.id) : true) && !(opts.exclude?.has(s.id) ?? false))
-            .map((s) => (s.id === "core/role.base" && opts.roleBaseLegacyId ? { ...s, legacyBlockId: opts.roleBaseLegacyId } : s)),
+            .map((s) => (s.id === "core/role.base" && opts.roleBaseBlockId ? { ...s, blockId: opts.roleBaseBlockId } : s)),
     };
 }
 function verifyDeclaredContentHash(d, onWarn) {
@@ -65,7 +65,7 @@ function mountDeclarations(basePack, decls, onWarn) {
             cacheClass: "prefix-stable",
             carrier: "system.block",
             content: () => d.text,
-            legacyBlockId: d.id,
+            blockId: d.id,
             ...(declaredContentHash !== undefined ? { declaredContentHash } : {}),
             origin: "provider",
         });
@@ -137,7 +137,7 @@ export function assemblePrompt(inputs) {
                 verifyDeclaredContentHash(assembledIdentity, onWarn);
                 onWarn?.(`prompt-provider stableBlocks: contentHash on "${assembledIdentity.id}" is ignored on the pass-through path (the text is emitted as core/role.base — a digest there would carry the wrong identity). Declare ONLY the role layer to keep the reconciliation anchor.`, "prompt-constitution");
             }
-            const ptPack0 = subsetPack(SEMA_DEFAULT_PACK, { keep: OPAQUE_KEPT, roleBaseLegacyId: "provider.assembled" });
+            const ptPack0 = subsetPack(SEMA_DEFAULT_PACK, { keep: OPAQUE_KEPT, roleBaseBlockId: "provider.assembled" });
             const ptPack = { ...ptPack0, sections: ptPack0.sections.map((s) => (s.id === "core/role.base" ? { ...s, origin: "provider" } : s)) };
             let lastPT = compose(ptPack, renderInputsPT(inputs.date));
             return {
@@ -150,8 +150,8 @@ export function assemblePrompt(inputs) {
                 get systemPrompt() {
                     return lastPT.text;
                 },
-                get legacyBlocks() {
-                    return lastPT.legacyBlocks;
+                get blocks() {
+                    return lastPT.blocks;
                 },
                 get sections() {
                     return lastPT.sections;
@@ -180,13 +180,13 @@ export function assemblePrompt(inputs) {
             constitution = "replaced";
             roleBase = roleOut;
             roleBaseOrigin = "provider";
-            pack = subsetPack(SEMA_DEFAULT_PACK, { exclude: REPLACE_ALL_EXCLUDED, roleBaseLegacyId: "provider.replace_all" });
+            pack = subsetPack(SEMA_DEFAULT_PACK, { exclude: REPLACE_ALL_EXCLUDED, roleBaseBlockId: "provider.replace_all" });
         }
         else if (roleOut.includes(CYBER_RISK) && roleOut.includes(URL_SAFETY) && roleOut.includes(HARNESS_SECTION_ANCHOR)) {
             constitution = "provider-assembled";
             roleBase = roleOut;
             roleBaseOrigin = "provider";
-            pack = subsetPack(SEMA_DEFAULT_PACK, { keep: OPAQUE_KEPT, roleBaseLegacyId: "provider.assembled" });
+            pack = subsetPack(SEMA_DEFAULT_PACK, { keep: OPAQUE_KEPT, roleBaseBlockId: "provider.assembled" });
             onWarn?.("prompt-constitution: this PromptProvider returns an already-assembled prompt (constitution anchor found). Core now appends the constitution structurally — return ONLY the role base from stableSystem (or set replaceAll:true to own the whole base). Passed through un-doubled.", "prompt-constitution");
         }
         else {
@@ -227,8 +227,8 @@ export function assemblePrompt(inputs) {
         get systemPrompt() {
             return last.text;
         },
-        get legacyBlocks() {
-            return last.legacyBlocks;
+        get blocks() {
+            return last.blocks;
         },
         get sections() {
             return last.sections;