@sensigo/realm 0.15.0 → 0.16.0

package/dist/engine/claim-liveness.js

@@ -0,0 +1,108 @@
+import { computeBackoff } from './backoff.js';
+/**
+ * Default execution timeout (issue A3) enforced on every `execution: 'auto'` step that declares no
+ * `timeout_seconds` — bounds a hung adapter/handler call so it fails loudly (`STEP_TIMEOUT`)
+ * instead of pinning the runner forever. Generous (1 hour, GitHub-Actions-style): it guards against
+ * a genuine hang, not normal-operation latency. Also now the basis of the claim-deadline DETECTION
+ * horizon in `computeClaimDeadline` below, so detection tracks the real enforcement bound. See
+ * plans/execution-timeout-a3-design.md for the full rationale.
+ */
+export const DEFAULT_EXECUTION_TIMEOUT_SECONDS = 3600; // 1 hour
+/**
+ * Whether `step`'s dispatch must be bounded by a timeout (issue A3). Pure: `execution === 'auto'`,
+ * period. Deliberately NOT conjoined with `hasFinalizers` — that conjunct is correct for
+ * *detection*'s claim horizon below (a claim may legitimately be held through a finalizer drain),
+ * but would be WRONG for *enforcement*: it would leave every auto step in a finalizer-bearing
+ * workflow completely unbounded — the exact hang this feature exists to prevent. Do NOT re-add a
+ * `hasFinalizers`/finalizer conjunct here (this split was the Design Reviewer's blocking-fix).
+ */
+export function shouldEnforceTimeout(step) {
+    return step.execution === 'auto';
+}
+// --- Deadline constants (Phase 1: the deadline drives the DETECTION DISPLAY only; it gates no
+// action, so a too-large horizon merely delays a `claim_stale` label — bias LARGE).
+/**
+ * @deprecated Superseded by `DEFAULT_EXECUTION_TIMEOUT_SECONDS`; retained for API compatibility.
+ * Assumed handler wall-clock bound when a step declares no `timeout_seconds`. Biased large.
+ */
+export const DEFAULT_STEP_TIMEOUT_SECONDS = 300; // 5 min
+/** Added to a step's `timeout_seconds` to absorb scheduling / clock skew before a claim is stale. */
+export const RECLAIM_MARGIN_SECONDS = 60; // 1 min
+/**
+ * Minimum staleness horizon. A concrete claim is never `claim_stale` sooner than this, even for a
+ * fast handler — so a live-but-slow runner is not mislabeled. Biased large: too-large only delays
+ * the label (Phase 1 gates no action); too-small risks flagging live work. (Concrete deadlines are
+ * set ONLY for finalizer-free auto steps, so the worst-case finalizer-drain span never applies to a
+ * deadline-carrying claim — finalizer-bearing steps get `deadline: null` → `claim_unknown_age`.)
+ */
+export const RECLAIM_FLOOR_SECONDS = 900; // 15 min
+/**
+ * Computes the claim deadline for `stepName` at claim time. A CONCRETE deadline is returned ONLY
+ * for a reliably time-boundable claim: an `execution: 'auto'` (handler-driven) step in a workflow
+ * with NO `execution: 'finalizer'` steps (so no finalizer drain can legitimately extend the claim
+ * past the seal). Every other claim returns `null` (→ `claim_unknown_age`): agent steps have no
+ * reliable wall-clock bound (the dispatcher returns instantly; `timeout_seconds` is advisory), and
+ * any step in a finalizer-bearing workflow may hold its claim through the terminal drain.
+ *
+ * The horizon is the WORST-CASE wall-clock across every retry attempt (issue #101 follow-up —
+ * Design Reviewer finding #4 from the A3 debate): a single-attempt bound understates a retrying
+ * step's real claim span (`max_attempts × per-attempt-timeout + the declared backoffs between
+ * attempts`), so a legitimately-retrying step could be labeled `claim_stale` — and, if
+ * `idempotent`, become eligible for a premature `realm run reclaim --all --force` re-drive —
+ * while still on an early attempt. For `n = 1` (no `retry:`, or `max_attempts: 1`) this reduces
+ * EXACTLY to the prior single-attempt formula `max(RECLAIM_FLOOR, perAttemptSec + MARGIN)`, so
+ * non-retry steps' horizons are byte-unchanged. This uses the DECLARED backoff schedule only — a
+ * runtime `retry_after` (rate-limit 429 override, applied in execution-loop.ts) is not knowable at
+ * claim time; the horizon stays a best-effort, floored, advisory bound (Phase 1 gates no action on
+ * this label) and does not attempt to model `retry_after`.
+ */
+export function computeClaimDeadline(definition, stepName, now) {
+    const step = definition.steps[stepName];
+    if (step === undefined)
+        return null;
+    const hasFinalizers = Object.values(definition.steps).some((s) => s.execution === 'finalizer');
+    if (step.execution !== 'auto' || hasFinalizers)
+        return null;
+    const n = step.retry?.max_attempts ?? 1;
+    const perAttemptSec = step.timeout_seconds ?? DEFAULT_EXECUTION_TIMEOUT_SECONDS;
+    // Backoffs occur BETWEEN attempts: n-1 of them, for attemptNum 1..n-1 (matches the retry loop's
+    // schedule in execution-loop.ts). computeBackoff returns ms; the horizon is seconds.
+    let backoffSec = 0;
+    if (step.retry !== undefined) {
+        for (let a = 1; a < n; a++)
+            backoffSec += computeBackoff(step.retry, a) / 1000;
+    }
+    const worstCaseSec = n * perAttemptSec + backoffSec;
+    const horizonSeconds = Math.max(RECLAIM_FLOOR_SECONDS, worstCaseSec + RECLAIM_MARGIN_SECONDS);
+    return new Date(now.getTime() + horizonSeconds * 1000).toISOString();
+}
+/**
+ * Returns a NEW claims record with `stepName` removed (a fresh object — never mutates the input,
+ * so it is safe to use on a value spread from the prior record). Used at the settle/seal sites to
+ * delete the claim clock in the SAME record mutation that removes the step from
+ * `in_progress_steps`. Returns `{}` when the last claim is removed (harmless; detection ignores a
+ * run with no in-progress steps). A missed delete self-heals: `claimStep` overwrites `claims[S]`.
+ */
+export function omitClaim(claims, stepName) {
+    if (claims === undefined)
+        return {};
+    const { [stepName]: _removed, ...rest } = claims;
+    return rest;
+}
+/** Classifies a single claim record against `now`. Definition-free (reads only the stored deadline). */
+export function classifyClaim(claim, now) {
+    if (claim === undefined || claim.deadline === null)
+        return 'claim_unknown_age';
+    return now.getTime() > new Date(claim.deadline).getTime() ? 'claim_stale' : 'healthy';
+}
+/**
+ * Classifies every in-progress claim on a run. Definition-free — works even when the workflow
+ * definition is unresolved (detection reads the stored per-claim deadline, not the definition).
+ */
+export function classifyInProgressClaims(run, now = new Date()) {
+    return run.in_progress_steps.map((step) => {
+        const claim = run.claims?.[step];
+        return { step, state: classifyClaim(claim, now), deadline: claim?.deadline ?? null };
+    });
+}
+//# sourceMappingURL=claim-liveness.js.map

