@sema-agent/core 7.6.0 → 7.6.2

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

@@ -22,29 +22,35 @@ import type { WorkflowSizeGuideline } from "../../orchestration/workflow-size-gu
 import type { ToolManifestRow } from "../../prompt-assembly/tool-catalog.js";
 import type { CwdRef, ReadFace } from "../../tools/fs/index.js";
 import type { MaterializedA2a } from "../a2a.js";
-import type { CompactionForkContext } from "../auto-compaction.js";
+import type { CompactionForkContext, MaybeCompactOptions, RapidRefillState } from "../auto-compaction.js";
 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 { Checkpoint, CheckpointState, CheckpointToken, PlatformLimitReason, ResourceLedger, ResourceLimitReason, SerializedCheckpointState } from "../checkpoint-store.js";
+import type { ActorAssertion, Checkpoint, CheckpointState, CheckpointStore, CheckpointToken, PendingSteerEntry, PlatformLimitReason, ReopenReason, ResourceLedger, ResourceLimitReason, ResumeOutcome, SerializedCheckpointState } from "../checkpoint-store.js";
 import type { ClearedProjectionLedger, ContextEditMachine, OccurrenceIndex } from "../context-edit.js";
-import type { HookInvocationIdentity, Hooks, OrgGateVerdict, PermissionDeniedPayload, ToolGateInput } from "../hooks.js";
+import type { HookInvocationIdentity, Hooks, OrgGateVerdict, PermissionDeniedPayload, PostToolBatchCall, PostToolBatchResult, ToolGateInput } from "../hooks.js";
 import type { MaterializedMcp } from "../mcp.js";
 import type { MemoryEngine } from "../memory-engine/engine.js";
 import type { HarvestReport, MemorySessionHandle } from "../memory-engine/types.js";
 import type { SessionPermissionRules } from "../session-policy-store.js";
 import type { RecoveredOrphan } from "../session-reconcile.js";
