@sema-agent/core 7.5.1 → 7.6.0

package/dist/core/runner/prepare-boundary-parks.d.ts

@@ -0,0 +1,102 @@
+/**
+ * design/390 §1.2 M19 (boundary parks) — prepareTask's three BOUNDARY-FAMILY park lanes, verbatim from the driver's
+ * gate-machinery block: the ONE resource mint (`mintResourceSuspend`) behind the task-axis `suspendForResource` (exposed
+ * under the caller's `resourceSuspend` opt-in) and the infrastructure `suspendForPlatformLimit` (exposed on durable infra
+ * alone), and the `plan_review` mint behind `suspendForReview` (exposed with a checkpoint store). Every mint reuses the
+ * suspend saga's serializer, commit saga, loop cap and env split — this phase adds no second copy of any of them. The
+ * interface is the dependency list the segment had implicitly (design/238 R-1); the three lanes used to be forward-declared
+ * `let`s at task scope, assigned inside the block, so the driver's Prepared could expose them — they are this phase's
+ * Result now, and the driver binds them as consts.
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the mints run at a turn boundary), so the
+ * phase adds no yield between the suspend saga before it and the park closure after it (design/390 §1.5). Read-stability
+ * of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * The lanes exist exactly when the saga does (the ask lane's presence law) — an absent saga answers three absent lanes,
+ * so the orchestrator grows no branch.
+ */
+import type { AgentHarness } from "../../internal/harness.js";
+import { type CheckpointStore } from "../checkpoint-store.js";
+import type { SessionStore } from "../session.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Prepared, SuspendSaga } from "./contracts.js";
+export interface PrepareBoundaryParksInput {
+    /** borrowed-readonly — the suspend saga's eight seats (the serializer, the commit saga, the loop cap, the env split, the
+     *  park-only handle, the in-flight spend), or undefined when the gate machinery is inactive (then all three lanes are
+     *  absent). Called at park time; never rebuilt here. */
+    saga: SuspendSaga | undefined;
+    /** borrowed-readonly — the REBOUND spec. Read: `resourceSuspend` (the slice scope/ttl/maxSlices), `retainBackgroundProcesses`
+     *  (the park-only sweep gate), `durableApproval` (the review pause's ttl), `principal` (the rows' identity record and
+     *  the review scope). Never mutated. */
+    spec: Pick<TaskSpec, "resourceSuspend" | "retainBackgroundProcesses" | "durableApproval" | "principal">;
+    /** borrowed-readonly — the leg's checkpoint store, or undefined (then the review lane is absent and the resource mint
+     *  answers false). */
+    checkpointStore: CheckpointStore | undefined;
+    /** borrowed-mutable — prepare's abort seat. `.signal` is read (a cancelling run mints nothing); `abort()` is called on
+     *  the review lane's commit (the review pause stops the run the human gate's way). */
+    abortController: {
+        readonly signal: AbortSignal;
+        abort(): void;
+    };
+    /** borrowed-mutable — the built harness. Writers here: `requestStopAfterTurn()` (the resource lanes' clean stop) and
+     *  `abort()` (the review lane's stop). */
+    harness: Pick<AgentHarness, "abort" | "requestStopAfterTurn">;
+    /** borrowed-readonly — the acquired session; only `getLeafId` is read (no committed leaf ⇒ no consistent resume point). */
+    session: Pick<Prepared["session"], "getLeafId">;
+    /** borrowed-readonly — the session store; only the optional `pin` is called (best-effort, after commit). */
+    sessions: Pick<SessionStore, "pin">;
+    /** borrowed-readonly — the acquired session id (the rows' session, the source attribution, every disclosure's tag). */
+    sessionId: string;
+    /** borrowed-readonly — the deployment's error face, as a Pick over the SAME `deps` object (receiver preserved for
+     *  `deps.onError?.()`): the suspendVM refusals, the skipped-review lines, the pin failures. */
+    deps: Pick<RunnerDeps, "onError">;
+    /** borrowed-readonly — the cross-slice ledger carried on the resumed checkpoint, or undefined on the first slice. */
+    priorLedger: Prepared["resourceLedger"];
+    /** borrowed-readonly — the resource-slice cap, or undefined (no slice ceiling). */
+    maxSlices: number | undefined;
+    /** borrowed-readonly — the restart-loop cap the review lane is bounded by. */
+    maxSuspends: number;
+    /** borrowed-readonly — the human total the first slice seeds the ledger from, or undefined. */
+    resourceTotal: {
+        totalBudgetMicroUsd?: number;
+        totalTokens?: number;
+    } | undefined;
+    /** borrowed-readonly — how many times this task already suspended (carried on the resumed checkpoint); a slice carries
+     *  it UNCHANGED. */
+    priorSuspendCount: number;
+    /** borrowed-readonly — the restart-loop chain base (resets after an approved execution); the review lane's count. */
+    suspendChainBase: () => number;
+    /** borrowed-readonly — the per-task human-review accumulator; snapshotted onto every row (never written here). */
+    humanReviewRef: Prepared["humanReviewRef"];
+    /** borrowed-readonly — the loop's live spend seat; `.get` is read at mint time for the review ledger. */
+    liveSpendRef: Prepared["liveSpendRef"];
+    /** borrowed-readonly — the injectable wall clock (the review pause's `suspendedAt`). */
+    now: () => number;
+    /** borrowed-readonly — the inherited-gate phase's three version-stamp predicates (face / F-012 / org admission). */
+    faceCheckpointState: () => boolean;
+    /** borrowed-readonly — see `faceCheckpointState`. */
+    f012CheckpointState: () => boolean;
+    /** borrowed-readonly — see `faceCheckpointState`. */
+    orgAdmissionCheckpointState: () => boolean;
+    /** borrowed-mutable — the run's committed-pause holder (`Prepared.pausedRef`). Writer here: the commit-side publication
+     *  of a committed resource / platform / plan-review checkpoint. */
+    pausedRef: Prepared["pausedRef"];
+    /** borrowed-mutable — the run-scoped remote-lifecycle failure log. Writer here: a refused `suspendVM` (`push`). */
+    remoteEnvFailures: Prepared["remoteEnvFailures"];
+    /** borrowed-readonly — the wiring-manifest phase's task-axis predicate (opt-in ∧ durable infra): exposes `suspendForResource`. */
+    resourceSuspendEligible: boolean;
+    /** borrowed-readonly — the wiring-manifest phase's durable-infra predicate: exposes `suspendForPlatformLimit`. */
+    durableSuspendInfraReady: boolean;
+    /** borrowed-readonly — the restore-incomplete adapter's missing members, or undefined (the review lane refuses loudly). */
+    incompleteSuspendAdapter: readonly ("resumeVM" | "postResumeInit")[] | undefined;
+}
+export interface PrepareBoundaryParksResult {
+    /** owned — the task-axis resource lane (`Prepared.suspendForResource`), or undefined (no opt-in / no infra / inactive). */
+    suspendForResource: Prepared["suspendForResource"];
+    /** owned — the platform lane (`Prepared.suspendForPlatformLimit`), or undefined (no durable infra / inactive). */
+    suspendForPlatformLimit: Prepared["suspendForPlatformLimit"];
+    /** owned — the plan-review lane (`Prepared.suspendForReview`), or undefined (no store / inactive). */
+    suspendForReview: Prepared["suspendForReview"];
+}
+/** The M19 boundary-parks phase body — prepareTask's three boundary lanes, verbatim (see the module header). */
+export declare function prepareBoundaryParks(input: PrepareBoundaryParksInput): PrepareBoundaryParksResult;

