@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/checkpoint-store-sql.js

@@ -1,28 +1,85 @@
+/**
+ * Durable `CheckpointStore` (core 1.67 durable-checkpoint / design/45) — SINGLE-FILE DUAL-DIALECT
+ * (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical `TiDBCheckpointStore` /
+ * `PgCheckpointStore` class names survive as thin ctor subclasses so every consumer (store-backend.ts,
+ * local-checkpoint-store.ts, the chaos/ownership/blackbox suites) is untouched.
+ *
+ * This is the durable backend that makes a policy `ask` survive cross-replica/crash/time as a suspended
+ * task an operator can `resume` from any instance. It implements core's `CheckpointStore` (put create-once
+ * / get / atomic CAS resolve / reopen / reap), modeled on the proven approval-store CAS, plus two concerns
+ * the core interface doesn't own but the service does (DURABLE-CHECKPOINT-PLAN §4.4a):
+ *   - `checkpoint_ctx` (sessionId-keyed): the service-side scenario rebuild inputs for `resume`'s taskConfig —
+ *     core's `put(token, cp)` can't carry it (it's service "profile", not the generic core checkpoint).
+ *   - operator-queue helpers (`listPending` / `findPendingTokenBySession`) that surface NON-secret fields and
+ *     map a session → its pending token INTERNALLY — the capability token never leaves the service (token-as-auth).
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n` (and the OPTIONAL `AND rev = ?` / `AND rev = $5` OCC tail)
+ *   - `ON DUPLICATE KEY UPDATE … VALUES(col)` vs `ON CONFLICT (session_id) DO UPDATE SET … EXCLUDED.col`
+ *   - dup-key errno `1062` (ER_DUP_ENTRY) vs SQLSTATE `23505`
+ *   - null-safe owner compare: `<=>` vs `IS NOT DISTINCT FROM` — AND the parameter arity that follows
+ *     (`?` cannot be reused, so the TiDB deleteBySession binds sessionId TWICE; PG reuses `$1`)
+ *   - affectedRows vs rowCount (via SqlDriver)
+ *   - JSON binding: TiDB `JSON.stringify` verbatim vs PG `pgProtocolJsonStringify` + `$n::jsonb` casts.
+ *     PG's envelope is LOSSLESS (codex R4-H1): tool_input is the operator's review surface and must agree
+ *     with `checkpoint.pendingAction.args` at the NUL position — redact/truncate is the display contract,
+ *     byte rewriting is not.
+ *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL centrally in pg-pool.ts (neither store creates tables).
+ */
 import { createHash } from "node:crypto";
 import { CheckpointError, validatePendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, } from "@sema-agent/core";
 import { redactDeep } from "../trace/redact.js";
 import { pgProtocolJsonStringify } from "./pg-safe-json.js";
 import { parseJsonStrict as parseJson } from "./sql-row-helpers.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+/** Cap the persisted/served pending-approval args so a pathological tool payload can't bloat the checkpoint row
+ *  or the operator-queue response (the BFF renders this in an approval card; a few KB is plenty). */
 const MAX_TOOL_INPUT_CHARS = 8192;
