@sensigo/realm 0.14.1 → 0.16.0

package/dist/engine/execution-loop.js

@@ -3,14 +3,17 @@ import { WorkflowError } from '../types/workflow-error.js';
 import { captureEvidence } from '../evidence/snapshot.js';
 import { validateInputSchema, validateOutputSchema, validateTraceSchema, } from '../validation/input-schema.js';
 import { normalizeTrace } from './trace-normalizer.js';
-import { TERMINAL_PHASES, isTerminalPhase } from './lifecycle.js';
+import { TERMINAL_PHASES, isTerminalPhase, DRAIN_CEILING_SECONDS } from './lifecycle.js';
+import { omitClaim, shouldEnforceTimeout, DEFAULT_EXECUTION_TIMEOUT_SECONDS, } from './claim-liveness.js';
+import { computeBackoff } from './backoff.js';
 import { checkPreconditions, evaluateAllPreconditions, evaluateGuardConditions, } from './precondition.js';
 import { ExtensionRegistry } from '../extensions/registry.js';
 import { createDefaultRegistry } from '../extensions/default-registry.js';
 import { renderTemplate, resolvePath, UnknownFilterError } from './render-template.js';
 import { generateSchemaSkeleton } from '../utils/schema-skeleton.js';
 import { loadWorkflowContext } from './workflow-context-loader.js';
-import { findEligibleSteps, findEligibleGuardSteps, isWorkflowComplete, buildEvidenceByStep, propagateSkips, } from './eligibility.js';
+import { findEligibleSteps, findEligibleGuardSteps, isWorkflowComplete, buildEvidenceByStep, propagateSkips, deriveRunPhase, } from './eligibility.js';
+import { requirementForStep } from './capability.js';
 import { resolvePreExecutionAgentAction, resolvePostDispatchAgentAction, } from './error-resolution.js';
 function delayMs(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -83,23 +86,6 @@ function resolveInputMapNode(node, root, keyChain, depth) {
     }
     return result;
 }
