@sema-agent/core 7.6.3 → 7.7.0

package/dist/core/checkpoint-store.d.ts

@@ -1,3 +1,5 @@
+import type { GateOutcome } from "./gate-outcome.js";
+import { type ExecutionOutcomeRecordWord } from "./checkpoint-execution-record.js";
 import type { CheckpointPause } from "./pause-registry.js";
 import type { SystemInjectionPriority } from "./task-notification.js";
 import { type QuestionAnswer } from "./ask-question.js";
@@ -1062,7 +1064,7 @@ export interface CheckpointState {
     activeWorktree?: ActiveWorktreeSession;
     /**
      * Parent effective-policy inheritance (tighten-only): the durable projection of the run's
-     * {@link import("./runner/prepare-task.js").InheritedGate}. Only the serializable DATA half persists —
+     * {@link import("./runner/contracts.js").InheritedGate}. Only the serializable DATA half persists —
      * `ancestorRules` (each ancestor's session-rule snapshot: sessionId/principal/rev/rules, re-compiled on
      * resume against the resumed leg's env) and `shellGate` (the chain's max-rank shell doctrine). The OPAQUE
      * half (`parentConstraints` — live ToolPolicy/onAsk closures) CANNOT persist; `requiresParentConstraint`
@@ -1202,7 +1204,7 @@ export interface CheckpointState {
     /**
      * #281 件B follow-up — `true` iff the suspended leg ran as a DELEGATED CHILD (the trusted
      * `RunInternals.isDelegatedChild` fact, read off the leg's own minted
-     * {@link import("./runner/prepare-task.js").Prepared.hookIdentity} so a re-suspend chain carries it
+     * {@link import("./runner/contracts.js").Prepared.hookIdentity} so a re-suspend chain carries it
      * forward). Without it a deps-only resume (`resume(token, outcome, config)` — no trusted internals
      * re-supplied) re-minted the resumed leg's identity with `isDelegatedChild: false`, so the
      * delegation-lifecycle observer's emission gate stayed shut and the resumed leg emitted NEITHER
@@ -1743,6 +1745,26 @@ export interface CheckpointRow {
         scope: string;
         ttlMs?: number;
     };
+    /**
+     * @contract checkpoint.execution_outcome — the settlement record of how the DECIDED action was
+     * finally disposed on the resumed leg: the {@link GateOutcome} the resumed call's `tool_end` frame
+     * carried (an executed allow, a person's refusal delivered, or a post-CAS belt's veto of a person's
+     * yes), written by {@link CheckpointStore.recordExecutionOutcome} exactly once per row, on every
+     * resolution (an `allowed` disposition is recorded too — the column's absence has ONE meaning:
+     * the execution outcome is not known, never "it was allowed"). Independent of
+     * {@link resolvedOutcome}, which stays the immutable record of the DECISION: a row can read
+     * `resolvedOutcome.gateOutcome.disposition.kind === "allowed"` beside
+     * `executionOutcome.disposition = { kind: "denied", deniedBy: "policy" }` — the person approved,
+     * the deployment's belt refused the edited call — and a reader rebuilding the run from the row
+     * sees both facts instead of the pre-execution one alone. The record is physically immutable:
+     * a second write of a different record is a conflict, never an overwrite, and a row carrying one
+     * cannot be {@link CheckpointStore.reopen | reopened} (the action is settled; a reopen would
+     * re-run or re-decide work whose outcome is already on file). Read through
+     * `executionVerdict` (checkpoint-execution-record.ts). Present together with {@link executionAtMs}.
+     */
+    executionOutcome?: GateOutcome;
+    /** Epoch ms the store stamped {@link executionOutcome} at. Present iff `executionOutcome` is. */
+    executionAtMs?: number;
 }
 /**
  * design/80 assistant-scheduler seam #1: a LIGHTWEIGHT projection of one PENDING
@@ -1967,6 +1989,10 @@ export declare class CheckpointError extends Error {
      *  checkpoint exists. Surfaced instead of silently treating the failed reopen as committed, so the
      *  caller's compensation path settles the token as terminally consumed. */
      | "checkpoint.reopen_failed"