+/**
+ * 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 const TERMINAL_BACKSTOP_MS = Math.max(60_000, Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) || 30 * 86_400_000);
-export const TERMINAL_GRACE_MS = 3_600_000;
+/**
+ * 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 const TERMINAL_GRACE_MS = 3_600_000; // exported for the LOCAL twin's read-time terminal_at derivation (anti-drift) // 1h — many reaper intervals of deny-sweep runway past the SLA deadline
+/**
+ * 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 function tokenFingerprint(token) {
     return "sha256:" + createHash("sha256").update(token).digest("hex").slice(0, 12);
 }
+/** 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 function boundedToolInput(args) {
     if (args === undefined)
         return null;
     const redacted = redactDeep(args);
     const json = JSON.stringify(redacted);
     if (json === undefined)
-        return null;
+        return null; // non-serializable (e.g. a bare function) — nothing to surface
     if (json.length > MAX_TOOL_INPUT_CHARS)
         return { truncated: true, bytes: json.length };
     return redacted;
 }
-const DUP_ENTRY = 1062;
+const DUP_ENTRY = 1062; // MySQL/TiDB ER_DUP_ENTRY
 const PG_UNIQUE_VIOLATION = "23505";
+/** Dual-dialect durable CheckpointStore. See the file header for the dialect-delta ledger. */
 export class SqlCheckpointStore {
     db;
     logger;
@@ -30,9 +87,12 @@ export class SqlCheckpointStore {
         this.db = db;
         this.logger = logger;
     }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
+    /** 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). */
     json(value, label) {
         return this.db.dialect === "tidb" ? JSON.stringify(value) : pgProtocolJsonStringify(value, label);
     }
@@ -41,9 +101,12 @@ export class SqlCheckpointStore {
             ? e?.errno === DUP_ENTRY
             : e?.code === PG_UNIQUE_VIOLATION;
     }
+    /** Create-once. core mints the token (`mintCheckpointToken`) and calls this during suspend. */
     async put(token, cp) {
         const pa = cp.pendingAction;
-        const version = checkpointVersionOf(cp);
+        const version = checkpointVersionOf(cp); // core helper: cp.version ?? 0 (1.67/1.68-era no-field = legacy 0)
+        // Persist the (redacted, bounded) tool args alongside so the operator queue can serve the approval-card
+        // payload without an N+1 trace.turns fetch. Stored as a stringified JSON column value.
         const toolInput = boundedToolInput(pa?.args);
         try {
             await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at, terminal_at, gate_kind, bound_input_hash, risk_descriptor) " +
@@ -59,14 +122,15 @@ export class SqlCheckpointStore {
                 this.json(cp, "checkpoint"),
                 cp.deadline ?? null,
                 cp.createdAt,
-                Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS),
-                cp.gate?.kind ?? null,
-                pa?.boundInputHash ?? null,
-                ((g) => (g?.riskDescriptor ? this.json(g.riskDescriptor, "risk descriptor") : null))(cp.gate),
+                Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS), // D-1 §3 inv#3 backstop — STRICTLY after any SLA deadline (grace) so the terminal_at-branch never races the D-D deny-sweep, and never pre-empts an operator's longer TTL
+                cp.gate?.kind ?? null, // D-D SLA split: human/irreversible_ask deadline → resolve-deny; others → expire
+                pa?.boundInputHash ?? null, // D-1: the opaque hash the portal must echo on /decide (surfaced via listPending so the TOCTOU binding is reachable)
+                ((g) => (g?.riskDescriptor ? this.json(g.riskDescriptor, "risk descriptor") : null))(cp.gate), // riskDescriptor inbox: stamp core's INERT descriptor for triage-sort
             ]);
         }
         catch (e) {
             if (this.isDupKey(e)) {
+                // a reused token would clobber a live suspension — never a silent overwrite (checkpoint-store contract)
                 throw new CheckpointError("checkpoint.already_exists", `checkpoint token already exists`);
             }
             throw e;
@@ -77,22 +141,37 @@ export class SqlCheckpointStore {
         const r = rows[0];
         if (!r)
             return null;
+        // Forward-compat guard: never hand a too-new checkpoint to a resume that can't
+        // parse it. Compare with `<= MAX` (never `=== CURRENT`) using core's exported constant so this
+        // stays aligned when core bumps the format. This durable-store get-path is the STRONGEST guard (protects a
+        // worker that doesn't check version itself); core's resume has a second pre-CAS guard.
         const version = Number(r.version);
         if (version > MAX_SUPPORTED_CHECKPOINT_VERSION) {
             throw new Error(`checkpoint format version ${version} is newer than this build supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION}) — upgrade the service to resume it`);
         }
         const cp = parseJson(r.checkpoint);
+        // the COLUMN status is authoritative (resolve/reap update it, not the blob) — reflect it on the returned cp.
         cp.status = r.status;
+        // design/80 D-1: surface the reopen-by-reason + OCC fields off the AUTHORITATIVE columns (the blob is the
+        // suspend-time snapshot; resolve/reopen mutate only the columns). Core's resume reads these to validate an
+        // env_failed re-resume against the persisted winner, and to require the `rev` it observed is still live (OCC).
+        // resolvedOutcome is DERIVED from the stored full outcome (winnerFromOutcome → {boundCallId,decision,
+        // updatedInput?}), so it is preserved across a reopen for free (reopen leaves `outcome` untouched).
         const outcomeRaw = parseJson(r.outcome);
         if (outcomeRaw)
             cp.resolvedOutcome = winnerFromOutcome(outcomeRaw);
         cp.reopenReason = r.reopen_reason ?? undefined;
-        cp.rev = r.rev == null ? 0 : Number(r.rev);
+        cp.rev = r.rev == null ? 0 : Number(r.rev); // legacy/pre-migration rows ⇒ 0 (the .d.ts "Absent ⇒ legacy 0")
+        // design/80 D-A: overlay the parked steer off the AUTHORITATIVE column (set by setPendingSteer AFTER the
+        // suspend-time blob was written) so core injects it on resume. The blob never carries it.
         const steerRaw = parseJson(r.pending_steer);
         if (steerRaw && cp.state)
             cp.state.pendingSteer = steerRaw;
+        // Diagnostic: log what the REAL runner.resume store.get returns for the remote
+        // workspaceHandle (the isolated round-trip test can't prove the real-path get). undefined here ⇒ store/get
+        // drops it; present ⇒ core's 910→614 threading drops it. Cheap, on the resume read-path only.
         this.logger?.info?.("checkpoint_get", {
-            tokenFp: tokenFingerprint(token),
+            tokenFp: tokenFingerprint(token), // NEVER the raw token — it is the resume credential (token-as-auth)
             status: cp.status,
             version,
             hasWorkspaceHandle: !!cp.state?.workspaceHandle,
@@ -100,6 +179,25 @@ export class SqlCheckpointStore {
         });
         return cp;
     }
+    /**
+     * 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.
+     */
     async resolve(token, scope, outcome, expect) {
         const params = [this.json(outcome, "checkpoint outcome"), Date.now(), token, scope];
         if (expect)
@@ -109,35 +207,103 @@ export class SqlCheckpointStore {
             (expect ? " AND rev = $5" : "")), params);
         return res.affected === 1;
     }
+    /**
+     * 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.
+     */
     async reopen(token, scope, reason) {
         const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'pending', reopen_reason = ?, rev = rev + 1 WHERE token = ? AND scope = ? AND status = 'resolved'", "UPDATE checkpoint SET status = 'pending', reopen_reason = $1, rev = rev + 1 WHERE token = $2 AND scope = $3 AND status = 'resolved'"), [reason, token, scope]);
         return res.affected === 1;
     }
+    /**
+     * 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).
+     */
     async setPendingSteer(token, scope, steer) {
-        const clean = validatePendingSteer(steer);
+        // M2(接入审计 2026-07-08):契约把 validatePendingSteer 定为【每个 impl 内部】必跑的 fail-closed 不变式
+        // ("EVERY CheckpointStore.setPendingSteer impl runs [it] so the reject is IDENTICAL across the in-memory and
+        // durable backends")——core 自家 File/InMemory/Pg 三 impl 全有;此前这里裸写 UPDATE=靠调用方自觉(HTTP 层
+        // 三处前置校验只是碰巧全覆盖,下一个内部调用方不一定记得)。clean = 冻结 {text,trusted} 两字段拷贝
+        // (调用方对象上的多余字段绝不落库,契约同款)。
+        const clean = validatePendingSteer(steer); // throws CheckpointError(steering.invalid_content) — per-impl 一致拒绝
         const res = await this.db.query(this.q("UPDATE checkpoint SET pending_steer = ? WHERE token = ? AND scope = ? AND status = 'pending'", "UPDATE checkpoint SET pending_steer = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'"), [this.json(clean, "pending steer"), token, scope]);
         return res.affected > 0;
     }
+    /**
+     * 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.
+     */
     async expire(token, scope) {
         const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? WHERE token = ? AND scope = ? AND status = 'pending'", "UPDATE checkpoint SET status = 'expired', decided_at = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'"), [Date.now(), token, scope]);
         return res.affected === 1;
     }
+    /** Interface reap: CAS-expire pending checkpoints in `scope` past `cutoff`. Returns count. */
     async reap(scope, cutoff) {
         const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? WHERE scope = ? AND status = 'pending' AND deadline IS NOT NULL AND deadline <= ?", "UPDATE checkpoint SET status = 'expired', decided_at = $1 WHERE scope = $2 AND status = 'pending' AND deadline IS NOT NULL AND deadline <= $3"), [Date.now(), scope, cutoff]);
         return res.affected;
     }
+    /**
+     * 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).
+     */
     async reapExpired(cutoff) {
         const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? " +
             "WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND (gate_kind IS NULL OR gate_kind NOT IN ('human','irreversible_ask') OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at IS NOT NULL AND terminal_at <= ?))", "UPDATE checkpoint SET status = 'expired', decided_at = $1 " +
             "WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND (gate_kind IS NULL OR gate_kind NOT IN ('human','irreversible_ask') OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at IS NOT NULL AND terminal_at <= $3))"), [Date.now(), cutoff, cutoff]);
         return res.affected;
     }