package/dist/engine/claim-liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim-liveness.js","sourceRoot":"","sources":["../../src/engine/claim-liveness.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,IAAI,CAAC,CAAC,SAAS;AAEhE;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAoB;IACvD,OAAO,IAAI,CAAC,SAAS,KAAK,MAAM,CAAC;AACnC,CAAC;AAED,+FAA+F;AAC/F,oFAAoF;AAEpF;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC,CAAC,QAAQ;AACzD,qGAAqG;AACrG,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC,CAAC,QAAQ;AAClD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC,CAAC,SAAS;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAA8B,EAC9B,QAAgB,EAChB,GAAS;IAET,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,WAAW,CAAC,CAAC;IAC/F,IAAI,IAAI,CAAC,SAAS,KAAK,MAAM,IAAI,aAAa;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC;IACxC,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,IAAI,iCAAiC,CAAC;IAChF,gGAAgG;IAChG,qFAAqF;IACrF,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YAAE,UAAU,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACjF,CAAC;IACD,MAAM,YAAY,GAAG,CAAC,GAAG,aAAa,GAAG,UAAU,CAAC;IACpD,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,qBAAqB,EAAE,YAAY,GAAG,sBAAsB,CAAC,CAAC;IAC9F,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,cAAc,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACvB,MAA+C,EAC/C,QAAgB;IAEhB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IACjD,OAAO,IAAI,CAAC;AACd,CAAC;AAWD,wGAAwG;AACxG,MAAM,UAAU,aAAa,CAAC,KAA8B,EAAE,GAAS;IACrE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,mBAAmB,CAAC;IAC/E,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;AACxF,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,GAAc,EACd,MAAY,IAAI,IAAI,EAAE;IAEtB,OAAO,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,IAAI,IAAI,EAAE,CAAC;IACvF,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/engine/execution-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-loop.d.ts","sourceRoot":"","sources":["../../src/engine/execution-loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execution-loop.d.ts","sourceRoot":"","sources":["../../src/engine/execution-loop.ts"],"names":[],"mappings":"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"}

package/dist/engine/execution-loop.js

@@ -4,13 +4,16 @@ 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, 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],
                 };
@@ -839,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
@@ -871,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.
@@ -1117,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],
     };
@@ -1262,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],
     };