+    /** {@link CheckpointStore.recordExecutionOutcome} met a row that already carries a DIFFERENT
+     *  execution record — see `ExecutionOutcomeConflictError` (checkpoint-execution-record.ts), the
+     *  in-tree form of this code. Never a retry condition. */
+     | "checkpoint.execution_outcome_conflict"
     /** design/80 D-A: {@link CheckpointStore.setPendingSteer} was handed `text` containing a
      *  `</system-reminder>` close tag — it would escape the model-facing `<system-reminder>` wrapper a
      *  trusted steer rides on resume. Rejected fail-closed so a dirty steer NEVER enters {@link CheckpointState}
@@ -2093,13 +2119,11 @@ export declare class CheckpointError extends Error {
          *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
          *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
          *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
-         *     (retryable on an org-wired worker), `"origin_missing"` (a pending approval row minted
-         *     before the ask's origin was persisted on the park — terminal for the row's bytes; the host
-         *     decides the orphaned card itself, no worker version redeems it).
+         *     (retryable on an org-wired worker).
          *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
          *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
          *     current bytes — no worker version redeems a damaged row). */
-        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "origin_missing" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
     } | undefined;
     constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"
     /** `runner.resume` was handed an {@link ResumeOutcome} whose `gate` arm does not match the
@@ -2151,6 +2175,10 @@ export declare class CheckpointError extends Error {
      *  checkpoint exists. Surfaced instead of silently treating the failed reopen as committed, so the
      *  caller's compensation path settles the token as terminally consumed. */
      | "checkpoint.reopen_failed"
+    /** {@link CheckpointStore.recordExecutionOutcome} met a row that already carries a DIFFERENT
+     *  execution record — see `ExecutionOutcomeConflictError` (checkpoint-execution-record.ts), the
+     *  in-tree form of this code. Never a retry condition. */
+     | "checkpoint.execution_outcome_conflict"
     /** design/80 D-A: {@link CheckpointStore.setPendingSteer} was handed `text` containing a
      *  `</system-reminder>` close tag — it would escape the model-facing `<system-reminder>` wrapper a
      *  trusted steer rides on resume. Rejected fail-closed so a dirty steer NEVER enters {@link CheckpointState}
@@ -2277,13 +2305,11 @@ export declare class CheckpointError extends Error {
          *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
          *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
          *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
-         *     (retryable on an org-wired worker), `"origin_missing"` (a pending approval row minted
-         *     before the ask's origin was persisted on the park — terminal for the row's bytes; the host
-         *     decides the orphaned card itself, no worker version redeems it).
+         *     (retryable on an org-wired worker).
          *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
          *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
          *     current bytes — no worker version redeems a damaged row). */