+    /**
+     * 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.
+     */
     async listExpiredApprovalGates(cutoff, limit = 100) {
         const { rows } = await this.db.query(this.q("SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND gate_kind IN ('human','irreversible_ask') " +
             "AND COALESCE(tool_name,'') <> 'AskUserQuestion' AND deadline IS NOT NULL AND deadline <= ? ORDER BY deadline ASC LIMIT ?", "SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND gate_kind IN ('human','irreversible_ask') " +
             "AND COALESCE(tool_name,'') <> 'AskUserQuestion' AND deadline IS NOT NULL AND deadline <= $1 ORDER BY deadline ASC LIMIT $2"), [cutoff, limit]);
         return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
     }
+    // ─────────────────────── operator approval queue (non-secret; token stays internal) ───────────────────────
+    /** 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). */
     async listPending(scope) {
         const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.created_at, c.deadline, ta.task_id " +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
@@ -151,21 +317,41 @@ export class SqlCheckpointStore {
                 scope: String(r.scope),
                 toolName: r.tool_name ?? null,
                 toolCallId,
+                // D-1: boundCallId === the pending tool call id; boundInputHash is the server-minted opaque hash. The
+                // portal echoes BOTH on /decide so the resume binds to the exact action shown (TOCTOU guard reachable).
                 boundCallId: toolCallId,
                 boundInputHash: r.bound_input_hash ?? null,
                 taskId: r.task_id ?? null,
+                // Both drivers return the JSON column already parsed; null for pre-migration rows. PG 库内恒干净
+                // (拒绝式)——直读即审阅面=执行面。
                 input: r.tool_input ?? null,
                 createdAt: Number(r.created_at),
                 deadline: r.deadline == null ? null : Number(r.deadline),
                 riskDescriptor: parseJson(r.risk_descriptor),
             };
         });