package/dist/core/runner/prepare-boundary-parks.js

@@ -0,0 +1,169 @@
+import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
+import { BINDING_CHECKPOINT_VERSION, debitLedger, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, mintCheckpointId, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, } from "../checkpoint-store.js";
+import { defaultTaskRegistry } from "../task-registry.js";
+import { checkpointScopeOf } from "./checkpoint-scope.js";
+import { DEFAULT_RESOURCE_TTL_MS, publishCommittedSuspend, sanitizedTtlMs, USAGE_WINDOW_REAP_MARGIN_MS } from "./park-commit.js";
+import { remoteEnvFailureNote } from "./remote-env-retry.js";
+export function prepareBoundaryParks(input) {
+    const { saga, spec, checkpointStore, abortController, harness, session, sessions, sessionId, deps, priorLedger, maxSlices, maxSuspends, resourceTotal, priorSuspendCount, suspendChainBase, humanReviewRef, liveSpendRef, now, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, pausedRef, remoteEnvFailures, resourceSuspendEligible, durableSuspendInfraReady, incompleteSuspendAdapter } = input;
+    if (saga === undefined)
+        return { suspendForResource: undefined, suspendForPlatformLimit: undefined, suspendForReview: undefined };
+    const { inFlightSpendMicroUsd, serializeCheckpointState, commitSuspendSaga, suspendLoopCapHit, suspendableEnv, parkOnlyRemoteEnv, parkOnlyHandle } = saga;
+    const mintResourceSuspend = async (reason, sliceSpend, hint) => {
+        const rs = spec.resourceSuspend;
+        if (!checkpointStore)
+            return false;
+        const scope = rs?.scope ?? checkpointScopeOf(spec);
+        if (abortController.signal.aborted)
+            return false;
+        if (suspendLoopCapHit(priorLedger?.sliceCount ?? 0, maxSlices, " (resource slice limit)"))
+            return false;
+        const leafId = await session.getLeafId();
+        if (!leafId)
+            return false;
+        if (abortController.signal.aborted)
+            return false;
+        let remoteHandle;
+        if (suspendableEnv !== undefined) {
+            if (hasBackgroundShell(suspendableEnv))
+                await sweepBackgroundShells(suspendableEnv, defaultTaskRegistry);
+            const snap = await suspendableEnv.suspendVM({ abortSignal: abortController.signal });
+            if (!snap.ok) {
+                remoteEnvFailures.push(remoteEnvFailureNote("suspendVM", snap.error, 1));
+                deps.onError?.(new Error(`resource suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error }), { phase: "config", sessionId });
+                return false;
+            }
+            remoteHandle = { ...suspendableEnv.workspaceHandle(), snapshotId: snap.value };
+        }
+        else if (parkOnlyRemoteEnv !== undefined) {
+            if (hasBackgroundShell(parkOnlyRemoteEnv) && spec.retainBackgroundProcesses !== true)
+                await sweepBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry);
+            remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+        }
+        const token = mintCheckpointToken();
+        const gate = { kind: "resource_limit", reason, ...(hint !== undefined ? { resumeAfterMs: hint.resumeAfterMs } : {}) };
+        const resourceLedgerOut = debitLedger(priorLedger, sliceSpend, resourceTotal);
+        const mintedAt = Date.now();
+        const cp = {
+            token,
+            checkpointId: mintCheckpointId(),
+            version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : resourceLedgerOut.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : RESOURCE_CHECKPOINT_VERSION,
+            scope,
+            sessionId,
+            leafId,
+            gate,
+            pendingAction: { kind: "resource_limit", reason },
+            state: serializeCheckpointState(remoteHandle),
+            status: "pending",
+            createdAt: mintedAt,
+            deadline: mintedAt + Math.max(sanitizedTtlMs(rs?.ttlMs) ?? DEFAULT_RESOURCE_TTL_MS, hint !== undefined ? hint.resumeAfterMs + USAGE_WINDOW_REAP_MARGIN_MS : 0),
+            suspendCount: priorSuspendCount,
+            humanReview: humanReviewRef.count > 0
+                ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                : undefined,
+            resourceLedger: resourceLedgerOut,
+            ...(spec.durableApproval !== undefined ? { durableApproval: { ...spec.durableApproval } } : {}),
+            ...(spec.principal ? { principal: spec.principal } : {}),
+        };
+        if ((await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).tag !== "committed")
+            return false;
+        publishCommittedSuspend({ pausedRef }, token, gate, scope, remoteHandle, cp.checkpointId, cp.pendingAction);
+        try {
+            await sessions.pin?.(sessionId);
+        }
+        catch (pinErr) {
+            deps.onError?.(pinErr, { phase: "config", sessionId });
+        }
+        harness.requestStopAfterTurn();
+        return true;
+    };
+    const suspendForResource = resourceSuspendEligible ? mintResourceSuspend : undefined;
+    const suspendForPlatformLimit = durableSuspendInfraReady ? mintResourceSuspend : undefined;
+    const suspendForReview = checkpointStore
+        ? async (reason) => {
+            if (!checkpointStore)
+                return false;
+            if (abortController.signal.aborted)
+                return false;
+            if (incompleteSuspendAdapter !== undefined) {
+                try {
+                    deps.onError?.(new Error(`plan_review park skipped: the per-task execution env declares capabilities.suspendable but its adapter does not implement ${incompleteSuspendAdapter.join(" or ")}, so its workspace could not be restored on resume (the plan-review request was dropped; the run continues without pausing)`), { phase: "config", sessionId });
+                }
+                catch {
+                }
+                return false;
+            }
+            if (suspendLoopCapHit(suspendChainBase(), maxSuspends, " for a plan_review (likely a resume/restart loop)."))
+                return false;
+            const leafId = await session.getLeafId();
+            if (!leafId) {
+                try {
+                    deps.onError?.(new Error("plan_review park skipped: no committed session leaf (the plan-review request was dropped; the run continues without pausing)"), { phase: "config", sessionId });
+                }
+                catch {
+                }
+                return false;
+            }
+            if (abortController.signal.aborted)
+                return false;
+            let remoteHandle;
+            if (suspendableEnv !== undefined) {
+                if (hasBackgroundShell(suspendableEnv))
+                    await sweepBackgroundShells(suspendableEnv, defaultTaskRegistry);
+                const snap = await suspendableEnv.suspendVM({ abortSignal: abortController.signal });
+                if (!snap.ok) {
+                    remoteEnvFailures.push(remoteEnvFailureNote("suspendVM", snap.error, 1));
+                    deps.onError?.(new Error(`plan_review suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error }), { phase: "config", sessionId });
+                    return false;
+                }
+                remoteHandle = { ...suspendableEnv.workspaceHandle(), snapshotId: snap.value };
+            }
+            else if (parkOnlyRemoteEnv !== undefined) {
+                if (hasBackgroundShell(parkOnlyRemoteEnv) && spec.retainBackgroundProcesses !== true)
+                    await sweepBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry);
+                remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+            }
+            const token = mintCheckpointToken();
+            const scope = checkpointScopeOf(spec);
+            const gate = { kind: "plan_review", reason: reason ?? `plan review requested` };
+            const reviewLedger = debitLedger(priorLedger, liveSpendRef.get?.() ?? { costMicroUsd: 0, tokens: 0, turns: 0, walltimeMs: 0 }, resourceTotal, { countSlice: false });
+            const mintedAt = Date.now();
+            const cp = {
+                token,
+                checkpointId: mintCheckpointId(),
+                version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : reviewLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
+                scope,
+                sessionId,
+                leafId,
+                gate,
+                pendingAction: { kind: "plan_review" },
+                state: serializeCheckpointState(remoteHandle, inFlightSpendMicroUsd()),
+                status: "pending",
+                createdAt: mintedAt,
+                suspendedAt: now(),
+                deadline: mintedAt + (sanitizedTtlMs(spec.durableApproval?.ttlMs) ?? DEFAULT_RESOURCE_TTL_MS),
+                suspendCount: suspendChainBase() + 1,
+                humanReview: humanReviewRef.count > 0
+                    ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                    : undefined,
+                resourceLedger: reviewLedger,
+                sourceTaskId: sessionId,
+                ...(spec.principal ? { principal: spec.principal } : {}),
+                ...(spec.durableApproval !== undefined ? { durableApproval: { ...spec.durableApproval } } : {}),
+            };
+            if ((await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).tag !== "committed")
+                return false;
+            publishCommittedSuspend({ pausedRef }, token, gate, scope, remoteHandle, cp.checkpointId, cp.pendingAction);
+            try {
+                await sessions.pin?.(sessionId);
+            }
+            catch (pinErr) {
+                deps.onError?.(pinErr, { phase: "config", sessionId });
+            }
+            abortController.abort();
+            void harness.abort();
+            return true;
+        }
+        : undefined;
+    return { suspendForResource, suspendForPlatformLimit, suspendForReview };
+}

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -244,7 +244,7 @@ export async function prepareCapsAndWorkflow(input) {
             },
             ...(spec.handsReadOnly === true ? { parentHandsReadOnly: true } : {}), ...(spec.interactiveTools === false ? { parentInteractiveTools: false } : {}),
             onNotice: deps.onNotice,