-import type { StoredSession } from "../session.js";
-import type { TaskNotificationPayload } from "../task-notification.js";
+import type { SessionStore, StoredSession } from "../session.js";
+import type { TaskOutcome } from "../task-outcome.js";
+import type { ModelPricing } from "../pricing.js";
+import type { PushQueue } from "../push-queue.js";
+import type { SystemInjectionPriority, TaskNotificationPayload } from "../task-notification.js";
 import type { OnAsk, PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "../tool-policy.js";
 import type { RemoteExecutionEnv, SnapshotId, WorkspaceHandle } from "../remote-env.js";
 import type { ToolDisclosureManifest } from "../trace.js";
-import type { NestedUsageAccum, RunnerDeps, TaskEvent, TaskResult, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
+import type { AgentDefinition, Brain, CompactOutcome, NestedUsageAccum, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream, ToolActivity, ToolEffect } from "../types.js";
 import type { WiringManifest } from "../wiring-manifest.js";
 import type { ActiveSkillFrame } from "./active-skill-scope.js";
+import type { BudgetAxis } from "./assemble-result.js";
 import type { GitStatusLaneRef } from "./git-status-frame.js";
 import type { SessionReadFileStates } from "./prepare-hands-readface.js";
 import type { BlockedRef, OutputRef, SkillListingEntry } from "./synthetic-tools.js";
+import type { createAttachmentState, WriteFamily } from "./turn-attachments.js";
+import type { cacheFamilyOf } from "./usage-accounting.js";
 /**
  * The frozen task-start snapshot of the caller's tool-face control arrays: produced by the
  * config-doors phase, read by the hands/read-face phase. Named here rather than reached for as
@@ -1970,3 +1976,373 @@ export interface ParkAsk {
      *  lane is not armed (the gate then keeps the synchronous onAsk path). */
     suspendAsk: ToolGateInput["suspendAsk"];
 }
+/**
+ * design/157 B15 二期 — `runLocked`'s per-run mutable state, EXPLICIT. These fields started as loose
+ * `let`/`const` bindings in the R2 declaration hub; the extraction kept every assignment at its
+ * original site and order (binding-form-only rewrite — the event-snapshot pin held the run
+ * byte-identical), and later work has since added fields directly here (see the per-field notes).
+ * Grouped by lifecycle semantics per the B15 pre-recon partition. Function members start as inert
+ * placeholders and are assigned at their ORIGINAL declaration sites (the original code could not
+ * call them earlier either — TDZ proved it). Not on the npm face; this extraction is what enabled
+ * makeTurnBoundary / makeHarnessHandlers (三期, both in runtask.ts).
+ */
+export interface RunState {
+    telemetry: {
+        cacheFamily: ReturnType<typeof cacheFamilyOf>;
+        pricing: ModelPricing;
+        /** RB-368 ([2076]): whether the CURRENT serving model has a configured price table (a
+         *  `RunnerDeps.pricing` entry or a `Model.cost` declaration). When neither exists,
+         *  `modelCostToPricing(undefined)` yields an all-zero table and every computed cost is a
+         *  fabricated 0 — indistinguishable from "declared free". This flag keeps the two apart so
+         *  the DISCLOSURE faces (trace frames, public stats) can go absent instead of lying; the
+         *  internal budget coordinate (`stats.costMicroUsd`) stays numeric either way. */
+        pricingConfigured: boolean;
+        /** RB-368: sticky — some spend was ACCOUNTED while `pricingConfigured` was false (a mid-task
+         *  model switch can flip pricedness, so per-call state isn't enough for the task total). Once
+         *  true, the task-level cost total is an undercount and its faces are omitted. */
+        unpricedSpend: boolean;
+        tracer: TaskSpec["tracer"];
+        taskId: string;
+        /** #499 — the run's engine-minted identity, so the task.start/task.end pair carries it from ONE
+         *  seat (the same place taskId is published). Empty only before the run body assigns it. */
+        runId: string;
+        taskStart: number;
+        taskStartMonotonic: number;
+        cacheBreakReported: boolean;
+    };
+    degrade: {
+        degradeToModel: Model | undefined;
+        degraded: TaskResult["degraded"];
+        outputErrorStreak: number;
+        outputInvalid: boolean;
+        recordDegraded: (info: NonNullable<TaskResult["degraded"]>, toModel?: Model) => void;
+    };
+    limits: {
+        turnsExceeded: boolean;
+        budgetHit: "exceeded" | "precall" | undefined;
+        /** design/164 — WHICH budget axis tripped, set at the same instant as {@link budgetHit} so the
+         *  terminal can name it (`limits.max_tokens_exceeded` vs `limits.max_cost_exceeded`). Tokens
+         *  outrank cost when both are over at the same boundary (the documented attribution order). */
+        budgetAxis: BudgetAxis | undefined;
+        /** design/164 件四/件五 — the TYPED terminal an EXTERNAL cause (a dying execution environment, an
+         *  exhausted governance window) recorded when it could not suspend the run durably. Set together with
+         *  the abort it triggers, and adopted as the run's `threw` once the loop settles, so the caller gets
+         *  `env.lifetime_expired` / `usage.window_exhausted` instead of the anonymous error an abort produces.
+         *  Same carrier shape as `brainCallGuardrailRef.timedOut`, and for the same reason: the harness turns a
+         *  loop throw into an error assistant message that strips the error object. */
+        platformTerminal: (Error & {
+            code?: string;
+            retryAfterMs?: number;
+        }) | undefined;
+        outputRetryCap: number;
+        effectiveMaxTurns: number | undefined;
+    };
+    budget: {
+        remainingMicroUsd: number | undefined;
+        maxCostMicroUsd: number | undefined;
+        /** design/164 — tokens still available on the cross-slice allocation (`resourceSuspend.totalTokens`
+         *  minus everything earlier slices spent), or `undefined` when no total is set. */
+        remainingTokens: number | undefined;
+        /** This slice's EFFECTIVE token ceiling = `min(limits.maxTokens, remainingTokens)`. The exact mirror
+         *  of `maxCostMicroUsd`. `undefined` = no token ceiling; `0` is a real, exhausted ceiling. */
+        maxTokensWindow: number | undefined;
+        /** The axis that is over its ceiling right now, or `undefined` when neither is — a predicate that
+         *  ALSO carries the attribution, so no caller can set `budgetHit` without an axis. */
+        overBudget: () => BudgetAxis | undefined;
+        streamCancel: boolean;
+        callOutputChars: number;
+        lastStreamBudgetCheck: number;
+        projectedOverBudget: () => BudgetAxis | undefined;
+    };
+    turn: {
+        callStartAt: number | undefined;
+        firstTokenAt: number | undefined;
+        turnUsage: {
+            inputTokens: number;
+            totalInputTokens: number;
+            outputTokens: number;
+            cacheReadTokens: number;
+            cacheWriteTokens: number;
+            costMicroUsd: number;
+        } | undefined;
+        turnUsageMissing: boolean;
+        turnStopReason: string | undefined;
+        lastTurnHadToolCalls: boolean;
+        /** B15 三期使能:design/134 §3.1b postToolBatch 的本回合聚集批(每回合边界消费并重置 — 回合语义,故归 turn)。 */
+        toolBatch: PostToolBatchCall[];
+    };
+    counters: {
+        /** design/164 — how many LIMIT-APPROACH frames have been injected this run (0..2). Also the
+         *  one-shot latch itself: each frame fires when the count is still below its index. */
+        approachNoticesSent: number;
+        /** B15 三期使能:R9 引用的 R3/压缩区 latch(walltime 收尾 latch — preemptIgnoredReported 同族)。 */
+        walltimeSyncBackstopFired: boolean;
+        /** B15 三期终件补遗:压缩地板/背压 latch — rs.counters.compactionFloor 跨 drainManualCompact(写)/R9(读写)/收尾(读)三方共享,rs.counters.trimForceBackoff 为 R9 跨调用 latch(同款只改绑定不改时机)。 */
+        compactionFloor: number;
+        trimForceBackoff: boolean;
+        repetitionCuts: number;
+        repetitionSpared: number;
+        repetitionEvents: Array<{
+            turn: number;
+            action: "cut" | "spared";
+            rule: "char-run" | "unit-loop";
+            period: number;
+            reps: number;
+            segment: string;
+        }>;
+        REPETITION_EVENTS_CAP: number;
+        preemptIgnoredReported: boolean;
+        wroteThisRun: boolean;
+        finalVerifyInjections: number;
+        groundingSignalPreR9: boolean;
+        groundingSignalPostR9: boolean;
+        cadenceTurns: number;
+    };
+    attach: {
+        attachmentsCfg: TaskSpec["attachments"];
+        agentListingOn: boolean;
+        skillsListingOn: boolean;
+        attachState: ReturnType<typeof createAttachmentState> | undefined;
+        dateState: {
+            announcedDate: string;
+        } | undefined;
+        instrProbe: RunnerDeps["probeInstructionSources"];
+        instrState: {
+            lastAnnouncedHash: Map<string, string | null>;
+        } | undefined;
+        /** #20 lane — the Workflow tool card's advisory size guideline as last ANNOUNCED to the model,
+         *  plus the live boundary-time read (Prepared.workflowSizeGuideline). Same deliberate posture as
+         *  `dateState`/`instrState`: NOT an AttachmentState member, one field, zero reducers. */
+        sizeGuidelineState: {
+            announcedGuideline: WorkflowSizeGuideline;
+            current: () => WorkflowSizeGuideline;
+        } | undefined;
+        /** B15 三期使能:boundary 注入计数(→ stats.mechanisms.attachmentsInjected;attachState 注入族语义,故归 attach)。 */
+        attachmentsInjected: number;
+    };
+}
+/** design/171 §6.3 parity, LIVE leg — one accepted live steer's REPLAY identity, the twin of the parked
+ *  queue's `samePendingSteerPayload`. `payload` is the exact string handed to the harness, so the text,
+ *  the speaker envelope and the trust framing all fold into it; `trusted` is kept SEPARATELY from those
+ *  framed bytes so a text that spells its own `<system-reminder>` wrapper can never read as the trusted
+ *  arm's byte-equal twin. `actor` carries the attribution the ledger frame reports. */
+export interface AcceptedSteerInput {
+    payload: string;
+    trusted: boolean;
+    /** design/373 (R2-F3) — the NORMALIZED priority the call delivered under (absent input ⇒ "next"),
+     *  the replay identity's sixth axis: same id + same text at a DIFFERENT tier is not a replay —
+     *  a `next` input re-sent as `now` answering "idempotent success" without the interrupt would be
+     *  a disposition lie, so it refuses `duplicate_input_id` like any other identity mismatch. */
+    priority: SystemInjectionPriority;
+    actor?: ActorAssertion;
+}
+/**
+ * Config re-supplied to {@link Runner.resume} (design/45). A suspended task's tools / model / policy /
+ * hooks cannot be reconstructed from a checkpoint token (the session stores neither tool implementations
+ * nor the hand band), so the caller's trusted control plane re-supplies the same {@link TaskSpec} it ran
+ * with — minus the conversation bits: `sessionId` comes from the checkpoint and `objective` is replaced by
+ * an internally-generated continuation, so both are omitted.
+ */
+export type ResumeTaskConfig = Omit<TaskSpec, "objective" | "sessionId">;
+/** design/45 resume plan threaded from {@link Runner.resume} into the shared run loop. */
+export interface ResumeRun {
+    cp: Checkpoint;
+    /**
+     * RB-152 (2026-07-25, 按面收口): did the APPROVED ACTION actually begin executing?
+     *
+     * The reopen compensation used to key on an error-code whitelist (`resume.env_failed` /
+     * `resume.session_not_found` / `resume.tool_unavailable`). That is a proxy for the thing that actually
+     * matters, and every time a NEW way to exit without running the action appeared, the whitelist did not
+     * know about it: a caller's abort landing anywhere between the CAS and `tool.execute` — across
+     * `SessionStore.acquire` (pluggable, cross-network on a durable backend), the MCP reconnect, the env
+     * rebuild, `resumeVM`, tool materialization — produced a `failed` result with NO errorCode, no reopen,
+     * and a human approval consumed for work that never happened. Two rounds of fixes (RB-77, RB-109) each
+     * moved that window rather than closing it, because both extended the whitelist.
+     *
+     * This binds the compensation to the FACT instead: set the instant before `tool.execute` for the gated
+     * call (the same `onExecuteStart` signal the orphan-reconcile split already trusts). Every terminal —
+     * throw OR returned result — asks one question: was the checkpoint consumed while this stayed false?
+     */
+    pendingActionStarted?: boolean;
+    /** Validated against `cp.gate.kind` at the resume entry: human/irreversible_ask→`policy_ask`,
+     *  resource_limit→`resource_limit` (design/74), needs_review→`dry_run_review` (design/76 §2.5),
+     *  plan_review→`plan_review` (design/80 D-B). The gate-match guard in `resumeStream` enforces the
+     *  correlation. design/144 §3: `wake` is the NON-GATE arm — only a checkpoint awaiting NO gate
+     *  decision passes the resume entry with it (gate purity, `wake.gate_pending`); the run loop skips
+     *  `applyResumeDecision` for it (no pending action to resolve) and re-enters via the continuation +
+     *  pendingSteer tail alone. */
+    outcome: Extract<ResumeOutcome, {
+        gate: "policy_ask" | "resource_limit" | "dry_run_review" | "plan_review" | "wake";
+    }>;
+    /** design/144 §3 (X5) — the wake's own operator message, validated (`validatePendingSteer`) at the
+     *  resume entry and carried SEPARATELY from the checkpoint's parked `pendingSteer`: a message-bearing
+     *  wake of a checkpoint that ALSO holds a parked steer must deliver BOTH (park order: parked first,
+     *  wake message second), each under its own trusted framing — the old merge-into-the-slot shape
+     *  silently DISPLACED the parked (undelivered) supervisor steer. Wake outcomes only. */
+    wakeMessage?: Omit<PendingSteerEntry, "seq">;
+    /** design/373 §4.3 (D2) — the userPromptSubmit screen's `additionalContext` for {@link wakeMessage},
+     *  captured at the resume ENTRY (the message is screened once, pre-CAS, on the resuming process's
+     *  hook) and delivered by the drain as the engine's own reminder AHEAD of the wake frame — carrying
+     *  it forward is what keeps the hook single-run (re-screening at the drain would be the double-run
+     *  §4.3-3 reserves for the cross-process parked leg). Present only when a wake message passed a
+     *  screen that supplied context. */
+    wakeMessageHookContext?: string;
+    /** Compensation hook (design/45/49): called iff the resumed run fails with `resume.env_failed` (post-CAS
+     *  workspace `resumeVM` failed) OR `resume.tool_unavailable` (P-7: the approved tool vanished) — in both
+     *  the CAS already consumed the checkpoint but the pending action never ran. `resumeStream` supplies a
+     *  closure that reopens the checkpoint (`resolved → pending`) so a retry re-resumes the SAME suspended work
+     *  instead of losing it to a forced "re-initiate". design/80 D-1 (reopen-by-reason): the `reason` is
+     *  recorded on the reopened row so the next re-resume validates per reason — an `env_failed` reopen must
+     *  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>;
+    /** 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
+     *  pre-delivery abort) and the walltime-exhausted settle fire BEFORE it is set, so an undelivered
+     *  negative decision still reopens as `env_failed` (the retry replays the persisted decision; it
+     *  never re-asks — design/80 D-1), closing the RB-152/RB-70 loss class the first RB-471 cut reopened. */
+    decisionDelivered?: boolean;
+}
+/**
+ * What {@link TaskStream.destroy} needs to reap a SUSPENDED task (design/51 §4). Captured (stashed) onto
+ * the stream handle the moment a run assembles `status:"suspended"` — `finish()` deliberately left the
+ * paused env + committed checkpoint alive for resume, so without this stash they'd be unreachable (the
+ * `Prepared`, and its `ownedEnv`, are GC'd once the run promise settles). `env` is `undefined` for a
+ * process-local suspend (no remote env to reap — only the checkpoint is expired).
+ */
+export interface SuspendReap {
+    env: Prepared["ownedEnv"];
+    token: CheckpointToken;
+    scope: string;
+    store: CheckpointStore;
+    /** The suspended task's session — for onError correlation only (the `token` is a capability and must
+     *  NEVER be logged, checkpoint-store.ts §6). */
+    sessionId: string;
+}
+/** B15 三期终件 — R9(回合边界全域:压缩/attachments 注入/提醒节律/预算判决)工厂。
+ *  正文自 runLocked 逐字搬迁(this 面经 runnerHooks 闭包打包,B13 #coreView 同款);模块级符号
+ *  同文件直见不经 deps;可变运行态全在 rs(B15 二期+使能车),deps 全部为 const 稳定引用。 */
+export interface TurnBoundaryDeps {
+    spec: TaskSpec;
+    queue: PushQueue<TaskEvent>;
+    /** The run loop's own latch — read for `userHalted` (the public `TaskStream.halt()` verb, which sets
+     *  the harness stop latch directly, not through the ctx primitive `Prepared.stopRequestedRef`
+     *  mirrors): a halted boundary has no next request either, so the bundle is not collected there. */
+    loopLatch: {
+        readonly userHalted: boolean;
+    };
+    manualCompactRef: {
+        requested: boolean;
+        waiters: Array<{
+            resolve: (outcome: CompactOutcome) => void;
+            signal?: AbortSignal;
+            instructions?: string;
+        }>;
+    };
+    todoToolMounted: boolean;
+    taskToolsMounted: boolean;
+    walltimeMonotonicDeadline: number | undefined;
+    timeout: {
+        fired: boolean;
+        latenessMs?: number;
+        clear: () => void;
+    };
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    postToolBatchHook: ((batch: PostToolBatchCall[], meta?: {
+        injectedThisTurn: "final_verification" | "finalize";
+    }, ctx?: import("../hooks.js").PostToolBatchContext) => PostToolBatchResult | undefined | Promise<PostToolBatchResult | undefined>) | undefined;
+    batchArgs: Map<string, unknown> | undefined;
+    compactionBrain: Brain;
+    withinTaskCompaction: boolean;
+    compactionBreaker: {
+        failures: number;
+    };
+    windowSafetyOptions: (mainModel: Model) => Pick<MaybeCompactOptions, "fallbackBudget" | "onWindowSafety">;
+    rapidRefill: RapidRefillState;
+    drainManualCompact: (outcome: CompactOutcome) => void;
+    runnerHooks: {
+        onError: RunnerDeps["onError"];
+        seamCCompactionOptions: (prepared: Prepared) => Pick<MaybeCompactOptions, "summaryProvider" | "onCompaction" | "maxConsecutiveProviderReuse" | "consecutiveProviderReuse"> | undefined;
+        compactionHookOptions: (spec: TaskSpec, sessionId: string, trigger: "auto" | "manual" | "forced") => Pick<MaybeCompactOptions, "trigger" | "preCompact" | "postCompact">;
+        recordCompactionReuse: (prepared: Prepared, comp: {
+            compacted: boolean;
+            reused?: boolean;
+        }) => void;
+    };
+}
+/** design/157 B15 尾件 — R5(harness 事件处理器族)的依赖包。全部为 runLocked 内声明顺序早于
+ *  工厂调用点的 const 稳定引用 + 三个 runLocked 形参;this 面(deps.onError)经 runnerHooks 打包
+ *  (B13 #coreView / R9 TurnBoundaryDeps 同款)。*/
+export interface HarnessHandlersDeps {
+    spec: TaskSpec;
+    queue: PushQueue<TaskEvent>;
+    internals: RunInternals | undefined;
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    parentToolCallId: string | undefined;
+    subagentName: string | undefined;
+    pushContent: (e: TaskEvent) => void;
+    emitCommitted: (entryId: string, role: "user" | "assistant" | "toolResult", toolCallId?: string) => void;
+    startedToolCallIds: Set<string>;
+    toolStartAt: Map<string, number>;
+    writeFamilyOf: (name: string) => WriteFamily | undefined;
+    toolLabels: Map<string, string>;
+    postToolBatchHook: ((batch: PostToolBatchCall[], meta?: {
+        injectedThisTurn: "final_verification" | "finalize";
+    }, ctx?: import("../hooks.js").PostToolBatchContext) => PostToolBatchResult | undefined | Promise<PostToolBatchResult | undefined>) | undefined;
+    batchArgs: Map<string, unknown> | undefined;
+    runnerHooks: {
+        onError: RunnerDeps["onError"];
+    };
+}
+/**
+ * The Runner as the modules it drives and the compositions over it see it — the delegation tools
+ * (Agent / SendMessage / AgentTranscript), the repair, verify, cascade, teacher and team loops, the
+ * workflow and goal orchestrations, the scenario registry, the HTTP server, `warmResume`, and the
+ * orchestrator's own trusted `runnerSelf` seat. Every one of them used to name the `Runner` CLASS
+ * through `import type`, which is a type edge from below the runner back up into it — a cycle the
+ * direction gate could only carry as an exemption, and one that reached the orchestrator through the
+ * delegation tools (prepare-task → send-message-tool → runtask).
+ *
+ * THE MEMBER SET IS MEASURED, NOT DESIGNED: it is exactly the union of what those consumers read off a
+ * Runner today (a TS-Program census over `src/`, pinned in test/runner-self-seat.test.ts so a member
+ * nobody reads reds as dead weight and a consumer reaching for a member outside it reds as a widening).
+ * `swapModels`, `sideQuery` and the constructor are NOT here — no consumer reaches them; a host that
+ * needs them holds the class. The class implements this interface, so the two cannot drift apart.
+ *
+ * Signatures are spelled out (not `Pick<Runner, …>`), because naming the class from here would be the
+ * very edge this seat exists to remove.
+ */
+export interface RunnerSelfSeat {
+    /** The session store this Runner was constructed over — the delegation tools acquire / release / fork through it. */
+    readonly sessions: SessionStore;
+    /** The deployment agent + model catalog, READ-ONLY (a fresh copy per read; the definitions are the shared objects). */
+    readonly agentCatalog: {
+        agents?: AgentDefinition[];
+        builtinAgents?: boolean;
+        models?: Record<string, Model>;
+    };
+    /** The deployment-level gating baseline (deps toolPolicy / hooks) as delegate wrappers — for assemblers that compose with it. */
+    readonly gateBaseline: {
+        toolPolicy?: RunnerDeps["toolPolicy"];
+        hooks?: RunnerDeps["hooks"];
+    };
+    /** Fire `RunnerDeps.onTaskOutcome` through the swallow-guarded chokepoint (thin compositions emit at their terminal state). */
+    emitTaskOutcome(outcome: TaskOutcome): void;
+    /** Run a task to completion. `internals` is the TRUSTED run-scoped channel (never a TaskSpec field). */
+    runTask(spec: TaskSpec, internals?: RunInternals): Promise<TaskResult>;
+    /** Streaming form of {@link RunnerSelfSeat.runTask}; `resume` is the run loop's resume plan, `internals` the trusted channel. */
+    runTaskStream(spec: TaskSpec, resume?: ResumeRun, internals?: RunInternals): TaskStream;
+    /** Resume a suspended task from its checkpoint token with the caller's decision, to completion. */
+    resume(token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, internals?: RunInternals): Promise<TaskResult>;
+    /** Streaming form of {@link RunnerSelfSeat.resume}: the pre-CAS guards and the CAS run first, then the live stream is returned. */
+    resumeStream(token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, internals?: RunInternals): Promise<TaskStream>;
+}

package/dist/core/runner/gate-exit.d.ts

@@ -1,16 +1,31 @@
 /**
- * The ONE mint of a {@link GateOutcome} — the record of what a tool-gate pass decided, what ask it settled
- * and who asked. The gate accumulates two facts on its way to an exit (WHO refused, written once at the
- * refusing site; WHAT was settled, written at the resolution site) and hands them here; this module
- * assembles the record, runs the invariant screen, and refuses a record the engine composed wrong. Every
- * projection of the outcome (the deny observer's payload, the call's `tool_end` frame, the engine's
- * per-call sideband) is the object minted here, never a re-derivation.
+ * The tool gate's RECORD FLOOR — everything about how one gate pass is recorded and how it ends:
  *
- * A machinery module on the prepare path's first stratum: it reaches down for the vocabulary only.
+ *  - the ONE mint of a {@link GateOutcome} ({@link mintGateOutcome}) — the record of what a tool-gate pass
+ *    decided, what ask it settled and who asked. The gate accumulates two facts on its way to an exit (WHO
+ *    refused, written once at the refusing site; WHAT was settled, written at the resolution site) and hands
+ *    them here; the mint assembles the record, runs the invariant screen, and refuses a record the engine
+ *    composed wrong. Every projection of the outcome (the deny observer's payload, the call's `tool_end`
+ *    frame, the engine's per-call sideband) is the object minted here, never a re-derivation;
+ *  - the settlement LEDGER of a pass ({@link createSettlementLedger}) — the one rule every attestation read
+ *    goes through;
+ *  - the PASS RECORD ({@link GatePass}) — the per-call cells the gate's station groups read and write, and
+ *    the hook-machinery seats they borrow, built once per call by `runToolGate` and handed to every station;
+ *  - the EXITS — the two phase-1 short-circuits ({@link engineFailClosedExit}, {@link hookDenyExit}) and the
+ *    single deny / allow exit of the adjudicate chain ({@link exitGate}), the only places a pass turns into a
+ *    `ToolGateResult`; plus the two observer-facing helpers every exit uses (the payload isolation clone and
+ *    the deployment-lane crash report).
+ *
+ * A floor module (layer 0 of the prepare/run path): the two station modules (`gate-fold.ts`, `gate-lanes.ts`)
+ * and the gate's dispatch in `hooks.ts` all reach DOWN for it, and it reaches down only for the vocabulary,
+ * the reminder envelope and the text helpers. Its `import type` edges up to `hooks.ts` name the gate's public
+ * contract (`ToolGateInput`, `ToolGateResult`, the observer payload), which stays declared there.
  */
 import { type DeniedBy, type GateOutcome, type Settlement } from "../gate-outcome.js";
-import type { AskOrigin } from "../ask-origin.js";
-import { type PermissionResult, type ResolvedAsk } from "../tool-policy.js";
+import type { AskOrigin, AskOriginFacts } from "../ask-origin.js";
+import { type PermissionResult, type ResolvedAsk, type ToolCallRequest } from "../tool-policy.js";
+import type { SafeNotifier } from "../safe-notify.js";
+import type { HookSeatOutcome, PermissionDeniedPayload, PreToolUseResult, ToolGateInput, ToolGateResult } from "../hooks.js";
 /** The ask a gate pass settled, as the gate captured it at its resolution site: the settlement the
  *  resolver composed and the origin word the ask carried. Both or neither (invariant I1). */
 export interface SettledAsk {
@@ -72,3 +87,156 @@ export declare function createSettlementLedger(call: {
     toolCallId: string;
     toolName: string;
 }): SettlementLedger;
+/**
+ * 1.256 复审 MED-1 — observe-only payload isolation for {@link import("../hooks.js").Hooks.permissionDenied}:
+ * clone the tool args before they ride the observer payload, so a hook mutating `payload.input` can never
+ * pollute the LIVE args object (later events / audit records share it). Same posture as the postToolUseFailure
+ * details clone (the gate-stations phase): `structuredClone` first; a non-structured-cloneable graph
+ * (functions/handles) falls back to a SHALLOW plain object/array copy (top-level mutation isolated);
+ * a non-object primitive passes through as-is (immutable anyway).
+ */
+export declare function cloneObserverInput(input: unknown): unknown;
+/** RB-442: hand the crash itself to the deployment's trace lane (`onError(phase:"hook")`), never letting a
+ *  throwing sink alter the fail-closed outcome — the same swallow posture as every other observer here.
+ *  Shared by the gate's dispatch (the phase-1 crash arm, the seat-bound refusal), the reversibility probe's
+ *  two failure arms and the approved-edit re-screen. */
+export declare function traceHookCrash(input: ToolGateInput, err: unknown, notifier: SafeNotifier): void;
+/**
+ * The PreToolUse screening face as the gate's stations see it — the hook machinery of `runToolGate` (the seat
+ * runner, the per-call seat bound, the fresh per-screening context, the result screen, the two fail-closed
+ * reason texts) behind three methods, so the approved-edit re-screen in the lanes runs the SAME screening the
+ * phase-1 pass ran without the lanes module reaching into the hook machinery. Present on the pass exactly when
+ * a `preToolUse` face is wired.
+ */
+export interface PreToolUseScreening {
+    /** Run the deployment's PreToolUse face over `args` under the seat bound. The answer is the SEAT's, unscreened —
+     *  the caller passes it through {@link PreToolUseScreening.screened} in the seat's own continuation. The seat
+     *  promise is returned as is (no wrapping `async`): what the gate does after the face answers — the policy in
+     *  phase 1, the re-check in the edit chain — runs on the tick the seat settles, as it did when this call was the
+     *  seat runner's own; a wrapper that screened the answer inside a second `async` cost one more tick there. An
+     *  expired seat is reported, not thrown; a crashing face rejects. */
+    screen(args: unknown): Promise<HookSeatOutcome<PreToolUseResult | undefined>>;
+    /** The result screen over an answered seat's value: an out-of-contract decision becomes the ordinary hook deny. */
+    screened(answer: PreToolUseResult | undefined): PreToolUseResult | undefined;
+    /** The model-facing text for a face that THREW while screening `subject`. */
+    crashReason(subject: string, err: unknown): string;
+    /** The model-facing text for a face that never ANSWERED while screening `subject` (the timeout arm also
+     *  reports on the deployment lane; a task-abort expiry does not). */
+    unansweredReason(subject: string, cause: "timeout" | "aborted"): Promise<string>;
+}
+/**
+ * ONE gate pass — the record the station groups (`runGateFold`, `runGateLanes`) and the exits read and write,
+ * built once per call by `runToolGate` before the screening pass. What used to be the closure-captured `let`
+ * cells of a 1 500-line function are its MUTABLE cells (each written by the station named on it, read by the
+ * ones after); what the stations borrow from the hook machinery are its SEATS (fixed for the pass). Ownership
+ * classes follow the phase-Input convention: `borrowed-readonly` = fixed for the pass, the stations only read
+ * it; `borrowed-mutable` = a cell a station writes.
+ */
+export interface GatePass {
+    /** borrowed-readonly — the gate's input: every deployment seat the stations read by name (`egress`,
+     *  `orgRules`, `persistedRules`, `autoMode`, …), and the identity / reminder mark the exits stamp. */
+    readonly input: ToolGateInput;
+    /** borrowed-readonly — the gate's event, read ONCE at entry (the dispatch's entry destructure): the exit compares the
+     *  final args against THIS event's input, never against a re-read of the input record. */
+    readonly event: ToolGateInput["event"];
+    /** borrowed-readonly — the deployment's policy face, captured ONCE at entry before the screening pass. The fold
+     *  adjudicates through it and the edit chain re-adjudicates through the SAME binding: a stateful accessor on the
+     *  input cannot hand the fold one policy and the approved-edit re-check another (or none). */
+    readonly adjudicate: ToolGateInput["adjudicate"];
+    /** borrowed-readonly — the ask resolver, captured ONCE at entry (same rule: the first-round resolution and the edit
+     *  round's re-ask resolve through one binding). */
+    readonly resolveAsk: ToolGateInput["resolveAsk"];
+    /** borrowed-readonly — the durable park closure, captured ONCE at entry (the three park sites hand it the same
+     *  thirteen seats; presence is judged off this one read). */
+    readonly suspendAsk: ToolGateInput["suspendAsk"];
+    /** borrowed-readonly — `input.event.toolName`, read once. */
+    readonly toolName: string;
+    /** borrowed-readonly — `input.event.toolCallId`, read once. */
+    readonly toolCallId: string;
+    /** borrowed-readonly — design/384: ONE read of the per-call signal for the whole gate call (the one-read
+     *  discipline the settlement screen already states): every conditional seat invocation (the three wait
+     *  seats plus the three suspendAsk park sites) judges presence and passes the value from this same cell, so
+     *  a stateful accessor cannot answer the arity check with a signal and the call with something else. */
+    readonly callSignal: AbortSignal | undefined;
+    /** borrowed-readonly — RB-463: the one host-callback isolation scope of this gate call (the deny observer,
+     *  the hook-error trace sink, the org and rule lanes' disclosure sinks). */
+    readonly notifier: SafeNotifier;
+    /** borrowed-readonly — the settlement LEDGER of this pass (the binding is fixed; the ledger's own methods
+     *  are how the resolution sites write it — one rule per read, see {@link createSettlementLedger}). */
+    readonly ledger: SettlementLedger;
+    /** borrowed-readonly — the ONE emission seat of the deny observer for this pass, bounded and contained like
+     *  every other seat (the hook machinery owns the seat runner; the exits call this). */
+    readonly notifyPermissionDenied: (payload: Omit<PermissionDeniedPayload, "signal">) => Promise<void>;
+    /** borrowed-readonly — the PreToolUse screening face ({@link PreToolUseScreening}), or undefined when no
+     *  `preToolUse` face is wired (the edit chain then re-screens nothing, as before). */
+    readonly screening: PreToolUseScreening | undefined;
+    /** borrowed-readonly — the station group that runs AFTER the fold (the lanes: org layer, rule lane, classifier,
+     *  parks, resolution, edit chain, and the exit they end in), handed the pass by the fold's LAST station on the
+     *  fold's own completing tick. A seat rather than an import because the two station modules sit on one layer
+     *  and may not name each other; a seat rather than a second `await` in the dispatch because that await is a
+     *  suspension point of its own: the org face and the rule store read HOST state the host may refresh
+     *  concurrently, and the tick on which they are consulted is the contract — when the station bodies were one
+     *  function, the org face was invoked in the same continuation that ran the last tighten, and a refresh queued
+     *  behind the policy's answer could not land in between. Returns the gate result (a park's suspension or the
+     *  exit's record). Writer: the dispatch (`runToolGate`, which wires `runGateLanes`). Reader: the fold's tail. */
+    readonly afterFold: (pass: GatePass) => Promise<ToolGateResult>;
+    /** borrowed-mutable — the FINAL args: the model's input, rewritten by the phase-1 hook, by the policy
+     *  rewrite on the ask path, by the content-ask lane's presented snapshot and by the exits' rewrite fold.
+     *  Writers: the dispatch (phase 1), the lanes, the exits. */
+    currentInput: unknown;
+    /** borrowed-mutable — the adjudication request. Minted over the model's input so the record is whole from
+     *  the first station, and RE-MINTED by the adjudication station over the FINAL post-screen args (the
+     *  pre-existing `const req` site); `args` is re-pointed at the policy rewrite on the ask path and at the
+     *  content-ask lane's presented snapshot. Writers: the fold (mint), the lanes (`args`). */
+    req: ToolCallRequest;
+    /** borrowed-mutable — the PreToolUse `additionalContext` collected for this call (pushed into; the binding
+     *  is fixed). Writers: the dispatch (phase 1), the lanes (sandbox admission note, the edit re-screen). */
+    readonly preToolContext: string[];
+    /** borrowed-mutable — the phase-1 hook's ASK, remembered for the fold. Only ever an ask (assigned under the
+     *  `r.action === "ask"` arm); typed as the narrowed member so the fold's reconstruction reads the ask-only
+     *  fields without a runtime re-test that could, if it ever failed, silently skip the promotion (i.e. loosen).
+     *  Writer: the dispatch (phase 1). Readers: the fold, the sandbox-admission conjunct. */
+    hookAsk: Extract<PermissionResult, {
+        action: "ask";
+    }> | undefined;
+    /** borrowed-mutable — set by a park attempt that FAILED (see `ParkAttemptFailed`). Read at the single deny
+     *  exit — whatever the fallback chain then decides to say, it says it knowing the park was tried first.
+     *  Writers: the three park sites. */
+    parkFailed: string | undefined;
+    /** borrowed-mutable — WHO refused, written ONCE by the refusing site (a direct policy / org / classifier
+     *  deny, a hook re-screen refusal, the write-protection re-judge, the edit chain's cap, an ask resolution
+     *  that ended as a refusal). The exit mints the outcome from it beside the ledger's `settled`; a refusal
+     *  that reaches the exit without it is an engine defect and the mint throws. */
+    deniedBy: DeniedBy | undefined;
+    /** borrowed-mutable — the standing verdict. The no-policy default until the adjudication station writes the
+     *  policy's answer; then rewritten by every station that changes the verdict (fold, tightens, org, rule
+     *  lane, stamp, classifier, sandbox, content lane, resolution, edit chain). */
+    decision: PermissionResult;
+    /** borrowed-mutable — which of the gate's OWN post-fold tightens minted the standing ask, if one did — an
+     *  input of the ask-origin derivation (`AskOriginFacts.tightened`). Written at most once per pass: every
+     *  tighten fires only over a surviving `allow`, and the first one to fire leaves an `ask` the others do not
+     *  touch. Recorded by the gate rather than read off `decisionReason` because that member is a policy's to
+     *  compose (a policy stamping `"safety"` on its own ask must read as `policy`). Writer: the fold. */
+    tightenedBy: AskOriginFacts["tightened"];
+    /** borrowed-mutable — the rewrite remembered BEFORE a hook-ask promotion / tighten, re-applied on the
+     *  approved path (a redaction is not cancelled because a person confirmed). Writer: the fold. Readers: the
+     *  fold's probe and write-protection judges, the lanes, the allow exit. */
+    policyRewrite: unknown;
+}
+/**
+ * The engine's fail-closed block of phase 1 — the PreToolUse face THREW or never ANSWERED, so the engine
+ * decides, on its own rule, that the call does not run. design/134 R5 BOUNDARY (deliberate asymmetry with
+ * {@link hookDenyExit} — do NOT unify the two): a hook `deny` is the HOOK's decision and the observer
+ * exclusion covers it; a crash / an unanswered seat produces no decision at all, so the deny OBSERVER fires
+ * here — an attribution channel whose job is "why was this call denied" must see an engine deny, or the
+ * deployment's only evidence of a broken hook is a tool that mysteriously stops working.
+ */
+export declare function engineFailClosedExit(pass: GatePass, reason: string): Promise<ToolGateResult>;
+/** The hook's OWN deny in phase 1. design/134 R5: a PreToolUse hook deny does NOT fire `permissionDenied`
+ *  (the exclusion recorded on `Hooks.permissionDenied`) — this return stays observer-free. */
+export declare function hookDenyExit(pass: GatePass, r: PreToolUseResult): ToolGateResult;
+/**
+ * The exit of the adjudicate chain — the pass has a standing `deny` or `allow` (every ask was resolved or
+ * parked before this), and this is where it becomes the gate result and the ONE record of the pass.
+ */
+export declare function exitGate(pass: GatePass): Promise<ToolGateResult>;