@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/caching-session-store.d.ts

@@ -1,18 +1,42 @@
 import type { AcquiredSession, SessionStore, SessionTreeEntry } from "@sema-agent/core";
 import type { SessionListItem } from "../security.js";
 export interface CachingOptions {
+    /** Idle seconds a woken session is kept warm. 0 disables caching (pure passthrough). */
     ttlSec: number;
     sweepIntervalMs?: number;
+    /** S25 (SILENT-FALLBACK P1): called when a cross-instance write (import/replace) evicts a WARM entry —
+     *  the affinity-contract violation signal that previously had zero fingerprint. */
     onConflictEvict?: (sessionId: string) => void;
 }
+/**
+ * Warm/sticky cache in front of a durable {@link SessionStore} (Option A).
+ *
+ * Keeps a woken session in memory and **reuses the same storage instance across turns**, so a hot
+ * session is not re-read from TiDB every short turn (treats the cattle like a warm pet while it's
+ * active). Idle sessions expire after `ttlSec`; `release` evicts immediately.
+ *
+ * ⚠️ **Session affinity is REQUIRED** when this cache is enabled (`SESSION_CACHE_TTL_SEC>0`): route a
+ * given sessionId to the same instance. Under affinity the cached storage is the sole writer, so its
+ * in-memory leaf is always current and consistent with TiDB (write-through; F2 CAS still applies).
+ * Without affinity a concurrent write from another instance makes this cache stale; that surfaces as
+ * a `SessionError("conflict")` on the next append — the async run driver calls `evict()` on conflict
+ * (defense-in-depth) and the entry also expires after `ttlSec`, but those are backstops, not the
+ * guarantee. If you cannot guarantee affinity, set `SESSION_CACHE_TTL_SEC=0` to disable the cache.
+ *
+ * Orthogonal to the F3 branch-floor change: floor bounds the *cold wake* size; this cache removes
+ * *repeated* re-reads of an active session.
+ */
 export declare class CachingSessionStore implements SessionStore {
     private readonly inner;
     private readonly cache;
     private readonly pending;
     private readonly ttlMs;
     private readonly timer?;
+    /** Delegated tenant-ownership ops, present only if the inner store exposes them (the TiDB store does). */
     readonly ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
     readonly register?: (sessionId: string, owner: string | null) => Promise<void>;
+    /** Delegated SessionRepo seam (§0.5) — list/fork/delete operate on the DURABLE tables directly (they bypass the
+     *  warm cache by design; a fork/delete must read/write durable state, not a possibly-stale cached view). */
     readonly listSessions?: (opts: {
         owner?: string;
         cursor?: {
@@ -24,22 +48,39 @@ export declare class CachingSessionStore implements SessionStore {
     }) => Promise<SessionListItem[]>;
     readonly fork?: (sourceId: string, owner: string | null) => Promise<string | null>;
     readonly deleteSession?: (sessionId: string, owner: string | null) => Promise<boolean>;
+    /** K-5c (core 1.155 SessionStore.noteTaskRun seam) — core's Runner calls it at runTask START to record the latest
+     *  run per session (→ listSessions `lastRunId`). MUST be forwarded: the local backend's Runner store is THIS cache
+     *  wrapper, so without forwarding `noteTaskRun?.()` silently no-ops and lastRunId stays null (review BLOCKER). Pure
+     *  pass-through to the inner store's in-mem map — no cache interaction. (TiDB/PG don't implement it → not bound.)
+     *  Return type matches core's `SessionStore.noteTaskRun?(): void | Promise<void>` (review: don't narrow to void). */
     readonly noteTaskRun?: (sessionId: string, taskId: string) => void | Promise<void>;
+    /** Write-once auto-title (SQL twins + local sidecar carry it; pure pass-through). */
     readonly setTitleIfNull?: (sessionId: string, title: string) => Promise<boolean>;
     readonly probeTitle?: (sessionId: string) => Promise<"none" | "untitled" | "titled">;
+    /** E18 — delegate the leaf read straight to inner (a cache-bypassing single SELECT; the resume-at turn-capture
+     *  reads the DURABLE leaf, not a possibly-stale cached view — same discipline as the §0.5 repo ops above). */
     readonly getLeafId?: (sessionId: string) => Promise<string | null>;
+    /** [1196] 六轮复审:owner+leafId 原子快照透传(cache-bypassing,getLeafId 同姿势)。 */
     readonly getHead?: (sessionId: string) => Promise<{
         owner: string | null;
         leafId: string | null;
     } | undefined>;
+    /** 2c session-sync — delegated export/import seam, DURABLE (bypasses the warm cache exactly like
+     *  list/fork: an export reads the full durable log, an import writes durable state). */
     readonly exportEntries?: (sessionId: string) => Promise<SessionTreeEntry[] | null>;
+    /** 2c session-sync P1d-α (PULL streaming) — delegated ids-only projection + keyset-paged entry STREAM, DURABLE
+     *  (read straight from the durable log, bypassing the warm cache, like exportEntries). The stream's per-batch query
+     *  discipline (one pooled query per page) lives in the inner store; this wrapper just forwards. */
     readonly listEntryIds?: (sessionId: string) => Promise<string[] | null>;
     readonly exportEntriesStream?: (sessionId: string, opts?: {
         afterSeq?: number;
         batchSize?: number;
     }) => Promise<AsyncIterable<SessionTreeEntry> | null>;
+    /** 轴A #1(1.254):core B-17 forget 面(evict 本地 + 转发 inner 可选面)。 */
     forget?: (sessionId: string) => void | Promise<void>;
     readonly importEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
+    /** 2c session-sync (§7/§8) — delegated IDEMPOTENT replace; like importEntries it writes durable state under
+     *  `sessionId`, so a stale warm handle for that id is evicted on success (next acquire re-wakes from the new log). */
     readonly replaceEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
     constructor(inner: SessionStore, opts: CachingOptions);
     acquire(sessionId?: string, opts?: {
@@ -47,6 +88,7 @@ export declare class CachingSessionStore implements SessionStore {
     }): Promise<AcquiredSession>;
     touch(sessionId: string): Promise<void>;
     release(sessionId: string): Promise<void>;
+    /** Drop a session from the warm cache (e.g. after a cross-instance write conflict). */
     evict(sessionId: string): void;
     get size(): number;
     dispose(): void;

package/dist/plugins/caching-session-store.js

@@ -1,24 +1,62 @@
+/**
+ * Warm/sticky cache in front of a durable {@link SessionStore} (Option A).
+ *
+ * Keeps a woken session in memory and **reuses the same storage instance across turns**, so a hot
+ * session is not re-read from TiDB every short turn (treats the cattle like a warm pet while it's
+ * active). Idle sessions expire after `ttlSec`; `release` evicts immediately.
+ *
+ * ⚠️ **Session affinity is REQUIRED** when this cache is enabled (`SESSION_CACHE_TTL_SEC>0`): route a
+ * given sessionId to the same instance. Under affinity the cached storage is the sole writer, so its
+ * in-memory leaf is always current and consistent with TiDB (write-through; F2 CAS still applies).
+ * Without affinity a concurrent write from another instance makes this cache stale; that surfaces as
+ * a `SessionError("conflict")` on the next append — the async run driver calls `evict()` on conflict
+ * (defense-in-depth) and the entry also expires after `ttlSec`, but those are backstops, not the
+ * guarantee. If you cannot guarantee affinity, set `SESSION_CACHE_TTL_SEC=0` to disable the cache.
+ *
+ * Orthogonal to the F3 branch-floor change: floor bounds the *cold wake* size; this cache removes
+ * *repeated* re-reads of an active session.
+ */
 export class CachingSessionStore {
     inner;
     cache = new Map();
     pending = new Map();
     ttlMs;
     timer;
+    /** Delegated tenant-ownership ops, present only if the inner store exposes them (the TiDB store does). */
     ownerOf;
     register;
+    /** Delegated SessionRepo seam (§0.5) — list/fork/delete operate on the DURABLE tables directly (they bypass the
+     *  warm cache by design; a fork/delete must read/write durable state, not a possibly-stale cached view). */
     listSessions;
     fork;
     deleteSession;
+    /** K-5c (core 1.155 SessionStore.noteTaskRun seam) — core's Runner calls it at runTask START to record the latest
+     *  run per session (→ listSessions `lastRunId`). MUST be forwarded: the local backend's Runner store is THIS cache
+     *  wrapper, so without forwarding `noteTaskRun?.()` silently no-ops and lastRunId stays null (review BLOCKER). Pure
+     *  pass-through to the inner store's in-mem map — no cache interaction. (TiDB/PG don't implement it → not bound.)
+     *  Return type matches core's `SessionStore.noteTaskRun?(): void | Promise<void>` (review: don't narrow to void). */
     noteTaskRun;
+    /** Write-once auto-title (SQL twins + local sidecar carry it; pure pass-through). */
     setTitleIfNull;
     probeTitle;
+    /** E18 — delegate the leaf read straight to inner (a cache-bypassing single SELECT; the resume-at turn-capture
+     *  reads the DURABLE leaf, not a possibly-stale cached view — same discipline as the §0.5 repo ops above). */
     getLeafId;
+    /** [1196] 六轮复审:owner+leafId 原子快照透传(cache-bypassing,getLeafId 同姿势)。 */
     getHead;
+    /** 2c session-sync — delegated export/import seam, DURABLE (bypasses the warm cache exactly like
+     *  list/fork: an export reads the full durable log, an import writes durable state). */
     exportEntries;
+    /** 2c session-sync P1d-α (PULL streaming) — delegated ids-only projection + keyset-paged entry STREAM, DURABLE
+     *  (read straight from the durable log, bypassing the warm cache, like exportEntries). The stream's per-batch query
+     *  discipline (one pooled query per page) lives in the inner store; this wrapper just forwards. */
     listEntryIds;
     exportEntriesStream;
+    /** 轴A #1(1.254):core B-17 forget 面(evict 本地 + 转发 inner 可选面)。 */
     forget;
     importEntries;
+    /** 2c session-sync (§7/§8) — delegated IDEMPOTENT replace; like importEntries it writes durable state under
+     *  `sessionId`, so a stale warm handle for that id is evicted on success (next acquire re-wakes from the new log). */
     replaceEntries;
     constructor(inner, opts) {
         this.inner = inner;
@@ -37,7 +75,7 @@ export class CachingSessionStore {
         if (ownerAware.fork)
             this.fork = ownerAware.fork.bind(inner);
         if (ownerAware.noteTaskRun)
-            this.noteTaskRun = ownerAware.noteTaskRun.bind(inner);
+            this.noteTaskRun = ownerAware.noteTaskRun.bind(inner); // K-5c: pass-through so the Runner's noteTaskRun reaches the inner map (review BLOCKER fix)
         if (ownerAware.getLeafId)
             this.getLeafId = ownerAware.getLeafId.bind(inner);
         if (ownerAware.getHead)
@@ -48,29 +86,39 @@ export class CachingSessionStore {
             this.listEntryIds = ownerAware.listEntryIds.bind(inner);
         if (ownerAware.exportEntriesStream)
             this.exportEntriesStream = ownerAware.exportEntriesStream.bind(inner);
+        // 历史复审轴A #1(1.254,core B-17 缝):core prepare-task 在 reconcile 冲突重试/prepare-throw 清理时
+        // 调 `sessions.forget?.()`,缺席=无 fallback(B-17 判例:绝不代之以 release)——本店此前无 forget,
+        // tidb+cache 形态下运行内冲突自愈失效(暖缓存命中同一 stale 实例→重试预算耗尽→该 run 以 conflict 败;
+        // runs.ts evictIfConflict 只兜 run 后)。补齐=evict 本地缓存 + 转发 inner 可选面(fork-routing 店同款)。
         this.forget = (sessionId) => {
             this.evict(sessionId);
             return inner.forget?.(sessionId);
         };
         if (ownerAware.importEntries) {
+            // An import writes durable state under `sessionId`; if a stale handle for that id is warm, drop it so the
+            // next acquire re-wakes from the freshly-imported durable log (mirrors the deleteSession evict discipline).
             const imp = ownerAware.importEntries.bind(inner);
             this.importEntries = async (sessionId, owner, entries) => {
                 await imp(sessionId, owner, entries);
                 if (this.cache.has(sessionId))
-                    opts.onConflictEvict?.(sessionId);
+                    opts.onConflictEvict?.(sessionId); // S25: a warm entry was live → stale-affinity fingerprint
                 this.evict(sessionId);
             };
         }
         if (ownerAware.replaceEntries) {
+            // A replace REWRITES durable state under `sessionId` (purge + re-import); evict any warm handle so the next
+            // acquire re-wakes from the replaced log (same discipline as importEntries / deleteSession above).
             const rep = ownerAware.replaceEntries.bind(inner);
             this.replaceEntries = async (sessionId, owner, entries) => {
                 await rep(sessionId, owner, entries);
                 if (this.cache.has(sessionId))
-                    opts.onConflictEvict?.(sessionId);
+                    opts.onConflictEvict?.(sessionId); // S25
                 this.evict(sessionId);
             };
         }
         if (ownerAware.deleteSession) {
+            // A durable delete must also drop the deleted session from THIS warm cache (else a stale cached handle
+            // could keep serving a purged session until its idle TTL). Wrap to evict on success.
             const del = ownerAware.deleteSession.bind(inner);
             this.deleteSession = async (sessionId, owner) => {
                 const removed = await del(sessionId, owner);
@@ -93,9 +141,20 @@ export class CachingSessionStore {
         }
         const hit = this.cache.get(sessionId);
         if (hit) {
+            // A warm cache hit means the session EXISTS → it satisfies `requireExisting` (no need to re-open the durable
+            // log). design/114 Phase3: the fail-loud only ever fires on a genuinely-missing (uncached) session below.
+            // 🟡 Affinity caveat (doc-as-intentional, LOW): under the REQUIRED session affinity (see the class header), the
+            // cached instance is the sole writer, so a warm handle can't be stale w.r.t. a purge — a same-instance E21
+            // delete evicts this entry (deleteSession wrapper). Only an out-of-band / cross-instance purge that VIOLATES
+            // affinity could leave a stale hit that satisfies requireExisting until the idle TTL expires. Bypassing the
+            // cache for strict acquires would add a DB round-trip to EVERY warm-resume (the hot path) to close an
+            // affinity-violation-only window — not worth it; the affinity contract already governs cross-instance writes.
             hit.expiresAt = Date.now() + this.ttlMs;
             return hit.acquired;
         }
+        // design/114 Phase3 (F1): a `requireExisting` acquire can REJECT (not_found) and never creates — it MUST bypass
+        // the shared create-dedup `pending`, else a concurrent create-capable waiter would inherit the not_found rejection
+        // instead of creating-on-miss. Forward the option to the inner (durable) store, which does the fail-loud.
         if (opts?.requireExisting) {
             const a = await this.inner.acquire(sessionId, opts);
             this.store(a);
@@ -124,6 +183,7 @@ export class CachingSessionStore {
         this.cache.delete(sessionId);
         await this.inner.release(sessionId);
     }
+    /** Drop a session from the warm cache (e.g. after a cross-instance write conflict). */
     evict(sessionId) {
         this.cache.delete(sessionId);
     }

package/dist/plugins/checkpoint-store-sql.d.ts

@@ -2,23 +2,64 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type Checkpoint, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor } from "@sema-agent/core";
 import { type SqlDriver } from "./sql-driver.js";
+/**
+ * design/80 D-1 (§3 invariant #3 — crash-safe reaper backstop): an ABSOLUTE upper bound on a pending
+ * checkpoint's lifetime, stamped at put() into `terminal_at` INDEPENDENT of the per-approval `deadline`. The
+ * SLA-timer (D-D) does the fine, per-gate-kind resolve-deny; THIS coarse backstop ensures even a pending row
+ * with a NULL `deadline` (no approval TTL configured) is eventually GC'd if the SLA service dies — closing a
+ * forever-leak of a never-resolved suspension (the current `reap`/`reapExpired` only catch non-NULL deadlines).
+ * Generous (default 30d) so it never pre-empts a legitimately long-lived human/irreversible_ask gate;
+ * env-overridable. Clamped ≥1min so a misconfig can't expire live suspensions instantly.
+ */
 export declare const TERMINAL_BACKSTOP_MS: number;
+/**
+ * design/80 D-D (adversarial fix): the crash-safe `terminal_at` backstop must fall STRICTLY AFTER any SLA
+ * `deadline`, never AT it. `terminal_at = max(createdAt+backstop, deadline)` made the two coincide whenever an
+ * operator tuned APPROVAL_TERMINAL_BACKSTOP_MS at/below the SLA — and reapExpired's terminal_at-branch (which
+ * has NO gate_kind filter) then abort-EXPIRED a human/irreversible_ask gate in the SAME tick the deny-sweep
+ * wanted to gracefully DENY it, racing it away. Adding this grace to the deadline term guarantees the deny-sweep
+ * at least this window of clean ticks before the absolute backstop can fire. Far smaller than the backstop, so
+ * it never meaningfully delays the eventual crash-safe GC.
+ */
 export declare const TERMINAL_GRACE_MS = 3600000;
+/**
+ * The capability token IS the resume credential (token-as-auth) — anyone who reads it can impersonate a
+ * resume, so it must never reach the logs (which fan out to a log-aggregation pipeline). For the diagnostic
+ * resume-read-path log we emit a stable, non-reversible fingerprint instead, enough to correlate get↔resolve.
+ */
 export declare function tokenFingerprint(token: string): string;
+/** Non-secret view of a pending checkpoint for the operator approval queue — deliberately NO token. */
 export interface PendingCheckpoint {
     sessionId: string;
     scope: string;
     toolName: string | null;
     toolCallId: string | null;
+    /** design/80 D-1: the decision-action binding fields the operator/portal must ECHO back on /decide so the
+     *  resume binds to the EXACT action they saw (a stale view is then rejected fail-closed PRE-CAS). `boundCallId`
+     *  === `toolCallId` (the pending tool call); `boundInputHash` is the server-minted opaque hash of the shown
+     *  input (NEVER recomputed by the portal — echoed verbatim). Surfacing them here is what makes the D-1 TOCTOU
+     *  guard REACHABLE by the portal (without it the portal can only do the unbound legacy fallback). `null` on a
+     *  pre-D-1 / legacy-deserialized checkpoint ⇒ the consumer falls back to the unbound resolve. */
     boundCallId: string | null;
     boundInputHash: string | null;
+    /** The suspended run's taskId (task_active join) — the key to the run/trace ("view task context"). */
     taskId: string | null;
+    /** The pending tool call's args (post-hook), redacted + bounded — for tool_approval the write payload, for a
+     *  durable AskUserQuestion the question itself. Lets the approval card render WITHOUT an N+1 trace.turns
+     *  fetch. `null` for pre-migration rows (suspended before the column existed) ⇒ consumer falls back. */
     input: unknown;
     createdAt: number;
     deadline: number | null;
+    /** design/80 riskDescriptor inbox: core's INERT triage descriptor ({severity 1-5, axes, toolName, redacted
+     *  summary, touchedPaths}) for human/irreversible_ask gates. listPending returns the queue severity-sorted
+     *  (DESC) so the supervisor inbox triages high-risk asks first. `null` for gates with no descriptor. */
     riskDescriptor: RiskDescriptor | null;
 }
+/** Redact + size-bound a pending tool call's args for persistence/serving. JSON-roundtrips so the stored shape
+ *  matches what the operator queue serves; oversized payloads collapse to a marker rather than bloating the row.
+ *  Exported for the LOCAL twin (local-checkpoint-store.ts) so the operator-queue projection can't drift. */
 export declare function boundedToolInput(args: unknown): unknown;
+/** Dual-dialect durable CheckpointStore. See the file header for the dialect-delta ledger. */
 export declare class SqlCheckpointStore implements CheckpointStore {
     protected readonly db: SqlDriver;
     protected readonly logger?: {
@@ -27,38 +68,176 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     constructor(db: SqlDriver, logger?: {
         info?(msg: string, meta?: unknown): void;
     } | undefined);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** JSON column binding: TiDB stores the string verbatim; PG goes through the LOSSLESS protocol envelope
+     *  (R4-H1 — the operator's review surface must agree with the executed args at the NUL position). */
     private json;
     private isDupKey;
+    /** Create-once. core mints the token (`mintCheckpointToken`) and calls this during suspend. */
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
     get(token: CheckpointToken): Promise<Checkpoint | null>;
+    /**
+     * Atomic CAS: pending → resolved, scoped. Returns true for the single winner, false if already
+     * resolved/expired (AlreadyResolved → caller no-ops, never re-executes). `outcome` is persisted atomically
+     * with the flip (R20 #1 — a future v2 resumable-resume can recover a crash-after-CAS; v1 runner write-only).
+     *
+     * design/80 D-1 (atomicity): the winner-persist (the full `outcome` is stored; the winner
+     * {boundCallId,decision,updatedInput?} is derived from it on read) + the `rev` bump happen ATOMICALLY in the
+     * SAME UPDATE as the pending→resolved CAS — one statement, no get→write window. When the caller passes the
+     * `rev` it observed at get() (ResolveExpectation), the CAS additionally requires the LIVE rev to still equal
+     * it: ANY intervening resolve/reopen cycle bumps rev, so a cycle in the get→resolve window loses the CAS
+     * (returns false → core re-inspects → checkpoint.reopened_concurrently). Omitting `expect` keeps the legacy
+     * unconditional CAS (a first resume of a never-reopened checkpoint is unconstrained by rev).
+     * 🔴 reopen_reason = NULL on a winning resolve — parity with the core reference InMemoryCheckpointStore
+     * (MINOR-12: "a freshly-resolved row carries no stale reopen reason"). Without this, an env_failed reopen
+     * followed by a correct winner-replay resolve leaves reopen_reason='env_failed' stale on the now-resolved
+     * row; a later DUPLICATE resume of that token would hit core's pre-CAS env_failed winner-replay guard
+     * against the stale reason and throw checkpoint.reopen_revote (which the service classifies RETRIABLE →
+     * re-parks the run suspended) instead of the terminal checkpoint.already_resolved — stranding the run.
+     */
     resolve(token: CheckpointToken, scope: string, outcome: ResumeOutcome, expect?: ResolveExpectation): Promise<boolean>;
+    /**
+     * Inverse of `resolve` (core `CheckpointStore.reopen`): CAS `resolved → pending`. Returns the CAS winner
+     * (true = was resolved → now pending again). Compensates a post-CAS env-restore failure
+     * (`resume.env_failed`): `resumeStream` consumes the checkpoint BEFORE `resumeVM`, so a restore failure
+     * would otherwise strand the suspended work as `resolved` + unfindable (`findPendingTokenBySession` only
+     * matches `pending`). Reopening lets a retry re-resume the SAME work.
+     *
+     * design/80 D-1 (reopen-by-reason): the `reason` distinguishes the two triggers (both fire at core's
+     * runtask.ts) so the re-resume can validate per reason (§3 inv #1) — `env_failed` = the action is still
+     * valid, the re-resume MUST replay the persisted winner (core rejects a different decision with
+     * `checkpoint.reopen_revote`); `tool_unavailable` = the action could not run and may now be stale, so a
+     * FRESH decision is allowed (P-7). We RECORD the reason on the row and bump `rev` (so a concurrent resume's
+     * resolve CAS loses — atomicity). 🔴 We DELIBERATELY leave the persisted `outcome` UNTOUCHED (NOT stale junk
+     * as a pre-D-1 reopen treated it): `resolvedOutcome` derives from it on get(), and an `env_failed` re-resume
+     * is validated against it — clearing it would defeat the winner-replay invariant.
+     */
     reopen(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
+    /**
+     * design/80 D-A (durable steering): park a steer message on a STILL-PENDING checkpoint (last-writer-wins),
+     * surfaced via get() as `state.pendingSteer` and injected on resume. CAS on `status='pending'` (+ scope) so a
+     * steer NEVER lands on a resolved/expired checkpoint and NEVER touches status/the resolve path (§3 inv #4).
+     * Returns the CAS winner (`true` = landed on a live pending checkpoint; `false` = no pending row to steer).
+     */
     setPendingSteer(token: CheckpointToken, scope: string, steer: {
         text: string;
         trusted: boolean;
     }): Promise<boolean>;
+    /**
+     * CAS-expire a SINGLE checkpoint by token (core 1.71 `CheckpointStore.expire`, for `TaskStream.destroy`'s
+     * suspended-worker reap — core [R33] {delta}). `pending → expired`, returns the CAS winner (true = we
+     * expired it; false = already resolved/expired). Same UPDATE as `reap`, keyed by **token** not deadline.
+     * It races the SAME `pending` row as `resolve`, so the two are mutually exclusive: destroy() must `expire`
+     * (fence) BEFORE destroying the env — if a concurrent resume already won `resolve`, expire returns false and
+     * destroy leaves the env for that resume; if expire wins, the resume's resolve fails → never resume-to-dead-env.
+     * Uses `expired` (not a `resolve`-deny) so a CANCELLED checkpoint never pollutes resolved-count / outcome.
+     */
     expire(token: CheckpointToken, scope: string): Promise<boolean>;
+    /** Interface reap: CAS-expire pending checkpoints in `scope` past `cutoff`. Returns count. */
     reap(scope: string, cutoff: number): Promise<number>;
+    /**
+     * GLOBAL sweep for the service's per-replica TTL reaper (expiry isn't tenant-
+     * sensitive — only `resolve` is scoped). Idempotent across replicas (DB serializes; no election). Returns count.
+     * Called with `cutoff = Date.now()` (deadline/terminal_at are ABSOLUTE epoch-ms), so it expires any pending row
+     * whose per-approval `deadline` OR its design/80 D-1 §3-inv#3 `terminal_at` crash-safe backstop has passed —
+     * the latter closes the forever-leak of a pending row with a NULL `deadline` (no approval TTL was configured).
+     *
+     * design/80 D-D: the deadline-branch EXPIRES (≈ abort) every kind EXCEPT a tool-approval human/irreversible_ask
+     * gate — those are resolve-DENIED gracefully by the SLA deny-sweep (listExpiredApprovalGates →
+     * resumeCheckpoint(deny)), so expiring them here too would race + lose the graceful denial. 🔴 A durable
+     * AskUserQuestion ALSO mints gate.kind='human' (no question-specific kind in core) — but DENYING a question is
+     * incoherent (the model gets a "denied" tool-result, not an answer), so it is carved BACK INTO the expire path
+     * (COALESCE(tool_name,'')='AskUserQuestion') to abort-expire on timeout instead. Legacy rows (gate_kind NULL)
+     * stay on the expire path. The terminal_at-branch is the crash-safe backstop for ANY kind (incl. a human gate
+     * whose deny-resume keeps failing) — it always abort-expires past the absolute cap (which is now STRICTLY after
+     * the deadline, so it never races the deny-sweep at the deadline instant).
+     */
     reapExpired(cutoff: number): Promise<number>;
+    /**
+     * design/80 D-D (SLA-timer): the sessions of pending human/irreversible_ask checkpoints past their `deadline`
+     * (the per-approval SLA). The reaper resolve-DENIES each (re-resume with decision=deny → the model continues
+     * with the denial) — graceful, vs the abort that expire() gives resource_limit/needs_review. Excludes legacy
+     * rows (gate_kind NULL — they predate the split and fall through to reapExpired's expire path). LIMIT bounds
+     * the per-tick deny-resume work (each is a model run). Scope is read off the COMMITTED row (invariant #4).
+     * 🔴 EXCLUDES AskUserQuestion gates (which also mint gate.kind='human'): denying a question is incoherent —
+     * the model would get a "denied" tool-result instead of an answer — so a timed-out durable question falls to
+     * reapExpired's abort-expire path instead of this graceful-deny path.
+     */
     listExpiredApprovalGates(cutoff: number, limit?: number): Promise<Array<{
         sessionId: string;
         scope: string;
     }>>;
+    /** Pending checkpoints for the operator queue — NON-secret fields only (never the token). `taskId` is
+     *  joined from task_active (the JOIN KEY to the run/trace — a suspended run KEEPS its
+     *  session claim, so the join is live for every pending row; null only in pathological windows). */
     listPending(scope?: string): Promise<PendingCheckpoint[]>;
+    /**
+     * design/80 #2 (scheduler seam, core 1.105): a scope's PENDING checkpoints as lightweight
+     * {@link CheckpointSummary} rows in ONE query — the cross-task triage view a supervisor scheduler needs
+     * (gate kind + risk severity + budget spent + deadline per suspended task), no N+1 `get`s. The projection is
+     * core's shared {@link summarizeCheckpoint} run over the persisted blob (the `checkpoint` column = the same full
+     * {@link Checkpoint} `get()` parses), so this stays byte-identical to core's InMemory/Pg/File impls. Order =
+     * created_at ASC; callers (the inbox/scheduler) sort by severity. The COLUMN `status` is authoritative (the blob
+     * is the suspend-time snapshot), so it overrides the blob's status before the summary is derived.
+     *
+     * LIMIT bounds the fan-out (review w16yqkkxv): a triage view never needs more than a few — 500 is a generous
+     * ceiling that still protects memory/latency if a scope ever accumulates pathologically many pending gates.
+     */
     listByScope(scope: string): Promise<CheckpointSummary[]>;
+    /**
+     * Map a session (the non-secret handle the operator decides by) → its single pending checkpoint token,
+     * INTERNALLY. A suspended session has exactly one pending checkpoint. `scope` is enforced so an operator
+     * can only resolve within its own tenant. Returns null if there is no pending checkpoint for that session/scope.
+     */
     findPendingTokenBySession(sessionId: string, scope?: string): Promise<CheckpointToken | null>;
+    /**
+     * The owner SCOPE of a session's pending checkpoint (the multi-tenant key === the owner principal in the
+     * BFF/non-operator flow, the same key listPending filters by). For the /decide owner-gate: a non-operator
+     * caller may only decide a checkpoint in their OWN scope. Returns `undefined` (no pending row), `null`
+     * (anonymous/dev session — open), or the owner scope string.
+     */
     peekPendingScope(sessionId: string): Promise<string | null | undefined>;
+    /** Upsert the resume rebuild inputs for a session (written at SUBMIT when durable mode is on). */
     putCtx(sessionId: string, ctx: unknown): Promise<void>;
     getCtx<T = unknown>(sessionId: string): Promise<T | null>;
+    /**
+     * GC ctx rows whose lifecycle is over (bound to the checkpoint, don't leak):
+     * a session with NO pending checkpoint, NO active run, AND not touched since `cutoff`.
+     *
+     * The extra `task_active` guard closes a multi-gate window: between a resume's CAS (pending→resolved) and
+     * the task hitting its NEXT gate (writing a new pending checkpoint), the session has no pending checkpoint —
+     * yet `putCtx` only stamps `updated_at` at submit, so the ctx could be older than `cutoff` and was being
+     * reaped, making the next resume 409 ("resume context missing"). `task_active` holds the session lock for
+     * the WHOLE submit→last-resume-complete span (running OR suspended), so excluding sessions with an active
+     * claim keeps the ctx exactly as long as a run still needs it, while still GC'ing it once the run is terminal.
+     */
     reapCtx(cutoff: number): Promise<number>;
+    /**
+     * E21 (§0.5 session delete) — purge ALL checkpoint state for one session: the durable checkpoint rows
+     * (suspended-task gates) AND their service-side resume-context rows (checkpoint_ctx). Keyed on the
+     * `session_id` column both tables carry. Idempotent (returns the count of `checkpoint` rows removed).
+     * Unconditional by design: a session being deleted has no resumable future, so any pending gate is moot.
+     *
+     * `owner` is a single-DB-fleet defense-in-depth guard (adversarial-review MEDIUM). Neither table carries an
+     * owner column, so the guard threads through `session_meta.owner` via an EXISTS sub-select (null-safe compare:
+     * `<=>` on TiDB, `IS NOT DISTINCT FROM` on PG). The purge coordinator runs this BEFORE deleting session_meta,
+     * so the meta row (with its authoritative owner) is still present here — a wrong-owner caller's EXISTS fails
+     * and purges nothing. `owner=null` (legacy/dev, never threaded by the route) keeps the historical
+     * unconditional behaviour via the null-safe match.
+     *
+     * 🔴 Placeholder ARITY differs, not just the syntax: `?` cannot be reused, so the TiDB arm binds `sessionId`
+     * TWICE (row key + guard sub-select) while PG reuses `$1`.
+     */
     deleteBySession(sessionId: string, owner: string | null): Promise<number>;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBCheckpointStore extends SqlCheckpointStore {
     constructor(pool: MySqlPool, logger?: {
         info?(msg: string, meta?: unknown): void;
     });
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgCheckpointStore extends SqlCheckpointStore {
     constructor(pool: PgPool, logger?: {
         info?(msg: string, meta?: unknown): void;