-            parentCheckpointStoreDisabled: spec.checkpointStore === null,
+            parentCheckpointStoreDisabled: spec.checkpointStore === "disabled",
             parentCenterArtifactDigest: () => input.centerAdoption()?.artifact.artifactDigest,
             parentCenterSourceRevision: () => input.centerAdoption()?.sourceRevision,
             ...(forwardEvent ? { forwardEvent } : {}),

package/dist/core/runner/prepare-context-lane.d.ts

@@ -0,0 +1,119 @@
+/**
+ * design/390 §1.2 M21 — prepareTask's CONTEXT-LANE phase, verbatim from the driver: the edit/guard budgets, the
+ * microCompact machine state with the trigger-window clamp's one loud outlet, the model's chars-per-token coordinate,
+ * and the `context` handler registered on the harness — heal → ledger replay → aggregate tool-result and media caps →
+ * frontier clear → the guard chain (arms A/B/C) → the git-frame guard → the orphan belt → the lossy-projection flag →
+ * the projection seat. The four module-level helpers only this lane called moved with it (the machine-state builder,
+ * the frontier-clear recorder, the observation-buffer flush, the guard chain with its two types). The interface is the
+ * dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the handler it registers is async and
+ * runs per provider request), so the phase adds no yield between the gate stations before it and the turn wiring after
+ * it (design/390 §1.5). Read-stability of the host handles: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * REGISTRATION SIDE EFFECT, OWNED: this phase registers the ONE `context` handler on the harness; the harness owns the
+ * listener for the run's life (it is never unregistered — the harness is per prepare). No other station registers on
+ * that hook.
+ */
+import { type AgentHarness, type AgentMessage } from "../../internal/harness.js";
+import type { Model } from "../../internal/llm.js";
+import { type ContextEditMachine, type OccurrenceIndex } from "../context-edit.js";
+import { type ToolResultStore } from "../tool-result-store.js";
+import { type RunnerDeps } from "../types.js";
+import type { Prepared, PreparedMicroCompact } from "./contracts.js";
+import { type GitStatusLaneRef } from "./git-status-frame.js";
+export interface PrepareContextLaneInput {
+    /** borrowed-readonly — the task model: the budgets, the trigger-window geometry and `charsPerToken` are read off it. */
+    model: Model;
+    /** borrowed-readonly — the deployment seats, whole: `onNotice` (the clamp outlet, the offload-loss announcement), `tracer`
+     *  (the cap / clear / trim frames), `mediaByteCapBytes` and `onMediaStripped` (the media cap), `onError` (the belt line, the
+     *  git-frame degrade) — the guard chain and the machine-state builder read through the whole record. */
+    deps: RunnerDeps;
+    /** borrowed-readonly — the acquired session id (the offload persist key; every disclosure's attribution). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (the clamp notice's per-run claim). */
+    runId: string;
+    /** borrowed-readonly — the per-task identity (the trace frames' taskId). */
+    hostTaskId: string;
+    /** borrowed-readonly — the run's offload store, or undefined (the caps' and the machine's persist seat). */
+    offloadStore: ToolResultStore | undefined;
+    /** borrowed-readonly — the doors' RESOLVED microCompact knob (immutable values, never the deps bag). */
+    microCompactKnob: {
+        machine: "off" | ContextEditMachine;
+        clearOnRejection: boolean;
+    };
+    /** borrowed-mutable — the built harness. Writer here: `on("context", …)` — the ONE registration of the request-build
+     *  handler (the harness owns the listener; nothing unregisters it). */
+    harness: AgentHarness;
+    /** borrowed-mutable — the turn's halt fact (`Prepared.batchHaltRef`). Writer here: the handler CLEARS it at every new
+     *  provider request (a new request means the halted boundary was legitimately passed). The judgment site sets it. */
+    batchHaltRef: Prepared["batchHaltRef"];
+    /** borrowed-mutable — the git-status lane ref. Writers here: the git-frame guard's degrade latch (`overBudgetShrunk`) inside
+     *  the handler; the prompt-inputs phase seeds it. */
+    gitStatusRef: GitStatusLaneRef;
+    /** borrowed-mutable — the per-request lossy-projection flag. Writer here: the handler re-derives it at every request
+     *  build; the provider-seam recording shim reads it immediately after. */
+    requestLossyRef: {
+        current: boolean;
+    };
+    /** borrowed-mutable — the trim-pressure flag (`Prepared.trimPressureRef`). Writer here: the guard chain's trim arm sets
+     *  `droppedMessages`; the run loop's boundary reads and clears it. */
+    trimPressureRef: {
+        droppedMessages: boolean;
+    };
+}
+export interface PrepareContextLaneResult {
+    /** owned — the per-run microCompact machine state (`Prepared.microCompact`): machine, MC-R flag, ledger, the projection
+     *  and in-turn-compaction seats the handler and the runtask arms fill. */
+    microCompact: PreparedMicroCompact;
+    /** owned — the model's structural coefficient (`charsPerToken ?? DEFAULT`), the ONE coordinate the request-layer
+     *  defenses here and the prompt-overhead term downstream share with the compaction trigger estimate. */
+    charsPerToken: number;
+}
+/** The M21 phase body — prepareTask's context-lane stretch, verbatim (see the module header). */
+export declare function prepareContextLane(input: PrepareContextLaneInput): PrepareContextLaneResult;
+/** See {@link runGuardChain}. */
+export interface GuardChainArgs {
+    /** The post-frontier view the chain starts from. */
+    edited: AgentMessage[];
+    /** The pre-cap counterpart view (arm A's clearSource — RB-212 durable composition seat). */
+    replayed: AgentMessage[];
+    index: OccurrenceIndex;
+    microCompact: PreparedMicroCompact;
+    guardAt: number;
+    charsPerToken: number;
+    offloadStore: import("../tool-result-store.js").ToolResultStore | undefined;
+    sessionId: string;
+    taskId: string;
+    deps: RunnerDeps;
+    trimPressureRef: {
+        droppedMessages: boolean;
+    };
+    recheck: boolean | undefined;
+    signal: AbortSignal | undefined;
+    /** The r7 per-request observation buffer — the chain DROPS it on its early returns (a discarded
+     *  provisional projection must not narrate itself). */
+    pendingProjectionObservations: Array<() => void>;
+}
+export type GuardChainOutcome = {
+    earlyReturn: {
+        messages: AgentMessage[];
+        adoptSessionRebuild?: boolean;
+    };
+} | {
+    working: AgentMessage[];
+    trimmed: AgentMessage[];
+    trimDroppedMessages: boolean;
+};
+/**
+ * design/374 slice 3 — the GUARD CHAIN over one request build (D-7 case-ii transfer table),
+ * module-level per the design/238 body-span bank. design/123 D3: the chain reads the anchored
+ * coordinate re-estimated on the EDITED array (pre-anchor clears don't lower it — deliberately;
+ * trimToBudget doc). The opt-out machine = the pre-374 backstop order byte-identical
+ * (trim as the ordinary second line); otherwise arm A (blocking machine run, only when the
+ * frontier pass is off) → arm B (in-turn forced compaction behind the adopt seam) → arm C (trim,
+ * the disaster-only last resort and this chain's sole `context.trim` emitter). Returns either the
+ * post-chain view for the pipeline tail, or an EARLY hook result the context handler must return
+ * verbatim (arm-B adoption / the r8 dead-turn stand-down).
+ */
+export declare function runGuardChain(args: GuardChainArgs): Promise<GuardChainOutcome>;

