@sensigo/realm 0.33.0 → 0.35.0

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

@@ -1,4 +1,4 @@
-import type { RunRecord, AgentTraceEntry } from '../types/run-record.js';
+import type { RunRecord, AgentTraceEntry, StructuredOutputMeta } from '../types/run-record.js';
 import type { ToolCallRecord } from '../types/mcp-types.js';
 import type { ResponseEnvelope, NextAction } from '../types/response-envelope.js';
 import { WorkflowError } from '../types/workflow-error.js';
@@ -22,9 +22,14 @@ export interface ExecuteStepOptions {
      * Tool calls produced by callStepWithTools for this step.
      * Absent on the callStep path (no tools configured).
      * Present (possibly []) when tools were declared — threads through to captureEvidence.
+     *
+     * `structuredOutput` (issue #236): the caller's own `structured_output: 'strict'` attempt
+     * disclosure for THIS attempt — threads into the diagnostics literal at every evidence-capture
+     * site. Independent of `toolCalls` (either alone must still cause `stepMeta` to be passed).
      */
     stepMeta?: {
         toolCalls?: ToolCallRecord[];
+        structuredOutput?: StructuredOutputMeta;
     };
     /**
      * Optional agent-submitted trace entries for this step.
@@ -50,6 +55,11 @@ export interface ExecuteStepOptions {
      * today's byte-identical behavior.
      */
     writerNonce?: string;
+    /**
+     * Issue #291: injectable clock for deterministic expiry tests (the execute_step pre-refusal
+     * enact-then-proceed check reads this). Defaults to `new Date()` — real callers never set it.
+     */
+    now?: Date;
 }
 export interface SubmitGateOptions {
     runId: string;
@@ -70,6 +80,12 @@ export interface SubmitGateOptions {
      * credential model stays authoritative); no arm ever reads it.
      */
     respondedBy?: string;
+    /**
+     * Issue #291: injectable clock for deterministic expiry tests (the F3 write-free
+     * `gate_expired_pending` refusal + the caller-issued `expire_gate` follow-up both read this).
+     * Defaults to `new Date()` — real callers never set it.
+     */
+    now?: Date;
 }
 export interface ExecuteChainOptions {
     runId: string;
@@ -82,9 +98,14 @@ export interface ExecuteChainOptions {
      * Tool calls produced by callStepWithTools for this step.
      * Absent on the callStep path (no tools configured).
      * Present (possibly []) when tools were declared — threads through to captureEvidence.
+     *
+     * `structuredOutput` (issue #236): the caller's own `structured_output: 'strict'` attempt
+     * disclosure for THIS attempt — threads into the diagnostics literal at every evidence-capture
+     * site. Independent of `toolCalls` (either alone must still cause `stepMeta` to be passed).
      */
     stepMeta?: {
         toolCalls?: ToolCallRecord[];
+        structuredOutput?: StructuredOutputMeta;
     };
     /** @see ExecuteStepOptions.trace */
     trace?: AgentTraceEntry[];

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,7 +4,8 @@ import { persistsField } from '../store/store-fidelity.js';
 import { storeDeclaresSeal, storeDeclaresNonceCarriage } from '../store/trace-buffer-store.js';
 import { partitionBufferedEntries } from './trace-adoption.js';
 import { deriveDefaultedSteps } from './defaulted-steps.js';
-import { selectFinalizers } from './settlement.js';
+import { computeGateDueState } from './gate-timing.js';
+import { selectFinalizers, deriveEffectiveTriggers, applySettlement } from './settlement.js';
 import { captureEvidence } from '../evidence/snapshot.js';
 import { validateInputSchema, validateOutputSchema, validateTraceSchema, } from '../validation/input-schema.js';
 import { normalizeTrace } from './trace-normalizer.js';
@@ -770,6 +771,72 @@ async function buildAlreadySettledEnvelope(store, definition, options, result, t
  */
 const DORMANCY_ADVISORY = 'settled via the legacy compatibility path — this store does not declare atomic settlement ' +
     '(RunStore.settleStep); upgrade the store to close the fan-out seal race (issue #279)';
+/**
+ * issue #291 (D1 "execute_step pre-refusal" enactment point — enact-then-proceed): if `run`
+ * carries an expired, enactable gate (`expires_at` past, `on_expiry` frozen), enacts it via the
+ * SAME dormancy-discriminated pattern `submitHumanResponse` uses (settleStep when declared, else
+ * the pure `applySettlement` transform + `store.update`'s CAS write) and returns the resulting
+ * (possibly unchanged) run plus any disclosure line for the caller's `warnings` array. A
+ * finding-only gate (no `on_expiry`) is a fast no-op — nothing to enact, never touched. Any
+ * refusal from the enactment attempt (a benign race: `already_settled`/`not_expired`/
+ * `gate_mismatch`/`run_terminal`) is absorbed silently — the caller's own subsequent eligibility
+ * re-check against the returned `run` is what actually matters, and a NOOP correctly leaves `run`
+ * as the fresh state the refusal matched against. [F4] advisory-not-crash: an external store's
+ * OWN `settleStep` throwing on the `expire_gate` kind (a pre-#291 re-implementing store
+ * honoring the union-openness contract's refuse-loud mandate) degrades to a console advisory and
+ * proceeds with `run` UNCHANGED — never crashes the caller's verb.
+ */
+async function enactExpiredGateIfDue(store, definition, run, registry, now) {
+    const gate = run.pending_gate;
+    if (gate === undefined ||
+        gate.expires_at === undefined ||
+        gate.on_expiry === undefined ||
+        now.getTime() < new Date(gate.expires_at).getTime()) {
+        return { run };
+    }
+    const delta = { kind: 'expire_gate', gateId: gate.gate_id };
+    let expireOutcome;
+    try {
+        if (store.settleStep !== undefined) {
+            expireOutcome = await store.settleStep(run.id, delta, definition, { now });
+        }
+        else {
+            const pure = applySettlement(run, delta, definition, { now });
+            if (!pure.applied) {
+                return { run: pure.run };
+            }
+            const persisted = await store.update(pure.run);
+            expireOutcome = { ...pure, run: persisted };
+        }
+    }
+    catch (err) {
+        console.warn(`⚠ realm: could not enact run '${run.id}''s expired gate '${gate.gate_id}' (${err instanceof Error ? err.message : String(err)}) — proceeding with the pre-enactment state.`);
+        return { run };
+    }
+    if (!expireOutcome.applied) {
+        return { run: expireOutcome.run };
+    }
+    let finalRun = expireOutcome.run;
+    const disclosureParts = [];
+    const disposition = finalRun.settled?.[gate.step_name]?.resolved_by === 'timeout' ? 'settle_default' : 'abort';
+    disclosureParts.push(`gate '${gate.gate_id}' on '${gate.step_name}' had expired — enacted declared ${disposition} before this execute_step call (enacted_via: execute_step).`);
+    if (expireOutcome.transitioned) {
+        try {
+            const drainOutcome = await drainFinalizers(store, definition, registry, run.id);
+            finalRun = drainOutcome.run;
+            disclosureParts.push(...drainOutcome.warnings);
+        }
+        catch (err) {
+            disclosureParts.push(`post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const disclosure = disclosureParts.join(' ');
+    // Printed unconditionally (never silently dropped, regardless of which downstream envelope
+    // path the caller's own request takes) — the caller ALSO threads this into whichever
+    // response-envelope warnings array is in scope at its own return point.
+    console.warn(`⚠ ${disclosure}`);
+    return { run: finalRun, disclosure };
+}
 /**
  * Validates eligibility, claims the step, executes it through the dispatcher with retry
  * and timeout support, captures evidence, persists the updated run record, and returns
@@ -793,6 +860,18 @@ export async function executeStep(store, definition, options) {
         });
         return makeErrorEnvelope(options, null, internal);
     }
+    // Step 1.5 (issue #291, D1 "execute_step pre-refusal" enactment point): if this run's gate has
+    // expired with an enactable disposition, enact it BEFORE the eligibility check below — a
+    // finding-only or non-expired gate is an immediate no-op (same `run` reference back). Level-
+    // triggering: the requested step may become newly eligible right here (settle_default/abort
+    // both clear `pending_gate`, un-blocking `findEligibleSteps`'s gate-serialization exclusion).
+    const gateExpiryCheckNow = options.now ?? new Date();
+    let gateExpiryDisclosure;
+    if (run.pending_gate !== undefined) {
+        const enacted = await enactExpiredGateIfDue(store, definition, run, options.registry, gateExpiryCheckNow);
+        run = enacted.run;
+        gateExpiryDisclosure = enacted.disclosure;
+    }
     // Step 2: Check eligibility.
     const eligible = findEligibleSteps(definition, run);
     if (!eligible.includes(options.command)) {
@@ -804,7 +883,7 @@ export async function executeStep(store, definition, options) {
             status: 'blocked',
             data: {},
             evidence: [],
-            warnings: [],
+            warnings: gateExpiryDisclosure !== undefined ? [gateExpiryDisclosure] : [],
             errors: [],
             agent_action: 'resolve_precondition',
             context_hint: `Step '${options.command}' is not eligible in the current run state.`,
@@ -1022,6 +1101,10 @@ export async function executeStep(store, definition, options) {
     // walEntries is declared at this outer scope because it is REASSIGNED to the post-claim read
     // below and referenced at the captureEvidence call site further down this function.
     const traceWarnings = [];
+    // issue #291: the Step-1.5 gate-expiry disclosure (if any) now rides every downstream envelope
+    // this function's own `traceWarnings` threading already reaches.
+    if (gateExpiryDisclosure !== undefined)
+        traceWarnings.push(gateExpiryDisclosure);
     let preNormalizedTrace;
     let walEntries = [];
     let preClaimSchemaResult;
@@ -1724,6 +1807,20 @@ export async function executeStep(store, definition, options) {
                     ...(attemptError === null && (run.validation_rejections?.[options.command] ?? 0) > 0
                         ? { validation_rejections: run.validation_rejections[options.command] }
                         : {}),
+                    // issue #236: the attempt's structured_output disclosure. External-agent stamp [Rv6 +
+                    // R2-3]: a step that DECLARED structured_output but arrives with no
+                    // options.stepMeta.structuredOutput at all was driven by something other than
+                    // run-agent (e.g. an external agent calling execute_step over MCP directly) — realm
+                    // cannot know whether strict was honored, so it says so rather than staying silent.
+                    ...(stepDef?.structured_output !== undefined
+                        ? {
+                            structured_output: options.stepMeta?.structuredOutput ?? {
+                                requested: true,
+                                sent: false,
+                                downgrade_reason: 'external_agent',
+                            },
+                        }
+                        : {}),
                 },
                 ...(profileData !== undefined
                     ? { agentProfile: profile, agentProfileHash: profileData.content_hash }
@@ -1830,6 +1927,17 @@ export async function executeStep(store, definition, options) {
                 precondition_trace: preconditionTrace,
                 settled_by_default: true,
                 validation_rejections: exhaustion.details['rejections'],
+                // issue #236: same disclosure/external-agent-stamp rule as the real dispatch-loop
+                // capture above.
+                ...(stepDef?.structured_output !== undefined
+                    ? {
+                        structured_output: options.stepMeta?.structuredOutput ?? {
+                            requested: true,
+                            sent: false,
+                            downgrade_reason: 'external_agent',
+                        },
+                    }
+                    : {}),
             },
             ...(defaultProfileData !== undefined
                 ? { agentProfile: defaultProfile, agentProfileHash: defaultProfileData.content_hash }
@@ -1887,6 +1995,17 @@ export async function executeStep(store, definition, options) {
                 input_token_estimate: inputTokenEstimate,
                 precondition_trace: preconditionTrace,
                 validation_rejections: exhaustion.details['rejections'],
+                // issue #236: same disclosure/external-agent-stamp rule as the real dispatch-loop
+                // capture above.
+                ...(stepDef?.structured_output !== undefined
+                    ? {
+                        structured_output: options.stepMeta?.structuredOutput ?? {
+                            requested: true,
+                            sent: false,
+                            downgrade_reason: 'external_agent',
+                        },
+                    }
+                    : {}),
             },
             ...(exhaustedProfileData !== undefined
                 ? { agentProfile: exhaustedProfile, agentProfileHash: exhaustedProfileData.content_hash }
@@ -2428,6 +2547,17 @@ export async function executeStep(store, definition, options) {
             resolvedGateMessage = raw;
         }
         const gateConfig = stepDef.gate;
+        const openedAt = new Date();
+        // issue #291 (mint-time freeze, [F2]): the gate's OWN enforce/notify clock fields, frozen
+        // into the record HERE — never re-read from the definition by any later enactment/
+        // notification/read-side surface (the definition-drift-livelock cure). `expires_at` derives
+        // from THIS `openedAt` instant, never a second `new Date()` call. `reminder_max` defaults to
+        // 3 at mint when `reminder_seconds` is declared and the author gave no explicit value — so
+        // every later reader can treat the frozen field as authoritative without re-applying a
+        // default itself.
+        const expiresAt = gateConfig?.timeout_seconds !== undefined
+            ? new Date(openedAt.getTime() + gateConfig.timeout_seconds * 1000).toISOString()
+            : undefined;
         // The PendingGate object is built EXACTLY as before, regardless of which path commits it below
         // (issue #279, increment 2, PR-D, Deliverable 1a — the migrated `open_gate` delta carries this
         // SAME object verbatim; the legacy fallback writes it via `store.update` unchanged).
@@ -2436,13 +2566,30 @@ export async function executeStep(store, definition, options) {
             step_name,
             preview: output,
             choices,
-            opened_at: new Date().toISOString(),
+            opened_at: openedAt.toISOString(),
             ...(gateConfig?.owner !== undefined ? { owner: gateConfig.owner } : {}),
             ...(resolvedGateMessage !== undefined ? { resolved_message: resolvedGateMessage } : {}),
             ...(gateConfig?.resolution_messages !== undefined
                 ? { resolution_messages: gateConfig.resolution_messages }
                 : {}),
+            // issue #291: the mint-frozen enforce clock.
+            ...(expiresAt !== undefined ? { expires_at: expiresAt } : {}),
+            ...(gateConfig?.on_expiry !== undefined ? { on_expiry: gateConfig.on_expiry } : {}),
+            ...(gateConfig?.default_choice !== undefined
+                ? { default_choice: gateConfig.default_choice }
+                : {}),
+            // issue #291: the mint-frozen notify clock (standalone-legal — independent of expiresAt).
+            ...(gateConfig?.reminder_seconds !== undefined
+                ? {
+                    reminder_seconds: gateConfig.reminder_seconds,
+                    reminder_max: gateConfig.reminder_max ?? 3,
+                }
+                : {}),
         };
+        // issue #291 ([F-A2-6]): computed ONCE for the whole gate-open envelope (migrated + legacy
+        // both read it) — the absolute first-due notify-clock timestamp, when reminder_seconds was
+        // declared.
+        const gateOpenDueState = computeGateDueState(pendingGate, openedAt);
         // gate.display fallback chain: gate.message resolved → step.prompt resolved → absent
         const resolvedGateDisplay = resolvedGateMessage !== undefined
             ? resolvedGateMessage
@@ -2532,6 +2679,7 @@ export async function executeStep(store, definition, options) {
                     // discarded). Calm, confirm_required (the gate genuinely IS still open) — never
                     // report_to_user (no `agent_action` set, matching the fresh-open confirm_required shape).
                     const liveGate = result.gate;
+                    const liveGateDueState = computeGateDueState(liveGate, new Date());
                     return {
                         command: options.command,
                         run_id: options.runId,
@@ -2555,6 +2703,10 @@ export async function executeStep(store, definition, options) {
                                 ? { display: liveGate.resolved_message }
                                 : {}),
                             response_spec: { choices: liveGate.choices },
+                            ...(liveGate.expires_at !== undefined ? { expires_at: liveGate.expires_at } : {}),
+                            ...(liveGateDueState.next_reminder_due_at !== undefined
+                                ? { first_reminder_due_at: liveGateDueState.next_reminder_due_at }
+                                : {}),
                         },
                     };
                 }
@@ -2585,6 +2737,10 @@ export async function executeStep(store, definition, options) {
                         ? { agent_hint: resolvedGateInstructions }
                         : {}),
                     response_spec: { choices },
+                    ...(pendingGate.expires_at !== undefined ? { expires_at: pendingGate.expires_at } : {}),
+                    ...(gateOpenDueState.next_reminder_due_at !== undefined
+                        ? { first_reminder_due_at: gateOpenDueState.next_reminder_due_at }
+                        : {}),
                 },
             };
         }
@@ -2629,6 +2785,10 @@ export async function executeStep(store, definition, options) {
                 ...(resolvedGateDisplay !== undefined ? { display: resolvedGateDisplay } : {}),
                 ...(resolvedGateInstructions !== undefined ? { agent_hint: resolvedGateInstructions } : {}),
                 response_spec: { choices },
+                ...(pendingGate.expires_at !== undefined ? { expires_at: pendingGate.expires_at } : {}),
+                ...(gateOpenDueState.next_reminder_due_at !== undefined
+                    ? { first_reminder_due_at: gateOpenDueState.next_reminder_due_at }
+                    : {}),
             },
         };
     }
@@ -2946,6 +3106,119 @@ function buildGateResponseSnapshot(gate, choice, respondedAt, respondedBy) {
         ...(respondedBy !== undefined ? { responded_by: respondedBy } : {}),
     };
 }
+/** Renders a millisecond duration as a compact human-readable string ("3m", "2h 15m", "1d 4h") —
+ *  issue #291 [F8] overdue-delta disclosure. Local to this file (core has no CLI dependency);
+ *  mirrors the CLI's own `formatGateAge` shape but is independently maintained — no cross-package
+ *  import for a two-branch formatter. */
+function formatOverdueDuration(ms) {
+    const totalMinutes = Math.floor(ms / 60_000);
+    const totalHours = Math.floor(totalMinutes / 60);
+    const totalDays = Math.floor(totalHours / 24);
+    if (totalMinutes < 60)
+        return `${totalMinutes}m`;
+    if (totalHours < 24)
+        return `${totalHours}h ${totalMinutes % 60}m`;
+    return `${totalDays}d ${totalHours % 24}h`;
+}
+/**
+ * issue #291 ([F3] shape c / [F8] / [F12]): composes the honest envelope for a late gate response
+ * that lost the race to the enforce clock — called AFTER an `expire_gate` settleStep attempt,
+ * regardless of whether THIS call enacted it (`applied: true`) or a racing enactment point already
+ * had (`applied: false, reason: 'already_settled'` — F1's arms make both paths land on the SAME
+ * committed disposition, read from `finalRun`). `finalRun` must be the state that actually reflects
+ * the enactment (either `expireResult.run` directly). Drains post-commit finalizers when the
+ * enactment itself transitioned the run (F7 — submit's existing transitioned-drain plumbing,
+ * extended to the expire result); a store lacking `settleStep`'s companion `drainFinalizers`
+ * capability is not a concern here — `drainFinalizers` works off any `RunStore`.
+ */
+async function composeExpiredGateEnvelope(store, definition, registry, originalGateId, originalChoice, overdueMs, expireResult) {
+    let finalRun = expireResult.run;
+    let drainWarnings = [];
+    if (expireResult.applied && expireResult.transitioned) {
+        try {
+            const drainOutcome = await drainFinalizers(store, definition, registry, finalRun.id);
+            finalRun = drainOutcome.run;
+            drainWarnings = drainOutcome.warnings;
+        }
+        catch (err) {
+            drainWarnings = [
+                `post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`,
+            ];
+        }
+    }
+    const overdueLabel = formatOverdueDuration(Math.max(0, overdueMs));
+    // settle_default disposition: a 'gate' settled entry bearing this gateId, resolved_by:'timeout'.
+    const settledEntry = Object.entries(finalRun.settled ?? {}).find(([, e]) => e.outcome === 'gate' && e.token === originalGateId && e.resolved_by === 'timeout');
+    if (settledEntry !== undefined) {
+        const [stepName, entry] = settledEntry;
+        const enactedDisclosure = `gate '${originalGateId}' expired ${overdueLabel} ago and was enacted (settle_default: '${entry.choice}') before this response arrived — enacted_via: submit.`;
+        if (entry.choice === originalChoice) {
+            // [F12]'s own pinned string — same choice, still honestly not "your" recorded response.
+            return {
+                command: stepName,
+                run_id: finalRun.id,
+                run_version: finalRun.version,
+                status: 'ok',
+                data: {},
+                evidence: [],
+                warnings: mergeWarnings([], enactedDisclosure, ...drainWarnings),
+                errors: [],
+                context_hint: 'the outcome matches your choice, but it was settled by timeout; your response was not recorded.',
+                run_phase: finalRun.run_phase,
+                next_actions: finalRun.terminal_state ? [] : buildNextActions(definition, finalRun),
+            };
+        }
+        const err = new WorkflowError(`Gate '${originalGateId}' was settled by timeout with choice '${entry.choice}' — your choice '${originalChoice}' was not recorded.`, {
+            code: 'STATE_BLOCKED',
+            category: 'STATE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: {
+                runId: finalRun.id,
+                gateId: originalGateId,
+                winning_choice: entry.choice,
+                resolved_by: 'timeout',
+            },
+        });
+        const envelope = errorEnvelope(stepName, finalRun.id, finalRun.version, err, err.message, finalRun.run_phase);
+        return { ...envelope, warnings: mergeWarnings([], enactedDisclosure, ...drainWarnings) };
+    }
+    // abort disposition: a skip_details entry kind 'gate_expired' bearing this gateId.
+    const abortEntry = Object.entries(finalRun.skip_details ?? {}).find(([, d]) => d.kind === 'gate_expired' && d.gate_id === originalGateId);
+    if (abortEntry !== undefined) {
+        const [stepName] = abortEntry;
+        const enactedDisclosure = `gate '${originalGateId}' expired ${overdueLabel} ago and was enacted (abort) before this response arrived — enacted_via: submit.`;
+        const err = new WorkflowError(`Gate '${originalGateId}' on '${stepName}' expired and the run aborted per the ` +
+            `workflow's declared on_expiry — your choice was NOT recorded.`, {
+            code: 'STATE_RUN_TERMINAL',
+            category: 'STATE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: { runId: finalRun.id, gateId: originalGateId, step_name: stepName },
+        });
+        const envelope = errorEnvelope(stepName, finalRun.id, finalRun.version, err, err.message, finalRun.run_phase);
+        return { ...envelope, warnings: mergeWarnings([], enactedDisclosure, ...drainWarnings) };
+    }
+    // issue #319: rare-by-construction, not unreachable. Reachable ONLY in the migrated-path race
+    // window where a concurrent writer terminalized the run BETWEEN the F3 gate_expired_pending
+    // refusal and this caller's own expire delta being applied — neither search above finds a
+    // matching entry because the concurrent settlement recorded a DIFFERENT gate/step, never this
+    // one (the #317-correction discriminator: this cell is proven reachable only with a terminal
+    // `finalRun`, since the legacy snapshot path answers both searches from one snapshot and can
+    // never fall through to here). The honest answer is a terminal disclosure, not an engine fault
+    // — never attribute the outcome to THIS gate's expiry (no matched entry exists to attribute it
+    // to), and never claim "expired" at all, since nothing here witnessed this gate expiring.
+    const err = new WorkflowError(`Gate '${originalGateId}': the run reached a terminal outcome concurrently — your choice ` +
+        `was NOT recorded. 'realm resume' clears a stale pending gate on a resumable run, or ` +
+        `'realm run purge' removes the record entirely.`, {
+        code: 'STATE_RUN_TERMINAL',
+        category: 'STATE',
+        agentAction: 'report_to_user',
+        retryable: false,
+        details: { runId: finalRun.id, gateId: originalGateId },
+    });
+    return errorEnvelope('submit_gate', finalRun.id, finalRun.version, err, err.message, finalRun.run_phase);
+}
 export async function submitHumanResponse(store, definition, options) {
     // 1. Load run.
     let run;
@@ -2963,13 +3236,16 @@ export async function submitHumanResponse(store, definition, options) {
             });
         return errorEnvelope('submit_gate', options.runId, 0, e);
     }
+    // issue #291: injectable clock, hoisted here so BOTH the migrated and legacy paths below use
+    // the SAME instant for their expiry checks.
+    const now = options.now ?? new Date();
     // issue #279 (increment 2, PR-D, Deliverable 1b): the migrated path — the four legacy
     // verify-arms below (1a-4) become settle_gate's OWN predicate arms; this branch skips them
     // entirely and settles atomically against FRESH state via the store's own settleStep. Dormancy:
     // an undeclaring store falls through to the byte-identical legacy path below (I16/#169
     // fail-closed dormancy).
     if (store.settleStep !== undefined) {
-        const respondedAt = new Date();
+        const respondedAt = now;
         // Evidence rule (design record §6 lens-3 S2): built from the PRE-READ `pending_gate` IFF it
         // matches options.gateId — else `[]` (the arm can never APPLY against a non-matching fresh
         // read either, so an empty evidence array is inert there; a matching pre-read is guaranteed
@@ -2989,7 +3265,9 @@ export async function submitHumanResponse(store, definition, options) {
         };
         let result;
         try {
-            result = await store.settleStep(options.runId, delta, definition);
+            // issue #291 ([F3]): the injectable `now` reaches applySettleGate's write-free
+            // gate_expired_pending arm through this SAME options.now plumbing.
+            result = await store.settleStep(options.runId, delta, definition, { now });
         }
         catch (err) {
             // Thrown infra errors keep the SAME shape as the legacy path's own final-persist catch,
@@ -3006,6 +3284,34 @@ export async function submitHumanResponse(store, definition, options) {
         }
         if (!result.applied) {
             switch (result.reason) {
+                case 'gate_expired_pending': {
+                    // issue #291 ([F3] shape c): the live gate has already expired unresolved — issue the
+                    // caller-composed expire_gate settleStep ([F1]'s arms make this idempotent even under a
+                    // race with another enactment point) and compose the honest late-response envelope from
+                    // whatever the enactment result actually committed.
+                    const overdueMs = run.pending_gate?.expires_at !== undefined
+                        ? now.getTime() - new Date(run.pending_gate.expires_at).getTime()
+                        : 0;
+                    const expireDelta = { kind: 'expire_gate', gateId: options.gateId };
+                    let expireResult;
+                    try {
+                        expireResult = await store.settleStep(options.runId, expireDelta, definition, {
+                            now,
+                        });
+                    }
+                    catch (err) {
+                        const e = err instanceof WorkflowError
+                            ? err
+                            : new WorkflowError("Failed to enact the gate's expiry", {
+                                code: 'ENGINE_STORE_FAILED',
+                                category: 'ENGINE',
+                                agentAction: 'stop',
+                                retryable: false,
+                            });
+                        return errorEnvelope(run.pending_gate?.step_name ?? 'submit_gate', options.runId, result.run.version, e, "Failed to enact the gate's expiry.", result.run.run_phase);
+                    }
+                    return composeExpiredGateEnvelope(store, definition, options.registry, options.gateId, options.choice, overdueMs, expireResult);
+                }
                 case 'already_settled': {
                     // Calm ok envelope stating the resolution already committed (same choice) — never
                     // report_to_user. Drain: on already_settled ∧ pending ledger entries non-empty — hand-
@@ -3213,6 +3519,44 @@ export async function submitHumanResponse(store, definition, options) {
             retryable: false,
         }), `Gate ID mismatch on run '${options.runId}'.`);
     }
+    // 3.5. issue #291 ([F4] legacy-store expiry — the ONE enactment point F4 explicitly gives a
+    // legacy-CAS fallback, since it already owns one): the gate has expired AND has an enactable
+    // disposition (on_expiry frozen — a finding-only gate, expires_at with no on_expiry, is
+    // excluded exactly like applySettleGate's own F3 gating, so a finding-only gate's human
+    // response resolves normally below, however overdue). Enacted via the SAME pure
+    // `applySettlement` transform this store's declaring siblings use through `settleStep` — this
+    // store has no `settleStep` of its own, so the result is persisted through the version-CAS
+    // `store.update()` this legacy path already owns. A CAS-mismatch (a genuine race) surfaces as
+    // an honest error, matching this path's existing no-retry risk profile everywhere else.
+    if (run.pending_gate.expires_at !== undefined &&
+        run.pending_gate.on_expiry !== undefined &&
+        now.getTime() >= new Date(run.pending_gate.expires_at).getTime()) {
+        const overdueMs = now.getTime() - new Date(run.pending_gate.expires_at).getTime();
+        const expireOutcome = applySettlement(run, { kind: 'expire_gate', gateId: options.gateId }, definition, { now });
+        if (!expireOutcome.applied) {
+            // In-contract for this snapshot-based path: the local `run` might already reflect a prior
+            // enactment (e.g. a same-process retry) — already_settled composes the honest envelope the
+            // same way the migrated path's race leg does, reading disposition off `expireOutcome.run`
+            // (the very snapshot the refusal matched against).
+            return composeExpiredGateEnvelope(store, definition, options.registry, options.gateId, options.choice, overdueMs, expireOutcome);
+        }
+        let persistedExpiry;
+        try {
+            persistedExpiry = await store.update(expireOutcome.run);
+        }
+        catch (err) {
+            const e = err instanceof WorkflowError
+                ? err
+                : new WorkflowError("Failed to persist the gate's expiry", {
+                    code: 'ENGINE_STORE_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'stop',
+                    retryable: false,
+                });
+            return errorEnvelope(run.pending_gate.step_name, options.runId, run.version, e, "Failed to enact the gate's expiry.", run.run_phase);
+        }
+        return composeExpiredGateEnvelope(store, definition, options.registry, options.gateId, options.choice, overdueMs, { ...expireOutcome, run: persistedExpiry });
+    }
     // 4. Validate choice.
     if (!run.pending_gate.choices.includes(options.choice)) {
         const expected = run.pending_gate.choices.join(', ');
@@ -3475,8 +3819,10 @@ async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
     // settlement.ts's selectFinalizers, shared with `mintFresh` — this call passes the SAME inputs
     // the inline loop used to compute over, so the returned name list is byte-identical to what
     // `[...groupA, ...groupB]` produced before the extraction.
+    // issue #302 (chokepoint 2 of 2): derive the full effective trigger set from sealDraft — the
+    // legacy seal path for a non-declaring external store (the dormancy fallback).
     const settled = new Set([...sealDraft.completed_steps, ...sealDraft.failed_steps]);
-    const selected = selectFinalizers(definition, settled, outcome);
+    const selected = selectFinalizers(definition, settled, deriveEffectiveTriggers(outcome, sealDraft));
     let record = sealDraft;
     for (const name of selected) {
         const step = definition.steps[name];