+        // riskDescriptor inbox: triage-sort by severity DESC (highest-risk asks first), then oldest-first within a
+        // tier. A row with no descriptor (pre-migration / non-gate) sorts to severity 0 (after the descriptored ones).
         return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
     }
+    /**
+     * 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.
+     */
     async listByScope(scope) {
         const { rows } = await this.db.query(this.q("SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at ASC LIMIT 500", "SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at ASC LIMIT 500"), [scope]);
         const out = [];
         for (const r of rows) {
+            // A corrupt/missing blob skips THAT row rather than crashing the whole scheduler view (review w16yqkkxv):
+            // unlike get() (a single-token read where a null blob is a hard error), a bulk triage list must degrade.
             const cp = parseJson(r.checkpoint);
             if (!cp)
                 continue;
@@ -174,18 +360,31 @@ export class SqlCheckpointStore {
         }
         return out;
     }
+    /**
+     * 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.
+     */
     async findPendingTokenBySession(sessionId, scope) {
         const { rows } = scope
             ? await this.db.query(this.q("SELECT token FROM checkpoint WHERE session_id=? AND scope=? AND status='pending' LIMIT 1", "SELECT token FROM checkpoint WHERE session_id=$1 AND scope=$2 AND status='pending' LIMIT 1"), [sessionId, scope])
             : await this.db.query(this.q("SELECT token FROM checkpoint WHERE session_id=? AND status='pending' LIMIT 1", "SELECT token FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1"), [sessionId]);
         return rows[0] ? String(rows[0].token) : 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.
+     */
     async peekPendingScope(sessionId) {
         const { rows } = await this.db.query(this.q("SELECT scope FROM checkpoint WHERE session_id=? AND status='pending' LIMIT 1", "SELECT scope FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1"), [sessionId]);
         if (!rows[0])
             return undefined;
         return rows[0].scope ?? null;
     }
+    // ─────────────────────── checkpoint_ctx (service rebuild inputs; sessionId-keyed) ───────────────────────
+    /** Upsert the resume rebuild inputs for a session (written at SUBMIT when durable mode is on). */
     async putCtx(sessionId, ctx) {
         await this.db.query(this.q("INSERT INTO checkpoint_ctx (session_id, ctx, updated_at) VALUES (?,?,?) " +
             "ON DUPLICATE KEY UPDATE ctx = VALUES(ctx), updated_at = VALUES(updated_at)", "INSERT INTO checkpoint_ctx (session_id, ctx, updated_at) VALUES ($1,$2::jsonb,$3) " +
@@ -195,6 +394,17 @@ export class SqlCheckpointStore {
         const { rows } = await this.db.query(this.q("SELECT ctx FROM checkpoint_ctx WHERE session_id=?", "SELECT ctx FROM checkpoint_ctx WHERE session_id=$1"), [sessionId]);
         return rows[0] ? parseJson(rows[0].ctx) : 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.
+     */
     async reapCtx(cutoff) {
         const res = await this.db.query(this.q("DELETE FROM checkpoint_ctx WHERE updated_at < ? " +
             "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +
@@ -203,6 +413,22 @@ export class SqlCheckpointStore {
             "AND session_id NOT IN (SELECT session_id FROM task_active)"), [cutoff]);
         return res.affected;
     }
+    /**
+     * 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`.
+     */
     async deleteBySession(sessionId, owner) {
         const ownerGuard = this.q("EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = ? AND sm.owner <=> ?)", "EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = $1 AND sm.owner IS NOT DISTINCT FROM $2)");
         const params = this.db.dialect === "tidb" ? [sessionId, sessionId, owner] : [sessionId, owner];
@@ -211,11 +437,13 @@ export class SqlCheckpointStore {
         return res.affected;
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBCheckpointStore extends SqlCheckpointStore {
     constructor(pool, logger) {
         super(mysqlDriver(pool), logger);
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgCheckpointStore extends SqlCheckpointStore {
     constructor(pool, logger) {
         super(pgDriver(pool), logger);

package/dist/plugins/file-outcome-sink.d.ts

@@ -1,4 +1,8 @@
 import type { TaskOutcome as CoreTaskOutcome } from "@sema-agent/core";
+/** The one write verb every outcome sink (TiDB/Pg ledger adapters + this File twin) exposes to main.ts,
+ *  plus the OPTIONAL read aggregate backing `GET /v1/outcomes` (P2) — present on the SQL ledgers (their
+ *  existing per-(signature, model) summary); absent here (the JSONL file IS the local dataset — a dashboard
+ *  reads the file, the endpoint 501s honestly). */
 export interface OutcomeSink {
     recordCore(o: CoreTaskOutcome): Promise<void>;
     summary?(opts?: {

package/dist/plugins/file-outcome-sink.js

@@ -1,9 +1,18 @@
+/**
+ * design/73 §1 consumption, LOCAL lane — the File twin of the TiDB/Pg outcome ledgers for the single-user /
+ * no-DB posture: append each core `TaskOutcome` fact VERBATIM to an owner-only JSONL ledger. Read-only v1
+ * (dashboard/backtest dataset — mirrors the SQL ledgers' read-only red line); no query surface here, the
+ * file IS the dataset. Non-load-bearing observability → no fsync (a crash may lose the tail fact; the run
+ * itself is unaffected — same posture as metrics).
+ */
 import { mkdirSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 export class FileOutcomeSink {
     path;
     constructor(root) {
         const dir = join(root, "outcomes");
+        // 0o700 dir + 0o600 file: outcome facts carry model/taskSignature/oracle detail — operator-only, parity
+        // with the other File ledgers' posture.
         mkdirSync(dir, { recursive: true, mode: 0o700 });
         this.path = join(dir, "outcomes.jsonl");
     }

package/dist/plugins/file-resume-anchor-store.d.ts

@@ -1,19 +1,39 @@
 export declare class FileResumeAnchorStore {
     private readonly dir;
+    /** sessionId → (eventId → {entryId, owner}) — the same in-memory shape MemoryResumeAnchorStore holds, hydrated on ctor. */
     private readonly bySession;
+    /** sessionId → the open append log (one O_APPEND fd per session, lazily opened on first put, held for lifetime). */
     private readonly logs;
     constructor(root: string);
+    /** `<dir>/<sanitizePathComponent(sessionId)>.jsonl` — the per-session log path (sessionId is uuidv7, already safe). */
     private pathFor;
+    /** Replay every session log into the in-memory index on boot (torn-tail-safe via readJsonlRecords; last-wins upsert
+     *  so a re-stamped eventId reflects the latest appended record). The in-memory index is keyed by the SANITIZED
+     *  sessionId throughout (put/resolve/list/delete all sanitize), and each on-disk file's base name IS
+     *  `sanitizePathComponent(sessionId)` — so the index key is just the file base, with no de-sanitize needed. */
     private hydrate;
+    /** Open (or reuse) the append log for a session. The file base is the SANITIZED id (matches hydrate's de-sanitize). */
     private logFor;
+    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert; parity with the SQL
+     *  ON DUPLICATE/CONFLICT). Appends a durable record (fsync:true) THEN upserts the index — a crash after the
+     *  fsync is recovered by hydrate (the record is on disk); a crash before it just loses an un-acked anchor. */
     put(sessionId: string, eventId: string, entryId: string, owner: string | null): Promise<void>;
+    /** Resolve a shell-supplied eventId → the persisted SessionTreeEntry.id for TaskSpec.resumeAt; undefined = unknown
+     *  anchor (the route 4xx's before handing core a bad id). owner null-safe guard = the SQL `owner <=> ?` defense-in-depth. */
     resolve(sessionId: string, eventId: string, owner: string | null): Promise<string | undefined>;
+    /** 2c session-sync: ALL anchors for a session (every eventId→entryId + its owner), UNFILTERED — a cross-backend
+     *  session EXPORT bundles the whole anchor map so the importer can RE-KEY owner to the target principal (§9). The
+     *  route already proved session ownership (the export gate), so no per-row owner filter here. Twin of the SQL stores. */
     listBySession(sessionId: string): Promise<Array<{
         eventId: string;
         entryId: string;
         owner: string | null;
     }>>;
+    /** E21 (§0.5 delete) — purge ALL anchors for a session, scoped by session_id ALONE (the route already proved session
+     *  ownership; a per-row owner guard would orphan rows stored under a divergent per-run principal). Idempotent (count).
+     *  Closes + unlinks the session log so the dir does not leak a file, and drops the in-memory index entry. */
     deleteBySession(sessionId: string): Promise<number>;
+    /** Release every open append-log fd (called by LocalBackend.close so a graceful restart can re-open the data dir). */
     dispose(): void;
 }
 //# sourceMappingURL=file-resume-anchor-store.d.ts.map

package/dist/plugins/file-resume-anchor-store.js

@@ -1,23 +1,47 @@
+/**
+ * File-backed resume-at anchor map (E18) — the DURABLE local twin of {@link MemoryResumeAnchorStore}, persisting the
+ * service-owned eventId→entryId translation across a process restart (P0.5 variant-1, clay 2026-06-26; the file-backed
+ * follow-on the Memory twin's header promised). Behaviour is byte-identical to the Memory store (put/resolve/
+ * deleteBySession + the §0.5/2c `listBySession` add); the only difference is durability.
+ *
+ * Persistence: one append-only JSONL log per session at `<root>/resume-anchors/<sanitizePathComponent(sessionId)>.jsonl`,
+ * each line `{eventId, entryId, owner, ts}`. `put` APPENDS (fsync:true — an anchor is a durable rewind boundary; a lost
+ * anchor silently breaks the next rewind), and the in-memory index is upserted last-wins so a re-stamped eventId
+ * overwrites (parity with the SQL ON DUPLICATE/CONFLICT). On construction the index is HYDRATED by replaying every
+ * session log via core's `readJsonlRecords` (torn-tail-safe: a crash mid-append drops only the partial last line, and a
+ * later `put` re-records it). `resolve`/`listBySession` read the in-memory index (O(1)/O(per-session)); `deleteBySession`
+ * unlinks the file + drops the index entry. owner null-safe guard (`(a??null)===(b??null)`) = the SQL `owner <=> ?`
+ * defense-in-depth twin. Single-process (the FileStorageBackend boot lock guarantees one writer per data dir), so there
+ * is no per-op lock — the in-process model is the premise (core fs-atomic BootLock).
+ */
 import { join } from "node:path";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { AppendLog, ensureDir, readJsonlRecords, sanitizePathComponent } from "@sema-agent/core";
+/** Null-safe owner equality — the JS twin of the SQL `owner <=> ?` guard (a legacy null-owner anchor matches owner=null). */
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 export class FileResumeAnchorStore {
     dir;
+    /** sessionId → (eventId → {entryId, owner}) — the same in-memory shape MemoryResumeAnchorStore holds, hydrated on ctor. */
     bySession = new Map();
+    /** sessionId → the open append log (one O_APPEND fd per session, lazily opened on first put, held for lifetime). */
     logs = new Map();
     constructor(root) {
         this.dir = join(root, "resume-anchors");
         ensureDir(this.dir);
         this.hydrate();
     }
+    /** `<dir>/<sanitizePathComponent(sessionId)>.jsonl` — the per-session log path (sessionId is uuidv7, already safe). */
     pathFor(sessionId) {
         return join(this.dir, `${sanitizePathComponent(sessionId)}.jsonl`);
     }
+    /** Replay every session log into the in-memory index on boot (torn-tail-safe via readJsonlRecords; last-wins upsert
+     *  so a re-stamped eventId reflects the latest appended record). The in-memory index is keyed by the SANITIZED
+     *  sessionId throughout (put/resolve/list/delete all sanitize), and each on-disk file's base name IS
+     *  `sanitizePathComponent(sessionId)` — so the index key is just the file base, with no de-sanitize needed. */
     hydrate() {
         let names;
         try {
-            names = readdirSync(this.dir);
+            names = readdirSync(this.dir); // a fresh root has the (just-ensured) empty dir → []
         }
         catch {
             return;
@@ -25,19 +49,20 @@ export class FileResumeAnchorStore {
         for (const name of names) {
             if (!name.endsWith(".jsonl"))
                 continue;
-            const key = name.slice(0, -".jsonl".length);
+            const key = name.slice(0, -".jsonl".length); // the file base IS sanitizePathComponent(sessionId) = the index key
             const records = readJsonlRecords(join(this.dir, name));
             if (!records.length)
                 continue;
             const m = this.bySession.get(key) ?? new Map();
             for (const r of records) {
                 if (!r || typeof r.eventId !== "string" || typeof r.entryId !== "string")
-                    continue;
-                m.set(r.eventId, { entryId: r.entryId, owner: r.owner ?? null });
+                    continue; // skip a malformed record
+                m.set(r.eventId, { entryId: r.entryId, owner: r.owner ?? null }); // last-wins upsert (replay order = append order)
             }
             this.bySession.set(key, m);
         }
     }
+    /** Open (or reuse) the append log for a session. The file base is the SANITIZED id (matches hydrate's de-sanitize). */
     logFor(sessionId) {
         const key = sanitizePathComponent(sessionId);
         let log = this.logs.get(key);
@@ -47,6 +72,9 @@ export class FileResumeAnchorStore {
         }
         return log;
     }
+    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert; parity with the SQL
+     *  ON DUPLICATE/CONFLICT). Appends a durable record (fsync:true) THEN upserts the index — a crash after the
+     *  fsync is recovered by hydrate (the record is on disk); a crash before it just loses an un-acked anchor. */
     async put(sessionId, eventId, entryId, owner) {
         const key = sanitizePathComponent(sessionId);
         this.logFor(sessionId).append({ eventId, entryId, owner: owner ?? null, ts: new Date().toISOString() }, true);
@@ -57,10 +85,15 @@ export class FileResumeAnchorStore {
         }
         m.set(eventId, { entryId, owner });
     }
+    /** Resolve a shell-supplied eventId → the persisted SessionTreeEntry.id for TaskSpec.resumeAt; undefined = unknown
+     *  anchor (the route 4xx's before handing core a bad id). owner null-safe guard = the SQL `owner <=> ?` defense-in-depth. */
     async resolve(sessionId, eventId, owner) {
         const e = this.bySession.get(sanitizePathComponent(sessionId))?.get(eventId);
         return e && ownerEq(e.owner, owner) ? e.entryId : undefined;
     }
+    /** 2c session-sync: ALL anchors for a session (every eventId→entryId + its owner), UNFILTERED — a cross-backend
+     *  session EXPORT bundles the whole anchor map so the importer can RE-KEY owner to the target principal (§9). The
+     *  route already proved session ownership (the export gate), so no per-row owner filter here. Twin of the SQL stores. */
     async listBySession(sessionId) {
         const m = this.bySession.get(sanitizePathComponent(sessionId));
         if (!m)
@@ -70,6 +103,9 @@ export class FileResumeAnchorStore {
             out.push({ eventId, entryId: e.entryId, owner: e.owner });
         return out;
     }
+    /** E21 (§0.5 delete) — purge ALL anchors for a session, scoped by session_id ALONE (the route already proved session
+     *  ownership; a per-row owner guard would orphan rows stored under a divergent per-run principal). Idempotent (count).
+     *  Closes + unlinks the session log so the dir does not leak a file, and drops the in-memory index entry. */
     async deleteBySession(sessionId) {
         const key = sanitizePathComponent(sessionId);
         const removed = this.bySession.get(key)?.size ?? 0;
@@ -85,16 +121,19 @@ export class FileResumeAnchorStore {
                 rmSync(path, { force: true });
             }
             catch {
+                /* best-effort — a stale file is harmless (the index entry is already gone) */
             }
         }
         return removed;
     }
+    /** Release every open append-log fd (called by LocalBackend.close so a graceful restart can re-open the data dir). */
     dispose() {
         for (const log of this.logs.values()) {
             try {
                 log.close();
             }
             catch {
+                /* best-effort */
             }
         }
         this.logs.clear();