-/** Computes the delay (ms) before a retry attempt based on the configured backoff strategy. */
-function computeBackoff(config, attemptNum) {
-    const backoff = config.backoff ?? 'fixed';
-    const base = config.base_delay_ms ?? 0;
-    let delay;
-    switch (backoff) {
-        case 'linear':
-            delay = base * attemptNum;
-            break;
-        case 'exponential':
-            delay = base * Math.pow(2, attemptNum - 1);
-            break;
-        default: // 'fixed'
-            delay = base;
-    }
-    return config.max_delay_ms !== undefined ? Math.min(delay, config.max_delay_ms) : delay;
-}
 /**
  * Resolves and calls the service adapter for an auto step with `uses_service`.
  *
@@ -130,7 +116,9 @@ async function callAdapter(stepDef, definition, options, pendingRun, rateLimiter
             ? `. Declare this adapter under 'adapters:' in realm.yaml at your deployment root.`
             : '';
         throw new WorkflowError(`Adapter '${serviceDef.adapter}' for service '${serviceName}' is not registered${extensionHint}`, {
-            code: 'ENGINE_ADAPTER_FAILED',
+            // #134 discriminator: minted at the NOT-REGISTERED site ONLY (not the service-not-found or
+            // adapter-runtime throws), so Step 5 can settle this RECOVERABLY instead of terminal-burning.
+            code: 'ENGINE_ADAPTER_NOT_REGISTERED',
             category: 'ENGINE',
             agentAction: 'stop',
             retryable: false,
@@ -252,7 +240,9 @@ async function callHandler(stepDef, options, pendingRun, evidenceByStep, signal)
     const handler = (options.registry ?? createDefaultRegistry()).getHandler(handlerName);
     if (handler === undefined) {
         throw new WorkflowError(`Handler '${handlerName}' is not registered`, {
-            code: 'ENGINE_HANDLER_FAILED',
+            // #134 discriminator: minted at the NOT-REGISTERED site ONLY (not the ran-and-threw throw
+            // below), so Step 5 can settle this RECOVERABLY instead of terminal-burning the step.
+            code: 'ENGINE_HANDLER_NOT_REGISTERED',
             category: 'ENGINE',
             agentAction: 'stop',
             retryable: false,
@@ -684,7 +674,17 @@ export async function executeStep(store, definition, options) {
     // Step 4: Dispatch with retry and timeout.
     const retryConfig = stepDef?.retry;
     const maxAttempts = retryConfig?.max_attempts ?? 1;
-    const timeoutMs = stepDef?.timeout_seconds !== undefined ? stepDef.timeout_seconds * 1000 : undefined;
+    // A3: every `execution: 'auto'` step is bounded — authored timeout_seconds if declared, else the
+    // generous DEFAULT_EXECUTION_TIMEOUT_SECONDS default. Resolved ONCE here (before the retry loop
+    // below), not per-attempt. Agent/guard steps (shouldEnforceTimeout false) are untouched: agent
+    // dispatch stays the instant-return no-op it always was, never wrapped in withTimeout.
+    // effectiveTimeoutSeconds is the single source of truth; timeoutMs is derived from it so the
+    // two can never diverge. It is also surfaced onto the evidence snapshot below.
+    const enforceTimeout = stepDef !== undefined && shouldEnforceTimeout(stepDef);
+    const effectiveTimeoutSeconds = enforceTimeout
+        ? (stepDef.timeout_seconds ?? DEFAULT_EXECUTION_TIMEOUT_SECONDS)
+        : undefined;
+    const timeoutMs = effectiveTimeoutSeconds !== undefined ? effectiveTimeoutSeconds * 1000 : undefined;
     // Create a stable rate-limiter registry for all retry attempts of this step.
     // Shared state ensures that a pause() triggered on attempt N is still in effect
     // when the proactive acquire() runs on attempt N+1. When the caller provides an
@@ -754,6 +754,8 @@ export async function executeStep(store, definition, options) {
                 const withHandlerSkipped = {
                     ...pendingRun,
                     in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== options.command),
+                    // Delete the claim clock in the SAME mutation that removes the step (issue #101).
+                    claims: omitClaim(pendingRun.claims, options.command),
                     evidence: [...pendingRun.evidence, abortEvidence],
                     skipped_steps: [...pendingRun.skipped_steps, options.command],
                 };
@@ -761,7 +763,7 @@ export async function executeStep(store, definition, options) {
                     ...withHandlerSkipped,
                     skipped_steps: propagateSkips(withHandlerSkipped, definition),
                 };
-                const abortedRun = {
+                const abortDraft = {
                     ...withAllSkipped,
                     terminal_state: true,
                     terminal_reason: `Handler '${options.command}' aborted the run: ${abortMessage}`,
@@ -770,6 +772,9 @@ export async function executeStep(store, definition, options) {
                         abort_message: abortMessage,
                     },
                 };
+                // NEW: a handler-abort now drains the abort/always finalizers before sealing
+                // (previously it sealed-and-returned immediately). Single seal write below.
+                const abortedRun = await buildFinalizedSeal(definition, abortDraft, 'abort', options.registry);
                 let persistedAbortRun;
                 try {
                     persistedAbortRun = await store.update(abortedRun);
@@ -836,6 +841,7 @@ export async function executeStep(store, definition, options) {
             ...(options.stepMeta?.toolCalls !== undefined
                 ? { toolCalls: options.stepMeta.toolCalls }
                 : {}),
+            ...(effectiveTimeoutSeconds !== undefined ? { effectiveTimeoutSeconds } : {}),
             // Gate trace to agent steps only — drop silently for auto/adapter/handler steps.
             // When pre-normalized (WAL merge + schema validation ran), pass the pre-normalized
             // result to avoid double normalization. Also handle WAL-only case (options.trace may
@@ -868,25 +874,122 @@ export async function executeStep(store, definition, options) {
     }
     if (dispatchError !== null && retryConfig !== undefined && attemptsUsed === maxAttempts) {
         const lastError = dispatchError;
-        dispatchError = new WorkflowError(`Step '${options.command}' failed after ${attemptsUsed} attempts`, {
-            code: 'STEP_RETRY_EXHAUSTED',
-            category: 'ENGINE',
-            agentAction: 'report_to_user',
-            retryable: false,
-            details: {
-                stepName: options.command,
-                attempts: attemptsUsed,
-                lastError: lastError.message,
-                ...(lastError.retry_after !== undefined ? { retry_after: lastError.retry_after } : {}),
-            },
-        });
+        // #134: do NOT wrap a recoverable-incapability error (a max_attempts:1 not-registered failure
+        // hits attemptsUsed === maxAttempts). The STEP_RETRY_EXHAUSTED wrap discards the inner code, which
+        // would rob Step 5 of the discriminator it needs to settle recoverably. Leave dispatchError as the
+        // original not-registered error; all other codes wrap unchanged.
+        const isRecoverableIncapability = lastError instanceof WorkflowError &&
+            (lastError.code === 'ENGINE_HANDLER_NOT_REGISTERED' ||
+                lastError.code === 'ENGINE_ADAPTER_NOT_REGISTERED');
+        if (!isRecoverableIncapability) {
+            dispatchError = new WorkflowError(`Step '${options.command}' failed after ${attemptsUsed} attempts`, {
+                code: 'STEP_RETRY_EXHAUSTED',
+                category: 'ENGINE',
+                agentAction: 'report_to_user',
+                retryable: false,
+                details: {
+                    stepName: options.command,
+                    attempts: attemptsUsed,
+                    lastError: lastError.message,
+                    ...(lastError.retry_after !== undefined ? { retry_after: lastError.retry_after } : {}),
+                },
+            });
+        }
     }
     // Step 5: Handle dispatch failure — move step to failed_steps.
     if (dispatchError !== null) {
+        // #134 recoverable-incapability settle: a NOT-REGISTERED handler/adapter means THIS runner cannot
+        // execute the step, but a correctly-provisioned runner can. Terminal-burning it into failed_steps
+        // would make it permanently un-reclaimable. Instead settle RECOVERABLY: drop it from in_progress and
+        // omit its claim (same mutation), do NOT add it to failed_steps, do NOT seal the run, record a
+        // capability_blocks marker for diagnostics, and let it fall back to eligible so a capable runner
+        // reclaims it. Genuine ran-and-threw / service-not-found / adapter-runtime failures keep their
+        // ENGINE_*_FAILED codes and fall through to the terminal path below unchanged.
+        const recoverableCode = dispatchError instanceof WorkflowError &&
+            (dispatchError.code === 'ENGINE_HANDLER_NOT_REGISTERED' ||
+                dispatchError.code === 'ENGINE_ADAPTER_NOT_REGISTERED')
+            ? dispatchError.code
+            : undefined;
+        if (recoverableCode !== undefined) {
+            const requirement = requirementForStep(options.command, stepDef, definition);
+            const blockedDraft = {
+                ...pendingRun,
+                in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== options.command),
+                // Delete the claim clock in the SAME mutation that removes the step (issue #101).
+                claims: omitClaim(pendingRun.claims, options.command),
+                evidence: [...pendingRun.evidence, ...allEvidence],
+                capability_blocks: {
+                    ...pendingRun.capability_blocks,
+                    [options.command]: {
+                        requirement: requirement !== undefined
+                            ? { kind: requirement.kind, name: requirement.name }
+                            : {
+                                kind: recoverableCode === 'ENGINE_HANDLER_NOT_REGISTERED' ? 'handler' : 'adapter',
+                                name: 'unknown',
+                            },
+                        code: recoverableCode,
+                        at: new Date().toISOString(),
+                    },
+                },
+            };
+            // Non-terminal: recompute the phase so the store-fail fallback below is correct too
+            // (on the happy path store.update recomputes it identically via deriveRunPhase).
+            const blockedRun = { ...blockedDraft, run_phase: deriveRunPhase(blockedDraft) };
+            let persistedBlockedRun;
+            let blockStoreWarning;
+            try {
+                persistedBlockedRun = await store.update(blockedRun);
+            }
+            catch (storeErr) {
+                blockStoreWarning = `Failed to persist capability block: ${storeErr instanceof Error ? storeErr.message : String(storeErr)}`;
+            }
+            let blockWalWarning;
+            try {
+                // Delete WAL after run state is written — the step's entries are now in evidence.
+                await options.traceBufferStore?.delete(options.runId, options.command);
+            }
+            catch (walErr) {
+                blockWalWarning = `Failed to clean up trace buffer after capability block: ${walErr instanceof Error ? walErr.message : String(walErr)}`;
+            }
+            // Non-terminal 'stop' → 'report_to_user' via the existing mapping: a human must provision the
+            // runner (or re-run on a capable one); no further progress is possible on THIS runner.
+            const blockedAction = resolvePostDispatchAgentAction(dispatchError, false);
+            let blockedNextActions = [];
+            if (blockedAction !== 'stop' && blockStoreWarning === undefined) {
+                try {
+                    blockedNextActions = buildNextActions(definition, persistedBlockedRun ?? blockedRun);
+                }
+                catch {
+                    // buildNextActions can throw for unresolvable template references; fall back to [].
+                }
+            }
+            const reqLabel = requirement !== undefined
+                ? `${requirement.kind} '${requirement.name}'`
+                : recoverableCode === 'ENGINE_HANDLER_NOT_REGISTERED'
+                    ? 'handler'
+                    : 'adapter';
+            return {
+                command: options.command,
+                run_id: options.runId,
+                run_version: (persistedBlockedRun ?? blockedRun).version,
+                status: 'error',
+                data: {},
+                evidence: allEvidence,
+                warnings: mergeWarnings(traceWarnings, blockStoreWarning ?? blockWalWarning),
+                errors: [dispatchError.message],
+                agent_action: blockedAction,
+                error_code: recoverableCode,
+                context_hint: `Step '${options.command}' is blocked: its ${reqLabel} is not registered in this runner. The run is NOT terminated — the step remains eligible, so a runner that provides this ${requirement?.kind ?? 'capability'} can execute it. Provision this runner (or re-run on a capable one), then follow next_actions.`,
+                run_phase: (persistedBlockedRun ?? blockedRun).run_phase,
+                next_actions: blockedNextActions,
+            };
+        }
         // Pure in-memory derivations — no I/O, no try required.
         const afterFail = {
             ...pendingRun,
             in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== options.command),
+            // Delete the claim clock in the SAME mutation that removes the step (issue #101).
+            claims: omitClaim(pendingRun.claims, options.command),
             failed_steps: [...pendingRun.failed_steps, options.command],
         };
         // Propagate skips: mark steps whose trigger_rule can never be satisfied after this failure.
@@ -901,7 +1004,7 @@ export async function executeStep(store, definition, options) {
             (withSkippedFail.in_progress_steps.length === 0 &&
                 findEligibleSteps(definition, withSkippedFail).length === 0 &&
                 findEligibleGuardSteps(definition, withSkippedFail).length === 0);
-        const failedRun = {
+        const failDraft = {
             ...withSkippedFail,
             evidence: [...pendingRun.evidence, ...allEvidence],
             terminal_state: isComplete,
@@ -909,6 +1012,11 @@ export async function executeStep(store, definition, options) {
                 ? { terminal_reason: `Step '${options.command}' failed: ${dispatchError.message}` }
                 : {}),
         };
+        // On the terminal transition, drain the fail/always finalizers before the single seal.
+        // Non-terminal failures (recovery steps remain) run no finalizers.
+        const failedRun = isComplete
+            ? await buildFinalizedSeal(definition, failDraft, 'fail', options.registry)
+            : failDraft;
         // Persist run state and WAL cleanup in separate try/catch blocks so a WAL deletion
         // failure does not mask a successful store.update.
         let persistedRun;
@@ -1109,6 +1217,8 @@ export async function executeStep(store, definition, options) {
     const afterComplete = {
         ...pendingRun,
         in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== options.command),
+        // Delete the claim clock in the SAME mutation that removes the step (issue #101).
+        claims: omitClaim(pendingRun.claims, options.command),
         completed_steps: [...pendingRun.completed_steps, options.command],
         evidence: [...pendingRun.evidence, ...allEvidence],
     };
@@ -1125,11 +1235,15 @@ export async function executeStep(store, definition, options) {
         (withSkippedComplete.in_progress_steps.length === 0 &&
             findEligibleSteps(definition, withSkippedComplete).length === 0 &&
             findEligibleGuardSteps(definition, withSkippedComplete).length === 0);
-    const finalRun = {
+    const completeDraft = {
         ...withSkippedComplete,
         terminal_state: isComplete,
         ...(isComplete ? { terminal_reason: `Workflow completed.` } : {}),
     };
+    // On the terminal transition, drain the complete/always finalizers before the single seal.
+    const finalRun = isComplete
+        ? await buildFinalizedSeal(definition, completeDraft, 'complete', options.registry)
+        : completeDraft;
     let savedRun;
     try {
         savedRun = await store.update(finalRun);
@@ -1250,6 +1364,8 @@ export async function submitHumanResponse(store, definition, options) {
     const afterGate = {
         ...rest,
         in_progress_steps: rest.in_progress_steps.filter((s) => s !== gateStepName),
+        // Delete the claim clock in the SAME mutation that removes the step (issue #101).
+        claims: omitClaim(rest.claims, gateStepName),
         completed_steps: [...rest.completed_steps, gateStepName],
         evidence: [...rest.evidence, gateSnapshot],
     };
@@ -1266,11 +1382,15 @@ export async function submitHumanResponse(store, definition, options) {
         (withSkippedGate.in_progress_steps.length === 0 &&
             findEligibleSteps(definition, withSkippedGate).length === 0 &&
             findEligibleGuardSteps(definition, withSkippedGate).length === 0);
-    const finalRun = {
+    const gateDraft = {
         ...withSkippedGate,
         terminal_state: isComplete,
         ...(isComplete ? { terminal_reason: `Workflow completed.` } : {}),
     };
+    // On the gate-completion terminal transition, drain complete/always finalizers before seal.
+    const finalRun = isComplete
+        ? await buildFinalizedSeal(definition, gateDraft, 'complete', options.registry)
+        : gateDraft;
     let savedRun;
     try {
         savedRun = await store.update(finalRun);
@@ -1418,6 +1538,129 @@ async function executeGuardStep(stepName, stepDef, definition, run) {
         },
     };
 }
+/** Normalizes a finalizer's `on_outcome` to a set of triggers. */
+function finalizerTriggers(stepDef) {
+    const raw = stepDef.on_outcome;
+    if (raw === undefined)
+        return new Set();
+    return new Set(Array.isArray(raw) ? raw : [raw]);
+}
+/**
+ * Drains the finalizers matching a run's terminal `outcome` and returns the FINALIZED
+ * RunRecord — the workflow-level try/catch/finally at the seal. Modeled on
+ * executeGuardStep, but it does NOT persist: the caller performs the run's single seal
+ * `store.update` with its own error/WAL/envelope handling.
+ *
+ * Selection & order:
+ *  - Group A (rank 0): `on_outcome` contains `outcome` (the specific catch/complete arm).
+ *  - Group B (rank 1): `on_outcome` contains `'always'` but NOT `outcome` (the `finally` arm;
+ *    a finalizer listing both runs once, in Group A).
+ *  - Each group in declaration order (`Object.entries`); Group A then Group B (`always` last).
+ *  - Idempotent at-most-once: any finalizer already in completed/failed_steps is skipped
+ *    (resume / re-drive safety).
+ *
+ * Each finalizer runs its handler via `callHandler` (never `claimStep`), wrapped in
+ * `withTimeout` honoring `timeout_seconds` (default `DRAIN_CEILING_SECONDS`). Success →
+ * evidence + completed_steps; thrown error / STEP_TIMEOUT / handler `{ abort }` → evidence
+ * marked failed + failed_steps, NON-FATAL (the drain continues). A finalizer NEVER mutates
+ * `aborted_at`, `terminal_reason`, `terminal_state`, `skipped_steps`, or emits next_actions —
+ * the terminal marks come from `sealDraft` and `deriveRunPhase` precedence keeps the phase.
+ */
+async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
+    // Zero-finalizer fast path: no finalizer steps declared ⇒ return the seal draft
+    // completely untouched (byte-identical to the pre-finalizer engine — the damage rail).
+    const hasFinalizers = Object.values(definition.steps).some((s) => s.execution === 'finalizer');
+    if (!hasFinalizers)
+        return sealDraft;
+    const settled = new Set([...sealDraft.completed_steps, ...sealDraft.failed_steps]);
+    const groupA = [];
+    const groupB = [];
+    for (const [name, step] of Object.entries(definition.steps)) {
+        if (step.execution !== 'finalizer')
+            continue;
+        if (settled.has(name))
+            continue; // at-most-once per run (resume / re-drive safety)
+        const triggers = finalizerTriggers(step);
+        if (triggers.has(outcome))
+            groupA.push([name, step]);
+        else if (triggers.has('always'))
+            groupB.push([name, step]);
+    }
+    let record = sealDraft;
+    for (const [name, step] of [...groupA, ...groupB]) {
+        const now = new Date();
+        const evidenceByStep = buildEvidenceByStep(record);
+        const timeoutMs = (step.timeout_seconds ?? DRAIN_CEILING_SECONDS) * 1000;
+        // Minimal per-finalizer dispatch options: handler-only, no input (input_map prohibited),
+        // no agent dispatcher path. callHandler resolves the handler from the injected registry.
+        const options = {
+            runId: record.id,
+            command: name,
+            input: {},
+            dispatcher: async () => ({}),
+            ...(registry !== undefined ? { registry } : {}),
+        };
+        try {
+            const result = await withTimeout((signal) => callHandler(step, options, record, evidenceByStep, signal), timeoutMs, name);
+            if (result.kind === 'abort') {
+                // A finalizer handler returning { abort } is a recorded NON-FATAL failure — it must
+                // never mutate aborted_at/terminal_reason (that would corrupt the sealed outcome).
+                record = {
+                    ...record,
+                    evidence: [
+                        ...record.evidence,
+                        captureEvidence({
+                            stepId: name,
+                            startedAt: now,
+                            completedAt: new Date(),
+                            input: {},
+                            output: { aborted: true, abort_message: result.message },
+                            error: `Finalizer '${name}' returned abort: ${result.message}`,
+                        }),
+                    ],
+                    failed_steps: [...record.failed_steps, name],
+                };
+            }
+            else {
+                record = {
+                    ...record,
+                    evidence: [
+                        ...record.evidence,
+                        captureEvidence({
+                            stepId: name,
+                            startedAt: now,
+                            completedAt: new Date(),
+                            input: {},
+                            output: result.output,
+                            ...(result.kind === 'warn' ? { warn: result.message } : {}),
+                        }),
+                    ],
+                    completed_steps: [...record.completed_steps, name],
+                };
+            }
+        }
+        catch (err) {
+            // Thrown handler error OR STEP_TIMEOUT → recorded failed, drain continues (non-fatal).
+            const message = err instanceof Error ? err.message : String(err);
+            record = {
+                ...record,
+                evidence: [
+                    ...record.evidence,
+                    captureEvidence({
+                        stepId: name,
+                        startedAt: now,
+                        completedAt: new Date(),
+                        input: {},
+                        output: {},
+                        error: `Finalizer '${name}' failed: ${message}`,
+                    }),
+                ],
+                failed_steps: [...record.failed_steps, name],
+            };
+        }
+    }
+    return { ...record, terminal_state: true };
+}
 async function executeChainInternal(store, definition, options, depth, chainedSteps) {
     if (depth > MAX_CHAIN_DEPTH) {
         return {
@@ -1469,10 +1712,29 @@ async function executeChainInternal(store, definition, options, depth, chainedSt
         const guardStepDef = definition.steps[guardName];
         // Execute inline (pure in-memory; returns updated RunRecord).
         const guardResult = await executeGuardStep(guardName, guardStepDef, definition, run);
+        // Capture the guard's OWN evidence (its last entry) BEFORE the finalizer drain appends
+        // finalizer evidence — the terminal return below surfaces only the guard's evidence.
+        const guardOwnEvidence = guardResult.evidence.slice(-1);
+        // Blocking fix #1: classify the terminal outcome by the SEALED record, not aborted_at
+        // alone. executeGuardStep sets terminal_state in THREE cases — abort (aborted_at set),
+        // resolution-error (failed, no aborted_at), and a PASS that completes the run
+        // (terminal_reason 'Workflow completed.', no aborted_at). `aborted_at ? 'abort' : 'fail'`
+        // would wrongly run the catch finalizers on that success. When terminal, drain the
+        // matching finalizers before the single seal write; non-terminal guard passes persist as-is.
+        const guardOutcome = guardResult.terminal_state
+            ? guardResult.aborted_at !== undefined
+                ? 'abort'
+                : guardResult.terminal_reason === 'Workflow completed.'
+                    ? 'complete'
+                    : 'fail'
+            : undefined;
+        const guardSealed = guardOutcome !== undefined
+            ? await buildFinalizedSeal(definition, guardResult, guardOutcome, options.registry)
+            : guardResult;
         // Persist the guard step result.
         let persistedGuardRun;
         try {
-            persistedGuardRun = await store.update(guardResult);
+            persistedGuardRun = await store.update(guardSealed);
         }
         catch (storeErr) {
             const msg = storeErr instanceof Error ? storeErr.message : String(storeErr);
@@ -1494,17 +1756,22 @@ async function executeChainInternal(store, definition, options, depth, chainedSt
         // Record in chained_auto_steps for visibility.
         chainedSteps.push({ step: guardName, run_phase: persistedGuardRun.run_phase });
         if (persistedGuardRun.terminal_state) {
-            // Guard aborted or had a resolution error — run is terminal.
-            const contextHint = persistedGuardRun.aborted_at !== undefined
+            // Run is terminal via this guard. Adjacent pre-existing bug fixed: a PASSING guard that
+            // COMPLETES the run was mislabeled "failed with a resolution error" — describe each of
+            // the three terminal outcomes correctly (classified by guardOutcome, not aborted_at alone).
+            const contextHint = guardOutcome === 'abort'
                 ? `Guard step '${guardName}' aborted the run.`
-                : `Guard step '${guardName}' failed with a resolution error. Run is terminated.`;
+                : guardOutcome === 'complete'
+                    ? `Guard step '${guardName}' passed and completed the run.`
+                    : `Guard step '${guardName}' failed with a resolution error. Run is terminated.`;
             return {
                 command: options.command,
                 run_id: options.runId,
                 run_version: persistedGuardRun.version,
                 status: 'ok',
                 data: {},
-                evidence: persistedGuardRun.evidence.slice(-1),
+                // The guard's own evidence entry, captured before the finalizer drain appended any.
+                evidence: guardOwnEvidence,
                 warnings: [],
                 errors: [],
                 context_hint: contextHint,