-        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "origin_missing" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
     } | undefined);
 }
 /**
@@ -2456,6 +2482,20 @@ export interface CheckpointStore {
         reopen: boolean;
         validatingLease?: boolean;
     };
+    /**
+     * The EXECUTION-OUTCOME declaration — REQUIRED, and required to be exactly `{ outcome: true }`: the
+     * store promises that {@link recordExecutionOutcome} is the real CAS this contract describes (the
+     * predicate, the four words, the conflict throw) and that {@link reopen} honours the record. Same
+     * "declaration, never duck-typing" posture as the three optional axes above, but not optional: the
+     * durable resume lane records how every decided action was disposed, and a store that cannot keep
+     * that record would leave every resolved row it holds silently unreadable on that axis. A store
+     * without the declaration is refused at the FIRST read of the store seat
+     * ({@link resolveCheckpointStore}, code `config.invalid_checkpoint_store`) — a JavaScript caller that
+     * satisfies no type is told at prepare what the type would have told it.
+     */
+    readonly execution: {
+        readonly outcome: true;
+    };
     /** Create-once. Throws {@link CheckpointError} `already_exists` on a token collision (never a silent
      *  overwrite — a reused token would clobber a live suspension). */
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
@@ -2505,8 +2545,35 @@ export interface CheckpointStore {
      * `tool_unavailable` (P-7: the approved tool vanished, the action may now be invalid → a human re-decides,
      * so a FRESH decision is allowed). The store RECORDS the reason on the row as {@link Checkpoint.reopenReason}
      * and PRESERVES the persisted winner across the reopen (never clears it).
+     *
+     * **A row that carries an execution record is NOT reopenable** (`… AND execution_outcome IS NULL` in the
+     * WHERE; `checkpointExecutionRecorded` is the shared predicate): the decided action's disposition is on
+     * file — see {@link CheckpointRow.executionOutcome} — and reopening it would either re-run an action that
+     * already ran or re-decide one already refused. Answers `false` like every other predicate miss; the
+     * reasons and the winner are untouched.
      */
     reopen?(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
+    /**
+     * Record how the DECIDED action was finally disposed on the resumed leg — the {@link GateOutcome} its
+     * `tool_end` frame carried (see {@link CheckpointRow.executionOutcome} for what the record means and why
+     * it is a column of its own beside the immutable decision). REQUIRED (declared by {@link execution}).
+     *
+     * The CAS: `UPDATE … SET execution_outcome=?, execution_at_ms=? WHERE token=? AND scope=? AND
+     * status='resolved' AND execution_outcome IS NULL`. The answer is a word of the closed
+     * `ExecutionOutcomeRecordWord` set — `recorded` (the CAS won), `already_recorded` (the row already
+     * carries an EQUAL record: a retry, idempotent), `not_resolved` (pending/expired: no decision to be the
+     * outcome of), `absent` (no such row in this scope). A row carrying a DIFFERENT record throws
+     * `ExecutionOutcomeConflictError` (`checkpoint.execution_outcome_conflict`) — the record is immutable
+     * and two accounts of one execution are an engine defect, never a store overwrite. Equality is
+     * structural over the record's JSON (key order and freezing are not part of the value —
+     * `sameExecutionRecord`); every backend takes its disposition from `executionRecordDisposition`
+     * (checkpoint-execution-record.ts) and keeps only the commit half itself.
+     *
+     * Never touches `status`, `rev`, `resolvedOutcome` or `reopenReason`: the record is a fact about the
+     * execution, not a transition of the decision. Its one effect on the row's other verbs is that
+     * {@link reopen} refuses a recorded row.
+     */
+    recordExecutionOutcome(token: CheckpointToken, scope: string, gate: GateOutcome): Promise<ExecutionOutcomeRecordWord>;
     /**
      * design/80 D-A: park a durable mid-task STEER on a DURABLY-SUSPENDED task's checkpoint. CAS-style update
      * `SET state.pendingSteerQueue=? WHERE token=? AND scope=? AND status='pending'`: returns `true` iff the
@@ -2692,6 +2759,12 @@ export declare function resolveCheckpointStore(spec: {
 }, deps: {
     checkpointStore?: CheckpointStore;
 }): CheckpointStore | undefined;
+/** The ONE refusal of a store seat whose {@link CheckpointStore} does not declare `execution = { outcome: true }`
+ *  (named by seat and by the store's constructor when it has one). Same door, same code, as the retired-`null`
+ *  refusal above: a configuration the run cannot honour is refused at the first read, never carried. */
+export declare function checkpointStoreExecutionUndeclared(seat: "TaskSpec.checkpointStore" | "RunnerDeps.checkpointStore", store: object): Error & {
+    code: "config.invalid_checkpoint_store";
+};
 /** The ONE refusal of the retired `checkpointStore: null` spelling (the resolver and the workflow baseline overlay both throw it). */
 export declare function retiredCheckpointStoreNull(): Error & {
     code: "config.invalid_checkpoint_store";
@@ -2803,6 +2876,10 @@ export declare class InMemoryCheckpointStore implements CheckpointStore {
     readonly redecision: {
         readonly reopen: true;
     };
+    /** The execution-outcome record verb below is the contract's CAS, and `reopen` honours the record. */
+    readonly execution: {
+        readonly outcome: true;
+    };
     private cps;
     private fault;
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
@@ -2855,6 +2932,7 @@ export declare class InMemoryCheckpointStore implements CheckpointStore {
      *  atomic unit this method exists to provide. (A wrapper that OMITS the member opts out
      *  cleanly: the consumer's presence probe then keeps the two-step path, hooks intact.) */
     claimTerminal(token: CheckpointToken, scope: string, intent: TerminalClaimIntent): Promise<TerminalClaimOutcome>;
+    recordExecutionOutcome(token: CheckpointToken, scope: string, gate: GateOutcome): Promise<ExecutionOutcomeRecordWord>;
     reopen(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
     setPendingSteer(token: CheckpointToken, scope: string, steer: PendingSteerInput): Promise<boolean>;
     expire(token: CheckpointToken, scope: string): Promise<boolean>;

package/dist/core/checkpoint-store.js

@@ -4,6 +4,7 @@ import { PROBE_CAUSE_PATH_MAX, inlineUntrusted, sanitizeUntrustedText } from "./
 import { carriesBidiControls } from "./tool-policy.js";
 import { readDenialLimitFallback } from "./auto-mode.js";
 import { isAskOrigin } from "./ask-origin.js";
+import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "./checkpoint-execution-record.js";
 import { renderUntrustedCommandText, stripFormatCharacters } from "./permission-rule-model.js";
 import { redactSecrets } from "./untrusted-egress.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
@@ -367,7 +368,26 @@ export function resolveCheckpointStore(spec, deps) {
         throw retiredCheckpointStoreNull();
     if (spec.checkpointStore === "disabled")
         return undefined;
-    return spec.checkpointStore ?? deps.checkpointStore;
+    if (spec.checkpointStore !== undefined) {
+        if (spec.checkpointStore.execution?.outcome !== true)
+            throw checkpointStoreExecutionUndeclared("TaskSpec.checkpointStore", spec.checkpointStore);
+        return spec.checkpointStore;
+    }
+    if (deps.checkpointStore !== undefined && deps.checkpointStore.execution?.outcome !== true) {
+        throw checkpointStoreExecutionUndeclared("RunnerDeps.checkpointStore", deps.checkpointStore);
+    }
+    return deps.checkpointStore;
+}
+export function checkpointStoreExecutionUndeclared(seat, store) {
+    const ctor = store.constructor?.name;
+    const name = typeof ctor === "string" && ctor.length > 0 && ctor !== "Object" ? ` (${ctor})` : "";
+    const e = new Error(`${seat}: the wired CheckpointStore${name} does not declare \`execution = { outcome: true }\` — the execution-outcome ` +
+        "record (recordExecutionOutcome, and reopen refusing a recorded row) is a required member of the store contract; " +
+        "a store without it cannot record how a resumed approval was disposed, so the run is refused here rather than " +
+        "resolving rows no reader can settle. Implement the verb and add the declaration (the in-tree stores and the " +
+        "store-contract kit are the reference).");
+    e.code = "config.invalid_checkpoint_store";
+    return e;
 }
 export function retiredCheckpointStoreNull() {
     const e = new Error('TaskSpec.checkpointStore: null is not a value any more — write checkpointStore: "disabled" to run without a ' +
@@ -540,6 +560,7 @@ export class InMemoryCheckpointStore {
     durability = "process-local";
     fidelity = "structured-clone";
     redecision = { reopen: true };
+    execution = { outcome: true };
     cps = new Map();
     fault = null;
     async put(token, cp) {
@@ -618,9 +639,21 @@ export class InMemoryCheckpointStore {
         }
         return out;
     }
+    async recordExecutionOutcome(token, scope, gate) {
+        const cp = this.cps.get(token);
+        const disposition = executionRecordDisposition(cp, scope, gate);
+        if (disposition === "conflict")
+            throw new ExecutionOutcomeConflictError(cp.executionOutcome, gate);
+        if (disposition !== "commit")
+            return disposition;
+        const record = structuredClone(gate);
+        cp.executionOutcome = record;
+        cp.executionAtMs = Date.now();
+        return "recorded";
+    }
     async reopen(token, scope, reason) {
         const cp = this.cps.get(token);
-        if (!checkpointRowMatches(cp, scope, "resolved")) {
+        if (!checkpointRowMatches(cp, scope, "resolved") || checkpointExecutionRecorded(cp)) {
             return false;
         }
         cp.status = "pending";

package/dist/core/engine-notice.d.ts

@@ -211,6 +211,17 @@ export interface EngineNotice {
      *    (whoever answered the card is the one entitled to hear the answer ran nothing); a host may
      *    forward it on its own wire.
      *
+     *  - `"checkpoint.execution_outcome_unrecorded"` — the resumed leg's pending-call resolver disposed
+     *    the decided action (executed it, delivered the refusal, or vetoed the person's yes) and filed
+     *    the frame's record through `CheckpointStore.recordExecutionOutcome`, and the store answered
+     *    `not_resolved` or `absent` — the row was reopened, expired or removed under the leg by another
+     *    actor, so the row now reads `unknown` on its execution axis (`executionVerdict`). The
+     *    execution result is NOT changed by the answer (the record is an account of what ran, never a
+     *    gate on it); the notice is the loud half. Once per such resolution;
+     *    `detail: { sessionId, runId, scope, checkpointId?, word }` (`word` = the store's answer; the
+     *    secret token never rides a notice). A DIFFERENT record already on file is not this notice — it
+     *    is the `checkpoint.execution_outcome_conflict` throw (an engine defect, propagated).
+     *
      *  - `"classifier.denial_limit"` (#548, CC 2.1.250 `FO`/"too many classifier denials in headless
      *    mode") — the auto-mode classifier's DENIAL LIMIT was reached (3 consecutive blocks, or 20 in the
      *    run; `RunnerDeps.autoMode.denialLimit`) and the fallback ask it turns into had NO approver to go

package/dist/core/governance-codes.d.ts

@@ -103,7 +103,7 @@ export type NoticeAudience = "user" | "operator";
  * src/ for notice mint shapes and names any code that is minted but unregistered, or registered but
  * no longer minted.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "delegation.transcript_integrity", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "route.fallback_to_primary", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "tool_result.offload_put_failed"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "route.fallback_to_primary", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "tool_result.offload_put_failed"];
 /** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */

package/dist/core/governance-codes.js

@@ -108,6 +108,7 @@ export const ENGINE_NOTICE_CODES = [
     "peer.held_settled",
     "peer.idle_subscription",
     "classifier.denial_limit",
+    "checkpoint.execution_outcome_unrecorded",
     "delegation.transcript_integrity",
     "mcp.revocation_probe_failed",
     "workflow.governance_key_stripped",
@@ -169,6 +170,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "peer.held_settled": "user",
     "peer.idle_subscription": "user",
     "delegation.transcript_integrity": "operator",
+    "checkpoint.execution_outcome_unrecorded": "operator",
     "mcp.revocation_probe_failed": "operator",
     "workflow.governance_key_stripped": "operator",
     "workflow.agent_option_ignored": "operator",

package/dist/core/runner/clock-and-limits.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The run loop's CLOCK and LIMIT machinery — the pieces that turn a budget, a deadline or a ceiling into
+ * something a lane can act on, shared by the turn boundary, the run body and the end-of-task lane:
+ *  · the limit-approach frames (budget-measured, advisory) and the turn-cap read;
+ *  · the governance-read budget against the environment's suspend deadline, the chunked absolute-deadline
+ *    race that enforces it, and the never-abandoned ledger charge with its slow-settle disclosure;
+ *  · the typed terminal for an external stop cause that could not be suspended durably;
+ *  · the once-per-task disclosure of an auto-compaction trigger that cannot be evaluated (a WeakSet keyed
+ *    on the task's `Prepared`, so the latch dies with the task and never touches the contract surface);
+ *  · the hard walltime backstop timer, chunked past the largest delay a timer honours.
+ *
+ * Every clock read is `Date.now()` or a timer; every host read is through the arguments a caller hands in.
+ * Layer-1 machinery rather than a driven lane — initial-run-state.ts says why no run-loop machinery module
+ * wears a family prefix.
+ */
+import { type AgentHarness } from "../../internal/harness.js";
+import type { PlatformLimitReason } from "../checkpoint-store.js";
+import type { TaskSpec } from "../types.js";
+import type { Prepared } from "./contracts.js";
+/**
+ * design/164 — the LIMIT-APPROACH frames, the successor to the retired deadline-nudge family. Two facts
+ * make them a different mechanism, not a rename:
+ *  - they are measured in BUDGET (the tightest armed axis's fill ratio), not in wall-clock, so they need
+ *    no throughput estimate and cannot mis-fire on a starved event loop;
+ *  - they are ADVISORY. Neither frame stops anything; the run ends when a ceiling is actually crossed.
+ *
+ * Rendered by {@link limitApproachFrames}; registered in the prompt-assembly event registry under
+ * `limit_approach_converge` / `limit_approach_deliver`.
+ */
+export declare const LIMIT_APPROACH_DEFAULT_THRESHOLDS: readonly [number, number];
+/** The output-token figure the pre-call worst-case assumes when the model declares no cap of its own.
+ *  Shared by the $ and token arms so the two gates cannot disagree about the same hypothetical call. */
+export declare const DEFAULT_PRECALL_OUTPUT_TOKENS = 4096;
+/** The two frame bodies, indexed by how many have already been sent (0 → converge, 1 → deliver now). */
+export declare function limitApproachFrames(index: 0 | 1, axis: string, percent: number, mark: string | undefined): string;
+/**
+ * Resolve the effective turn cap. `undefined` = no turn cap; `0` (explicit) = unbounded.
+ *
+ * design/164: this is now a pure read of what the caller wrote. The two clauses it used to carry —
+ * "a wall-clock bound was set, so drop the turn cap" and "neither was set, so apply the engine's
+ * safety net" — are both gone: the axes no longer interact (each binds on its own), and there is no
+ * engine-side net to apply. A task with no `maxTurns` has no turn ceiling.
+ */
+export declare function resolveMaxTurns(limits?: {
+    maxTurns?: number;
+}): number | undefined;
+/**
+ * How long past the environment's suspend deadline the turn-boundary lane will keep waiting for the
+ * usage ledger's READ.
+ *
+ * The precedence ruling (usage_window > env_lifetime) means the ledger must be read BEFORE the env
+ * cause can be adopted — you cannot rank a cause you have not read. But that read is store I/O with no
+ * bound of its own, and past this instant every millisecond it spends is spent out of the margin that
+ * exists to mint the env checkpoint. A stalled ledger must not cost a deployment the checkpoint it
+ * could still have had, so the read runs against an ABSOLUTE deadline (`envLifetimeSuspendAt + this`)
+ * and a run that gets no answer by then stops for the cause it can still prove.
+ *
+ * 5s against the 60s suspend margin: two orders of magnitude above any healthy ledger read (in-memory
+ * and file stores answer in ms; a remote one in tens of ms), and it still leaves 55s — more than the
+ * margin was sized for — to pause the workspace, mint the checkpoint and commit it. Not a knob: it is a
+ * fraction of an engine constant, and a deployment that wants a wider band declares a shorter lifetime.
+ *
+ * ABSOLUTE, never a fresh per-boundary allowance: a boundary that finds the deadline one millisecond
+ * away must not hand a stalled ledger the whole margin, and a boundary that is already overdue must get
+ * LESS than the budget, not the same. {@link raceUntilDeadline} is what keeps that true for a deadline
+ * of any distance, without an unrepresentable timer.
+ */
+export declare const ENV_DUE_GOVERNANCE_READ_BUDGET_MS = 5000;
+export declare const GOVERNANCE_READ_STALLED: unique symbol;
+/** Await a ledger charge, firing `onSlow` ONCE if it has not settled after
+ *  {@link CHARGE_SETTLE_DISCLOSE_MS}. The charge itself is always awaited to completion. */
+export declare function awaitChargeWithSlowDisclosure<T>(charge: Promise<T>, onSlow: () => void, discloseAfterMs?: number): Promise<T>;
+/**
+ * Await `p` until the absolute epoch `deadline`, then give up with {@link GOVERNANCE_READ_STALLED}.
+ *
+ * Chunked, and deliberately so: the deadline is derived from a caller-declared environment lifetime, so
+ * the distance to it can exceed {@link MAX_TIMER_DELAY_MS} — a single timer armed for that distance
+ * would fire at once and abandon a perfectly healthy read. Each chunk re-reads the wall clock, so the
+ * decision is always made against the deadline itself rather than against an allowance computed once.
+ *
+ * Exported for its own unit pin (the same posture as the brain-call guardrail primitive): the
+ * behaviors below are clock behaviors, and only a virtual clock can assert them without spending the
+ * wall-clock time they describe. Not re-exported from the package index.
+ *
+ * An already-overdue deadline still gets ONE zero-delay pass: a promise that is settled (or settles in a
+ * microtask, which is every in-process store) must be allowed to win, because giving up on an answer we
+ * already hold would be a fabricated stall. The second pass is what makes the loop terminate.
+ */
+export declare function raceUntilDeadline<T>(p: Promise<T>, deadline: number): Promise<T | typeof GOVERNANCE_READ_STALLED>;
+/**
+ * design/164 件四/件五 — the TYPED terminal for an external stop cause that could NOT be suspended durably.
+ * Carried on `rs.limits.platformTerminal` and adopted as the run's `threw`, so the caller reads the cause
+ * on `TaskResult.errorCode` (`errorCodeOf` lifts `.code`) instead of the anonymous error an abort produces.
+ * `retryAfterMs` rides the error object because a wait hint has no `TaskResult` seat — a host reads it from
+ * the `RunnerDeps.onError` sink this is also delivered to.
+ */
+export declare function platformLimitTerminal(reason: PlatformLimitReason, retryAfterMs: number | undefined, moment?: "entry" | "turn_boundary" | "resume"): Error & {
+    code: string;
+    retryAfterMs?: number;
+};
+export declare function discloseUnevaluableWindow(u: {
+    estTokens: number;
+    windowField: string;
+    windowValue?: number;
+    modelId?: string;
+}, prepared: Prepared, tracer: TaskSpec["tracer"], taskId: string, onError: ((err: unknown, context: {
+    phase: "config";
+    sessionId: string;
+}) => void) | undefined): void;
+/** 1.296 件2a — report the hard-abort timer's lateness on `task.end` only above this bar: sub-5s
+ *  jitter is ordinary scheduling noise (GC pauses, sync work) and would only add trace lint. */
+export declare const TIMER_LATENESS_REPORT_MS = 5000;
+export declare function startTimeout(harness: AgentHarness, abortController: AbortController, remainingMs?: number, softSuspendable?: boolean): {
+    fired: boolean;
+    latenessMs?: number;
+    clear: () => void;
+};

package/dist/core/runner/clock-and-limits.js

@@ -0,0 +1,118 @@
+import {} from "../../internal/harness.js";
+import { openSystemReminder } from "../reminder-mint.js";
+import { emitTrace } from "../trace.js";
+export const LIMIT_APPROACH_DEFAULT_THRESHOLDS = [0.8, 0.95];
+export const DEFAULT_PRECALL_OUTPUT_TOKENS = 4096;
+export function limitApproachFrames(index, axis, percent, mark) {
+    return index === 0
+        ? `${openSystemReminder(mark)}[limit approach] This task has used about ${percent}% of its ${axis}. ` +
+            `Start converging: finish the step you are on, drop work that is not required for the deliverable, and ` +
+            `avoid starting anything you cannot complete within what is left.</system-reminder>`
+        : `${openSystemReminder(mark)}[limit approach] About ${percent}% of the ${axis} is gone. Deliver now: ` +
+            `stop exploring, write up what you have — including what is incomplete and what you would do next — ` +
+            `and end the task. Work that is not reported before the allowance runs out is lost.</system-reminder>`;
+}
+export function resolveMaxTurns(limits) {
+    return limits?.maxTurns;
+}
+export const ENV_DUE_GOVERNANCE_READ_BUDGET_MS = 5_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const DEADLINE_TICK = Symbol("deadline-tick");
+export const GOVERNANCE_READ_STALLED = Symbol("governance-read-stalled");
+const CHARGE_SETTLE_DISCLOSE_MS = 10_000;
+export async function awaitChargeWithSlowDisclosure(charge, onSlow, discloseAfterMs = CHARGE_SETTLE_DISCLOSE_MS) {
+    let timer = setTimeout(() => {
+        timer = undefined;
+        try {
+            onSlow();
+        }
+        catch {
+        }
+    }, discloseAfterMs);
+    try {
+        return await charge;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+export async function raceUntilDeadline(p, deadline) {
+    for (let firstPass = true;; firstPass = false) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0 && !firstPass)
+            return GOVERNANCE_READ_STALLED;
+        let timer;
+        const tick = new Promise((res) => {
+            timer = setTimeout(() => res(DEADLINE_TICK), Math.max(0, Math.min(remaining, MAX_TIMER_DELAY_MS)));
+        });
+        const out = await Promise.race([p, tick]).finally(() => clearTimeout(timer));
+        if (out !== DEADLINE_TICK)
+            return out;
+    }
+}
+export function platformLimitTerminal(reason, retryAfterMs, moment = "turn_boundary") {
+    const message = moment === "entry"
+        ? `a deployment usage window is exhausted (RunnerDeps.usageWindows), so the task was refused before its first model call — nothing ran and nothing was spent. There is no checkpoint to suspend into at this point, so the caller re-submits after the window frees, in ${String(retryAfterMs ?? 0)}ms.`
+        : moment === "resume"
+            ? `a deployment usage window is exhausted (RunnerDeps.usageWindows), so the resumed leg was stopped BEFORE its first model call — nothing was delivered or executed on this leg. The window frees in ${String(retryAfterMs ?? 0)}ms.`
+            : reason === "env_lifetime"
+                ? "the execution environment's declared lifetime is expiring and the run could not be suspended durably (not eligible, or the suspend was refused — see remoteEnvFailures / onError). It was stopped at a clean turn boundary instead of being killed mid-turn when the platform reclaims the environment."
+                : `a deployment usage window is exhausted (RunnerDeps.usageWindows) and the run could not be suspended durably, so it was stopped at a clean turn boundary. The window frees in ${String(retryAfterMs ?? 0)}ms.`;
+    const e = new Error(message);
+    e.code = reason === "env_lifetime" ? "env.lifetime_expired" : "usage.window_exhausted";
+    if (retryAfterMs !== undefined)
+        e.retryAfterMs = retryAfterMs;
+    return e;
+}
+const disclosedUnevaluableWindow = new WeakSet();
+export function discloseUnevaluableWindow(u, prepared, tracer, taskId, onError) {
+    if (disclosedUnevaluableWindow.has(prepared))
+        return;
+    disclosedUnevaluableWindow.add(prepared);
+    emitTrace(tracer, () => ({ kind: "compaction.unevaluable", version: 1, taskId, estTokens: u.estTokens, ts: Date.now() }));
+    const modelClause = u.modelId !== undefined ? ` "${u.modelId}"` : "";
+    const cause = u.windowValue !== undefined
+        ? `its \`${u.windowField}\` is ${u.windowValue}, which is not a positive number of tokens — that field takes precedence over the ` +
+            `others, so fixing or removing it is what restores the threshold`
+        : `it declares no context window at all (\`autoCompactTokens\` / \`contextTokens\` / \`contextWindow\` are all absent) — declare one to restore the threshold`;
+    try {
+        onError?.(new Error(`auto-compaction cannot run for model${modelClause}: ${cause}. Until then there is no threshold to compare against, so the ` +
+            `context will grow until the provider refuses the request. The conversation is already about ${u.estTokens} estimated tokens.`), { phase: "config", sessionId: prepared.sessionId });
+    }
+    catch {
+    }
+}
+const WALLTIME_SUSPEND_GRACE_SEC = 120;
+export const TIMER_LATENESS_REPORT_MS = 5_000;
+export function startTimeout(harness, abortController, remainingMs, softSuspendable = false) {
+    const state = { fired: false, clear: () => { } };
+    if (remainingMs !== undefined) {
+        const hardMs = Math.max(0, remainingMs + (softSuspendable ? WALLTIME_SUSPEND_GRACE_SEC * 1000 : 0));
+        const scheduledAtMs = Date.now() + hardMs;
+        let leftMs = hardMs;
+        let timer;
+        const armChunk = () => {
+            const chunk = Math.max(0, Math.min(leftMs, MAX_TIMER_DELAY_MS));
+            timer = setTimeout(() => {
+                leftMs -= chunk;
+                if (leftMs > 0) {
+                    armChunk();
+                    return;
+                }
+                fireHardAbort();
+            }, chunk);
+        };
+        const fireHardAbort = () => {
+            if (state.fired)
+                return;
+            state.fired = true;
+            state.latenessMs = Math.max(0, Date.now() - scheduledAtMs);
+            abortController.abort();
+            void harness.abort();
+        };
+        armChunk();
+        state.clear = () => clearTimeout(timer);
+    }
+    return state;
+}

package/dist/core/runner/contracts.d.ts

@@ -27,6 +27,7 @@ import type { AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import type { AutoModeDecider, AutoModeDenialTracker } from "../auto-mode.js";
 import type { CacheBreakDetector, ToolFingerprintInput } from "../cache-break-detector.js";
 import type { ActorAssertion, Checkpoint, CheckpointState, CheckpointStore, CheckpointToken, PendingSteerEntry, PlatformLimitReason, ReopenReason, ResourceLedger, ResourceLimitReason, ResumeOutcome, SerializedCheckpointState } from "../checkpoint-store.js";
+import type { ExecutionOutcomeRecordWord } from "../checkpoint-execution-record.js";
 import type { ClearedProjectionLedger, ContextEditMachine, OccurrenceIndex } from "../context-edit.js";
 import type { HookInvocationIdentity, Hooks, OrgGateVerdict, PermissionDeniedPayload, PostToolBatchCall, PostToolBatchResult, ToolGateInput } from "../hooks.js";
 import type { MaterializedMcp } from "../mcp.js";
@@ -2196,6 +2197,15 @@ export interface ResumeRun {
      *  replay the persisted winner (a system retry of the approved action), while a `tool_unavailable` reopen
      *  lets a human re-decide with the tool present (a fresh decision is allowed — preserves P-7). */
     onEnvRestoreFailed?: (reason: ReopenReason) => Promise<void>;
+    /** The row's execution-record verb, bound to THIS resume's token and scope by `resumeStream` (the
+     *  same closure form as {@link onEnvRestoreFailed}, but REQUIRED: the store contract requires the
+     *  verb, so there is no store this seat could be absent for). The pending-call resolver calls it
+     *  exactly once per resolution, right after it emits the resolved call's `tool_end` frame, with the
+     *  {@link import("../gate-outcome.js").GateOutcome} that frame carried — every disposition, the
+     *  executed allow included (see `CheckpointRow.executionOutcome`: absence means unknown, never
+     *  allowed). The word it answers is read through `EXECUTION_RECORD_LEAVES_ROW_UNRECORDED`; a
+     *  conflict throw propagates (an engine defect, not a store condition). */
+    recordExecutionOutcome: (gate: import("../gate-outcome.js").GateOutcome) => Promise<ExecutionOutcomeRecordWord>;
     /** RB-471/FR-C1 — set in the run body right after `applyResumeDecision` completes: the negative-
      *  decision twin of `pendingActionStarted`. A reject/deny consumes its gate BY BEING DELIVERED, and
      *  this bit is the delivery fact — every throw-arm cause (prepare failure, `session_not_found`, a