package/dist/core/runner/prepare-context-lane.js

@@ -0,0 +1,230 @@
+import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens } from "../../internal/harness.js";
+import { clearStaleToolResults, createClearedProjectionLedger, dropEmptyFailureAssistants, editBudget, replayClearedProjection, resolveTriggerWindow } from "../context-edit.js";
+import { dropOrphanToolResults, guardBudget, insertTrimNotice, trimToBudget } from "../context-guard.js";
+import { AGGREGATE_MEDIA_BUDGET_BYTES, capAggregateMediaBytes } from "../media-byte-cap.js";
+import { capAggregateToolResults } from "../tool-result-budget.js";
+import { createOffloadPersist } from "../tool-result-store.js";
+import { emitTrace } from "../trace.js";
+import { deliverEngineNotice } from "../types.js";
+import { applyGitFrameGuard } from "./git-status-frame.js";
+export function prepareContextLane(input) {
+    const { model, deps, sessionId, runId, hostTaskId, offloadStore, microCompactKnob, harness, batchHaltRef, gitStatusRef, requestLossyRef, trimPressureRef } = input;
+    const editAt = editBudget(model);
+    const guardAt = guardBudget(model);
+    const microCompact = buildMicroCompactState(deps, model, sessionId, runId, offloadStore, microCompactKnob);
+    const charsPerToken = model.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    harness.on("context", async ({ messages, recheck, signal }) => {
+        batchHaltRef.current = undefined;
+        const pendingProjectionObservations = [];
+        try {
+            const healed = dropEmptyFailureAssistants(messages);
+            const replay = replayClearedProjection(healed, microCompact.ledger);
+            const replayed = replay.messages;
+            const capped = await capAggregateToolResults(replayed, {
+                store: offloadStore,
+                sessionId,
+                onCapped: (info) => pendingProjectionObservations.push(() => emitTrace(deps.tracer, () => ({
+                    kind: "tool_result.capped",
+                    version: 1,
+                    taskId: hostTaskId,
+                    ...(info.tool !== undefined ? { tool: info.tool } : {}),
+                    sizeChars: info.sizeChars,
+                    storeFallback: info.storeFallback,
+                    ts: Date.now(),
+                }))),
+            });
+            const mediaCapped = capAggregateMediaBytes(capped, {
+                limitBytes: deps.mediaByteCapBytes ?? AGGREGATE_MEDIA_BUDGET_BYTES,
+                onStripped: (info) => {
+                    const onMediaStripped = deps.onMediaStripped;
+                    if (onMediaStripped !== undefined)
+                        pendingProjectionObservations.push(() => onMediaStripped(info));
+                },
+            });
+            let ccPass;
+            const edited = microCompact.machine === "off" ? mediaCapped : clearStaleToolResults(mediaCapped, {
+                budgetTokens: editAt,
+                machine: microCompact.machine,
+                ...(microCompact.machine === "cc" || microCompact.clearOnRejection ? { recognizeCcMarkers: true } : {}),
+                ...(microCompact.machine === "cc"
+                    ? {
+                        clearSource: replayed,
+                        onCleared: (pass) => { ccPass = pass; },
+                    }
+                    : {}),
+                anchoredTotalTokens: estimateContextTokens(mediaCapped, charsPerToken).tokens,
+                charsPerToken,
+                ...(offloadStore
+                    ? {
+                        offload: {
+                            persist: createOffloadPersist(offloadStore, sessionId, deps.onNotice),
+                        },
+                    }
+                    : {}),
+            });
+            if (ccPass !== undefined) {
+                recordFrontierClears({ pass: ccPass, index: replay.index, edited, ledger: microCompact.ledger, tracer: deps.tracer, taskId: hostTaskId, trigger: "frontier" });
+            }
+            const chain = await runGuardChain({
+                edited, replayed, index: replay.index, microCompact, guardAt, charsPerToken, offloadStore,
+                sessionId, taskId: hostTaskId, deps, trimPressureRef, recheck, signal,
+                pendingProjectionObservations,
+            });
+            if ("earlyReturn" in chain) {
+                return chain.earlyReturn;
+            }
+            const { working, trimDroppedMessages } = chain;
+            let trimmed = chain.trimmed;
+            trimmed = applyGitFrameGuard({
+                before: working,
+                trimmed,
+                budgetTokens: guardAt,
+                ref: gitStatusRef,
+                charsPerToken,
+                onDegrade: (message) => {
+                    try {
+                        deps.onError?.(new Error(message), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
+                    }
+                    catch {
+                    }
+                },
+            });
+            const swept = dropOrphanToolResults(trimmed);
+            if (swept.dropped.length > 0) {
+                try {
+                    deps.onError?.(new Error(`context belt: dropped ${swept.dropped.length} orphan toolResult(s) whose tool-call assistant was not in the request view — ` +
+                        swept.dropped
+                            .map((d) => `toolCallId=${d.toolCallId} at index ${d.index} (prev=${d.prevRole}, next=${d.nextRole})`)
+                            .join("; ")), { phase: "hook", sessionId });
+                }
+                catch {
+                }
+            }
+            requestLossyRef.current =
+                replayed !== healed ||
+                    capped !== replayed ||
+                    mediaCapped !== capped ||
+                    edited !== mediaCapped ||
+                    working !== edited ||
+                    trimDroppedMessages ||
+                    swept.dropped.length > 0 ||
+                    gitStatusRef.overBudgetShrunk === true;
+            microCompact.projectionRef.current = { messages: swept.messages, keyOf: replay.index.keyOf };
+            return { messages: swept.messages };
+        }
+        finally {
+            flushProjectionObservations(pendingProjectionObservations);
+        }
+    });
+    return { microCompact, charsPerToken };
+}
+function buildMicroCompactState(deps, model, sessionId, runId, offloadStore, knob) {
+    const triggerWindow = resolveTriggerWindow(model);
+    if (triggerWindow.clamped) {
+        deliverEngineNotice(deps.onNotice, {
+            code: "config.autocompact_window_clamped",
+            message: `model "${model.id}" declares autoCompactTokens=${triggerWindow.declaredAutoCompactTokens} ABOVE its physical window ` +
+                `${triggerWindow.physicalWindow}; the autocompact window only ever LOWERS the trigger-side geometry, so the value was ` +
+                `clamped to the physical window — fix the model config (declare a value at or below the physical window, or omit it)`,
+            detail: {
+                modelId: model.id,
+                declaredAutoCompactTokens: triggerWindow.declaredAutoCompactTokens,
+                physicalWindow: triggerWindow.physicalWindow,
+                sessionId,
+                runId,
+            },
+        });
+    }
+    return {
+        machine: knob.machine,
+        clearOnRejection: knob.clearOnRejection,
+        ledger: createClearedProjectionLedger(),
+        projectionRef: {},
+        inTurnCompactionRef: {},
+        ...(offloadStore ? { offloadPersist: createOffloadPersist(offloadStore, sessionId, deps.onNotice) } : {}),
+    };
+}
+function recordFrontierClears(args) {
+    for (const { index } of args.pass.clears) {
+        const at = args.index.keyAt(index);
+        const clearedMsg = args.edited[index];
+        const markerText = clearedMsg.content?.[0]?.text;
+        if (at !== undefined && typeof markerText === "string") {
+            args.ledger.entries.set(at.key, { marker: markerText, groupCount: at.groupCount, fp: at.fp });
+        }
+    }
+    emitTrace(args.tracer, () => ({
+        kind: "context.mc_clear",
+        version: 1,
+        taskId: args.taskId,
+        clearedCount: args.pass.clears.length,
+        tokensSavedEstimate: args.pass.tokensSavedEstimate,
+        trigger: args.trigger,
+        ts: Date.now(),
+    }));
+}
+function flushProjectionObservations(pending) {
+    for (const fire of pending.splice(0)) {
+        try {
+            fire();
+        }
+        catch {
+        }
+    }
+}
+export async function runGuardChain(args) {
+    const { edited, microCompact, guardAt, charsPerToken, deps, taskId } = args;
+    const applyGuardTrim = (view, anchoredTotal) => {
+        let trimmed = trimToBudget(view, guardAt, anchoredTotal, charsPerToken);
+        const dropped = trimmed.length < view.length;
+        if (dropped) {
+            args.trimPressureRef.droppedMessages = true;
+            const droppedCount = view.length - trimmed.length;
+            trimmed = insertTrimNotice(trimmed);
+            emitTrace(deps.tracer, () => ({
+                kind: "context.trim",
+                version: 1,
+                taskId,
+                dropped: droppedCount,
+                ts: Date.now(),
+            }));
+        }
+        return { trimmed, dropped };
+    };
+    let working = edited;
+    let anchoredWorking = estimateContextTokens(working, charsPerToken).tokens;
+    if (microCompact.machine === "legacy") {
+        const t = applyGuardTrim(working, anchoredWorking);
+        return { working, trimmed: t.trimmed, trimDroppedMessages: t.dropped };
+    }
+    if (microCompact.machine === "off" && anchoredWorking > guardAt) {
+        let blockingPass;
+        const blockingEdited = clearStaleToolResults(working, {
+            budgetTokens: guardAt,
+            machine: "cc",
+            clearSource: args.replayed,
+            onCleared: (pass) => { blockingPass = pass; },
+            anchoredTotalTokens: anchoredWorking,
+            charsPerToken,
+            ...(args.offloadStore ? { offload: { persist: createOffloadPersist(args.offloadStore, args.sessionId, deps.onNotice) } } : {}),
+        });
+        if (blockingPass !== undefined) {
+            recordFrontierClears({ pass: blockingPass, index: args.index, edited: blockingEdited, ledger: microCompact.ledger, tracer: deps.tracer, taskId, trigger: "blocking" });
+            working = blockingEdited;
+            anchoredWorking = estimateContextTokens(working, charsPerToken).tokens;
+        }
+    }
+    if (anchoredWorking > guardAt && args.recheck !== true) {
+        const compacted = (await microCompact.inTurnCompactionRef.current?.(args.signal, anchoredWorking)) === true;
+        if (compacted) {
+            args.pendingProjectionObservations.length = 0;
+            return { earlyReturn: { messages: working, adoptSessionRebuild: true } };
+        }
+        if (args.signal?.aborted === true) {
+            args.pendingProjectionObservations.length = 0;
+            return { working, trimmed: working, trimDroppedMessages: false };
+        }
+    }
+    const t = applyGuardTrim(working, anchoredWorking);
+    return { working, trimmed: t.trimmed, trimDroppedMessages: t.dropped };
+}