@sema-agent/server 1.323.0 → 2.0.1

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

@@ -3,21 +3,27 @@ import { escapeLike } from "./sql-escape.js";
 import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
 import { parseJsonLenient as parseJson, toIso as iso } from "./sql-row-helpers.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+/** Dual-dialect async run registry + event log. See the file header for the dialect-delta ledger. */
 export class SqlRunStore {
     db;
     constructor(db) {
         this.db = db;
     }
+    /** 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;
     }
+    /** mysql2 names the dup-key `ER_DUP_ENTRY`; PG raises SQLSTATE `23505`. */
     isDupKey(err) {
         const code = err?.code;
         return Boolean(err) && (this.db.dialect === "tidb" ? code === "ER_DUP_ENTRY" : code === "23505");
     }
+    /** JSON column binding: TiDB stores the string verbatim; PG goes through the protocol-safe envelope
+     *  (a raw NUL byte in an event payload would otherwise throw 22P05 mid-write). */
     json(value) {
         return this.db.dialect === "tidb" ? JSON.stringify(value) : pgSafeJsonStringify(value);
     }
+    /** Run statements atomically; rolls back on failure. */
     async tx(fn) {
         const conn = await this.db.connect();
         try {
@@ -30,6 +36,7 @@ export class SqlRunStore {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
@@ -37,6 +44,14 @@ export class SqlRunStore {
             conn.release();
         }
     }
+    /**
+     * Create a run, but only if the session has no other active run (double-text guard).
+     *
+     * Mutual exclusion is a unique-key claim on `task_active(session_id)` — NOT a SELECT…FOR UPDATE,
+     * which on TiDB (no gap locks) would fail to serialize two concurrent createRuns when the session
+     * has no prior row. A plain INSERT either claims the session or throws a duplicate-key error (TiDB
+     * does NOT report a reliable affectedRows for `ON DUPLICATE KEY UPDATE …=…`, so we catch dup-key).
+     */
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
         const conn = await this.db.connect();
         try {
@@ -62,6 +77,8 @@ export class SqlRunStore {
                 instanceId,
                 meta.jobId ?? null,
                 meta.source ?? null,
+                // PG-only (R12 同族): objective 预览=模型可控标量,走 pgSanitizeText(NUL/protocol-byte 防护)。
+                // TiDB 存 verbatim(无该字节类)。
                 this.db.dialect === "tidb"
                     ? meta.objectivePreview ?? null
                     : meta.objectivePreview == null
@@ -78,6 +95,7 @@ export class SqlRunStore {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
@@ -85,39 +103,79 @@ export class SqlRunStore {
             conn.release();
         }
     }
+    /** Request cancel of a RUNNING run (durable, cross-replica). Sets the flag the owning instance's heartbeat
+     *  tick polls; a same-replica caller additionally aborts the in-flight controller for instant effect. Only
+     *  flags a `running` row (terminal/suspended → 0 affected = no-op). Returns whether a running row was flagged.
+     *
+     *  `owner` is a single-DB-fleet defense-in-depth guard: the WHERE pins the row to the authenticated owner
+     *  (null-safe compare so a legacy null-owner run matches owner=null), so even if the HTTP owner-gate has a bug
+     *  a caller can never flip another tenant's run. Pass the run's owner (from the looked-up RunRecord). */
     async requestCancel(taskId, owner) {
         const { affected } = await this.db.query(this.q("UPDATE task_run SET cancel_requested = 1 WHERE task_id = ? AND owner <=> ? AND status = 'running'", "UPDATE task_run SET cancel_requested = 1 WHERE task_id = $1 AND owner IS NOT DISTINCT FROM $2 AND status = 'running'"), [taskId, owner]);
         return affected > 0;
     }
+    /** Whether a cancel has been requested for this run (polled by the owning instance's heartbeat tick).
+     *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}). */
     async isCancelRequested(taskId, owner) {
         const { rows } = await this.db.query(this.q("SELECT cancel_requested FROM task_run WHERE task_id = ? AND owner <=> ?", "SELECT cancel_requested FROM task_run WHERE task_id = $1 AND owner IS NOT DISTINCT FROM $2"), [taskId, owner]);
         return Boolean(rows[0]?.cancel_requested);
     }
+    /** design/80 seam #2: request PREEMPT (graceful durable yield, ≠ cancel's kill) of a RUNNING run — durable +
+     *  cross-replica. Sets the flag the owning instance's heartbeat tick polls (it then aborts its preemptSignal →
+     *  the task suspends at the next clean turn boundary, gate resource_limit/reason preempt); a same-replica caller
+     *  additionally aborts the in-flight preempt controller for instant effect. Only flags a `running` row
+     *  (terminal/suspended → 0 affected = no-op). Returns whether a running row was flagged.
+     *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}). */
     async requestPreempt(taskId, owner) {
         const { affected } = await this.db.query(this.q("UPDATE task_run SET preempt_requested = 1 WHERE task_id = ? AND owner <=> ? AND status = 'running'", "UPDATE task_run SET preempt_requested = 1 WHERE task_id = $1 AND owner IS NOT DISTINCT FROM $2 AND status = 'running'"), [taskId, owner]);
         return affected > 0;
     }
+    /** Whether a preempt has been requested for this run (polled by the owning instance's heartbeat tick).
+     *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}). */
     async isPreemptRequested(taskId, owner) {
         const { rows } = await this.db.query(this.q("SELECT preempt_requested FROM task_run WHERE task_id = ? AND owner <=> ?", "SELECT preempt_requested FROM task_run WHERE task_id = $1 AND owner IS NOT DISTINCT FROM $2"), [taskId, owner]);
         return Boolean(rows[0]?.preempt_requested);
     }
+    /** Liveness heartbeat: refresh updated_at for a still-running run, independent of events. The
+     *  running instance calls this on a timer so a long-but-alive turn (e.g. a subagent that emits no
+     *  parent events for minutes) is not mistaken for a dead instance.
+     *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}); the heartbeat is
+     *  always issued by the owning instance with the run's own owner, so this only narrows, never blocks. */
     async heartbeat(taskId, owner) {
         await this.db.query(this.q("UPDATE task_run SET updated_at = ? WHERE task_id = ? AND owner <=> ? AND status = 'running'", "UPDATE task_run SET updated_at = $1 WHERE task_id = $2 AND owner IS NOT DISTINCT FROM $3 AND status = 'running'"), [new Date(), taskId, owner]);
     }
+    /** Append one event. A single INSERT — `updated_at` (liveness) is owned by `heartbeat`, so there
+     *  is no second statement to keep atomic here. */
     async appendEvent(taskId, seq, type, data) {
         await this.db.query(this.q("INSERT INTO task_event (task_id, seq, type, data, ts) VALUES (?,?,?,?,?)", "INSERT INTO task_event (task_id, seq, type, data, ts) VALUES ($1,$2,$3,$4::jsonb,$5)"), [taskId, seq, type, data == null ? null : this.json(data), new Date()]);
     }
+    /** Highest event seq for a task (0 if none). Lets a resumed leg CONTINUE the durable event log past the
+     *  suspend (core 1.70 `resumeStream`) — the suspend wrote events 1..K, the resume appends from K+1 without
+     *  colliding on the (task_id, seq) PK. */
     async maxSeq(taskId) {
         const { rows } = await this.db.query(this.q("SELECT MAX(seq) AS m FROM task_event WHERE task_id = ?", "SELECT MAX(seq) AS m FROM task_event WHERE task_id = $1"), [taskId]);
         const m = rows[0]?.m;
         return m == null ? 0 : Number(m);
     }
+    /** Mark terminal AND release the single-active-run claim atomically — if the DELETE were a separate
+     *  statement that failed, the session would stay permanently locked. [888] FIRST terminal writer wins:
+     *  the UPDATE is CAS'd POSITIVELY on the live statuses (running/suspended/needs_review) — every call site
+     *  is a settle-once flow whose backstops may double-fire (cancel × leg-throw × reaper), and an
+     *  unconditional write let the LAST racer overwrite errorCode (a `cancelled` row flipping to a generic
+     *  abort text, or vice versa). Positive form ([1.207 codex M1]): the negative NOT IN missed the
+     *  blocked/timeout terminals — a first write of those could still be overwritten. The claim DELETE stays
+     *  unconditional (idempotent; the first writer already released it). */
     async setTerminal(taskId, status, result, error) {
+        // Denormalize the structured code into its own column so operators can `WHERE error_code LIKE
+        // 'budget.%'` without parsing every result JSON. Source of truth stays the result blob.
         const errorCode = result?.errorCode ?? null;
         await this.tx(async (conn) => {
             await conn.query(this.q("UPDATE task_run SET status = ?, result = ?, error = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended','needs_review')", "UPDATE task_run SET status = $1, result = $2::jsonb, error = $3, error_code = $4, updated_at = $5 WHERE task_id = $6 AND status IN ('running','suspended','needs_review')"), [
                 status,
                 result == null ? null : this.json(result),
+                // codex R12 (PG only): error/errorCode = 裸 TEXT 参数 — 真 NUL 直炸 22P05,UPDATE 抛 → 事务回滚 →
+                // task_active 保持 → run 卡非终态到 reaper(错误文案带脏字节的形:tool 报错内嵌 raw 输出)。观测标量
+                // 同族有损 sanitize(与 result jsonb 同臂同纪律)。TiDB 存 verbatim。
                 this.db.dialect === "tidb" ? error : error == null ? null : pgSanitizeText(error),
                 this.db.dialect === "tidb" ? errorCode : errorCode == null ? null : pgSanitizeText(errorCode),
                 new Date(),
@@ -126,20 +184,64 @@ export class SqlRunStore {
             await conn.query(this.q("DELETE FROM task_active WHERE task_id = ?", "DELETE FROM task_active WHERE task_id = $1"), [taskId]);
         });
     }
+    /**
+     * Durable F4 (design/45): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
+     * KEEPS the `task_active` claim — the session stays locked (no new run) until an operator resumes it to a
+     * terminal state or the reaper expires it. The token-bearing result is NOT stored (the submitter polling
+     * this row must never receive the capability token); only the status flips.
+     */
     async setSuspended(taskId) {
+        // CAS on `running` (idempotent on an already-suspended row): without it, a heartbeat-stall race where
+        // `reapStale` already flipped the row to `failed` and DELETED its `task_active` claim would be reverted
+        // here to `suspended` WITHOUT re-claiming `task_active` — leaving a suspended run with no session lock, so
+        // a new run could start on the same session while the checkpoint is still pending. The CAS makes the
+        // reaped→suspended revert a no-op, so the reaper's decision stands and the invariant holds.
         await this.db.query(this.q("UPDATE task_run SET status = 'suspended', updated_at = ? WHERE task_id = ? AND status IN ('running','suspended')", "UPDATE task_run SET status = 'suspended', updated_at = $1 WHERE task_id = $2 AND status IN ('running','suspended')"), [new Date(), taskId]);
     }
+    /**
+     * design/80 D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
+     * pre-action `plan_review`; core assemble-result slot 8.6). Like {@link setSuspended} this is a NON-terminal park
+     * that KEEPS the `task_active` session claim (it does NOT delete it — only {@link setTerminal} does), so the
+     * resume path (`getActiveTaskId` → `markResuming`) can find + claim the row. core treats a review pause "like a
+     * suspend, an INTENTIONAL durable pause" (design/76 §2.5) — the service MUST park it the same way, else the run is
+     * terminalized + its lock released and the plan_review/dry_run_review resume can never run (it gets
+     * taskId=undefined and drives the model unprotected on an unlocked session). CAS on `running`/`needs_review`
+     * (reaper-revert guard, mirrors setSuspended). 🔴 The store SQL here is exercised by mocked unit tests only — a
+     * real-TiDB integration test of the park→resume→claim invariant is a required-before-GA TODO (the lesson from the
+     * P2 lease-SQL + this needs_review-park bug: mocked tests hide store-SQL defects).
+     */
     async setNeedsReview(taskId) {
         await this.db.query(this.q("UPDATE task_run SET status = 'needs_review', updated_at = ? WHERE task_id = ? AND status IN ('running','needs_review')", "UPDATE task_run SET status = 'needs_review', updated_at = $1 WHERE task_id = $2 AND status IN ('running','needs_review')"), [new Date(), taskId]);
     }
+    /**
+     * Durable F4 resume: a suspended run is being actively resumed. Flip it back to `running` (CAS — only if
+     * still suspended) and refresh liveness, so the in-flight resume is protected by the running-run heartbeat
+     * and is NOT killed by `reapSuspended` (which targets `status='suspended'` past the approval TTL). Without
+     * this the row sits at `suspended`/updated_at=suspend-time for the WHOLE resume execution, so a resume that
+     * crosses the TTL is marked `failed` mid-run and its session lock (`task_active`) is released. Returns true
+     * if it claimed the flip (false ⇒ the reaper already expired it, or it isn't suspended).
+     */
     async markResuming(taskId) {
-        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, updated_at = ? WHERE task_id = ? AND status IN ('suspended','needs_review')", "UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, updated_at = $1 WHERE task_id = $2 AND status IN ('suspended','needs_review')"), [new Date(), taskId]);
+        const { affected } = await this.db.query(
+        // cancel_requested is RESET on resume: a cancel that raced the suspend (flag set but never honored —
+        // the run parked first) must not silently kill an operator-APPROVED resume later. Cancelling a suspended
+        // run is the deny-approval path; a cancel of the resumed leg sets the flag afresh. preempt_requested is
+        // RESET for the same reason (design/80 seam #2): a preempt flag that survived into the resumed leg would
+        // make the heartbeat re-preempt it immediately (you resume to make PROGRESS) — the durable twin of core's
+        // pre-aborted-signal strip; a genuine re-preempt of the resumed leg sets the flag afresh.
+        // design/80 D-B: a `needs_review` (plan_review / dry_run_review) park is resumable too — the CAS accepts it
+        // alongside `suspended` so the plan_review resume can claim the parked row. The flag-reset rationale is
+        // identical for both park kinds.
+        this.q("UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, updated_at = ? WHERE task_id = ? AND status IN ('suspended','needs_review')", "UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, updated_at = $1 WHERE task_id = $2 AND status IN ('suspended','needs_review')"), [new Date(), taskId]);
         return affected === 1;
     }
+    /** The active run's taskId for a session (the `task_active` claim) — lets resume find the suspended run row. */
     async getActiveTaskId(sessionId) {
         const { rows } = await this.db.query(this.q("SELECT task_id FROM task_active WHERE session_id = ?", "SELECT task_id FROM task_active WHERE session_id = $1"), [sessionId]);
         return rows[0] ? String(rows[0].task_id) : undefined;
     }
+    /** Shared row→record mapper — byte-identical between dialects (both drivers hand back the same column
+     *  names + comparable JS types after SqlDriver's result normalization). */
     rowToRun(r) {
         return {
             taskId: String(r.task_id),
@@ -161,7 +263,18 @@ export class SqlRunStore {
         const { rows } = await this.db.query(this.q("SELECT task_id, session_id, owner, status, result, error, error_code, job_id, source, instance_id, objective_preview, created_at, updated_at FROM task_run WHERE task_id = ?", "SELECT task_id, session_id, owner, status, result, error, error_code, job_id, source, instance_id, objective_preview, created_at, updated_at FROM task_run WHERE task_id = $1"), [taskId]);
         return rows[0] ? this.rowToRun(rows[0]) : undefined;
     }
+    /** Task Trace list (S1): runs newest-first, keyset-paginated on (created_at, task_id). Optional status +
+     *  jobId filters (jobId = the work-view group, served by idx_job). Caller passes `limit+1` to detect a next
+     *  page. Cursor fields are bound as params (no SQL injection).
+     *
+     *  🔴 Genuinely-divergent BUILDER (not just SQL text): TiDB's `?` is position-agnostic, so the WHERE array is
+     *  built with plain string pushes in call order. PG's `$n` needs a NUMBERED placeholder per param, so that arm
+     *  keeps its own positional-counter closure (`p()`) — collapsing the two into one shared counter would hide
+     *  the very placeholder-numbering divergence this file exists to keep visible. */
     async listRuns(opts) {
+        // 夜测 N1(2026-07-09,LOW):a non-date cursor.createdAt made the four backends diverge (PG threw a raw
+        // DB error; the other three returned an empty page). HTTP's decodeCursor pre-validates, so this is
+        // defence-in-depth for direct store callers — normalize ALL backends to the empty page.
         if (opts.cursor && Number.isNaN(Date.parse(opts.cursor.createdAt)))
             return [];
         if (this.db.dialect === "tidb") {
@@ -180,11 +293,11 @@ export class SqlRunStore {
                 params.push(opts.source);
             }
             if (opts.owner) {
-                where.push("owner = ?");
+                where.push("owner = ?"); // idx_owner — the per-user list view (portal scopes a normal user to their own)
                 params.push(opts.owner);
             }
             if (opts.cursor) {
-                where.push("(created_at < ? OR (created_at = ? AND task_id < ?))");
+                where.push("(created_at < ? OR (created_at = ? AND task_id < ?))"); // keyset: strictly older, ties by task_id
                 params.push(new Date(opts.cursor.createdAt), new Date(opts.cursor.createdAt), opts.cursor.taskId);
             }
             const sql = "SELECT task_id, session_id, owner, status, result, error, error_code, job_id, source, objective_preview, created_at, updated_at FROM task_run" +
@@ -220,6 +333,12 @@ export class SqlRunStore {
         const { rows } = await this.db.query(sql, params);
         return rows.map((r) => this.rowToRun(r));
     }
+    /** GET /v1/sessions (CC /resume picker): DISTINCT sessions newest-first by last activity, keyset-paginated on
+     *  (last_activity, session_id). Aggregates task_run by session_id — one window pass picks the latest run per
+     *  session (rn=1) for the preview/status and rolls up first/last/count. Owner-scoped when set (the per-user view).
+     *  Bounded by per-tenant data today; a denormalized session table is the optimization if it ever goes hot.
+     *
+     *  🔴 Same builder divergence as {@link listRuns} — see its header note. */
     async listSessions(opts) {
         if (this.db.dialect === "tidb") {
             const params = [];
@@ -230,15 +349,18 @@ export class SqlRunStore {
             }
             const outer = ["rn = 1"];
             if (opts.q) {
+                // `?q=` — ANY-run preview match, session-granular (an outer LIKE on the rn=1 row alone would
+                // miss sessions whose match lives in an older run). LOWER-LIKE = collation-proof ci; escapeLike pins wildcards.
+                // Owner/sql_mode rationale: see tidb-session-store.ts listSessions.
                 outer.push("EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = t.session_id AND LOWER(tr.objective_preview) LIKE LOWER(?) ESCAPE '\\\\')");
                 params.push(`%${escapeLike(opts.q)}%`);
             }
             if (opts.cursor) {
-                outer.push("(last_activity < ? OR (last_activity = ? AND session_id < ?))");
+                outer.push("(last_activity < ? OR (last_activity = ? AND session_id < ?))"); // keyset: strictly older, ties by session_id
                 params.push(new Date(opts.cursor.lastActivityAt), new Date(opts.cursor.lastActivityAt), opts.cursor.sessionId);
             }
             const sql = "SELECT session_id, owner, task_id, last_activity, first_activity, run_count, objective_preview, status FROM (" +
-                "SELECT session_id, owner, task_id, objective_preview, status," +
+                "SELECT session_id, owner, task_id, objective_preview, status," + // K-5c: carry the rn=1 (latest) run's task_id
                 " ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn," +
                 " MAX(created_at) OVER (PARTITION BY session_id) AS last_activity," +
                 " MIN(created_at) OVER (PARTITION BY session_id) AS first_activity," +
@@ -256,6 +378,7 @@ export class SqlRunStore {
         };
         const innerWhere = opts.owner ? ` WHERE owner = ${p(opts.owner)}` : "";
         const outer = ["rn = 1"];
+        // `?q=` — the PG twin of the TiDB EXISTS predicate above.
         if (opts.q)
             outer.push(`EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = t.session_id AND LOWER(tr.objective_preview) LIKE LOWER(${p(`%${escapeLike(opts.q)}%`)}) ESCAPE '\\')`);
         if (opts.cursor) {
@@ -265,7 +388,7 @@ export class SqlRunStore {
             outer.push(`(last_activity < ${a} OR (last_activity = ${b} AND session_id < ${sid}))`);
         }
         const sql = "SELECT session_id, owner, task_id, last_activity, first_activity, run_count, objective_preview, status FROM (" +
-            "SELECT session_id, owner, task_id, objective_preview, status," +
+            "SELECT session_id, owner, task_id, objective_preview, status," + // K-5c: carry the rn=1 (latest) run's task_id
             " ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn," +
             " MAX(created_at) OVER (PARTITION BY session_id) AS last_activity," +
             " MIN(created_at) OVER (PARTITION BY session_id) AS first_activity," +
@@ -275,6 +398,7 @@ export class SqlRunStore {
         const { rows } = await this.db.query(sql, params);
         return rows.map((r) => this.rowToSession(r));
     }
+    /** Shared row→summary mapper for listSessions (byte-identical between dialects). */
     rowToSession(r) {
         return {
             sessionId: String(r.session_id),
@@ -284,18 +408,41 @@ export class SqlRunStore {
             runCount: Number(r.run_count),
             objectivePreview: r.objective_preview ?? null,
             lastStatus: String(r.status),
-            lastRunId: r.task_id ?? null,
-            title: null,
+            lastRunId: r.task_id ?? null, // K-5c: the latest run's id (the live-tail re-attach anchor)
+            title: null, // the legacy task_run aggregate has no session_meta — honest degrade
         };
     }
+    /**
+     * E21 (§0.5 session delete) — purge the service-owned RUNS LEDGER for one session: task_event (the replayable
+     * event log), task_active (the single-active-run claim), and task_run (the run rows). Owner-guarded (null-safe
+     * compare, single-DB defense-in-depth, mirrors {@link requestCancel}) so even a buggy HTTP gate can't purge
+     * another tenant's runs. Idempotent — returns `{ removed }` (the count of task_run rows removed; 0 = nothing to
+     * purge). The conversation HISTORY (session_meta/session_event) is purged separately by the session store; the
+     * checkpoint/tool-result rows by their stores — this method owns only the runs-ledger tables. Done in one TX so a
+     * partial purge can't leak a task_active claim with no run row (a permanent session lock).
+     *
+     * 🔴 Active-run re-assert INSIDE the TX (adversarial-review LOW — TOCTOU): the route's pre-purge `getActiveTaskId`
+     * 409 check is a non-transactional SELECT — a concurrent createRun can claim `task_active(session_id)` in the
+     * window between that check and this purge, then have its LIVE rows deleted here. So we re-take the no-active-run
+     * invariant transactionally: `SELECT task_id FROM task_active WHERE session_id=? FOR UPDATE` at the TOP of the TX.
+     * `FOR UPDATE` serializes against createRun's unique-key INSERT on the SAME session_id (createRun either already
+     * holds the row — we see it and abort — or blocks on our lock until commit, then fails its own unique-key claim
+     * against the now-absent row). If a claim exists we return `{ active }` (the route maps it to 409) and delete
+     * NOTHING. Returns `{ removed }` on a clean purge.
+     *
+     * 🔴 The multi-table DELETEs are dialect-divergent SQL FORMS (not just placeholders): TiDB's
+     * `DELETE te FROM te JOIN tr ON …` vs PG's `DELETE FROM te USING tr WHERE …`.
+     */
     async deleteBySession(sessionId, owner) {
         let result = { removed: 0 };
         await this.tx(async (conn) => {
+            // Transactional no-active-run gate (FOR UPDATE serializes against createRun's task_active claim).
             const { rows: active } = await conn.query(this.q("SELECT task_id FROM task_active WHERE session_id = ? FOR UPDATE", "SELECT task_id FROM task_active WHERE session_id = $1 FOR UPDATE"), [sessionId]);
             if (active[0]) {
                 result = { active: String(active[0].task_id) };
-                return;
+                return; // abort — delete nothing; the route 409s (don't purge a live run's rows)
             }
+            // task_event has no owner column → scope it through the owner-guarded task_run set for this session.
             await conn.query(this.q("DELETE te FROM task_event te JOIN task_run tr ON te.task_id = tr.task_id WHERE tr.session_id = ? AND tr.owner <=> ?", "DELETE FROM task_event te USING task_run tr WHERE te.task_id = tr.task_id AND tr.session_id = $1 AND tr.owner IS NOT DISTINCT FROM $2"), [sessionId, owner]);
             await conn.query(this.q("DELETE ta FROM task_active ta JOIN task_run tr ON ta.task_id = tr.task_id WHERE tr.session_id = ? AND tr.owner <=> ?", "DELETE FROM task_active ta USING task_run tr WHERE ta.task_id = tr.task_id AND tr.session_id = $1 AND tr.owner IS NOT DISTINCT FROM $2"), [sessionId, owner]);
             const { affected } = await conn.query(this.q("DELETE FROM task_run WHERE session_id = ? AND owner <=> ?", "DELETE FROM task_run WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2"), [sessionId, owner]);
@@ -303,10 +450,15 @@ export class SqlRunStore {
         });
         return result;
     }
+    /** Per-door usage rollup (center systems-UI input): COUNT by (source,status) since a cutoff. Reads the
+     *  denormalized columns only — no JSON parsing; served by full scan bounded by created_at (small windows). */
     async sourceSummary(sinceMs) {
         const { rows } = await this.db.query(this.q("SELECT source, status, COUNT(*) AS c FROM task_run WHERE created_at >= ? GROUP BY source, status", "SELECT source, status, COUNT(*) AS c FROM task_run WHERE created_at >= $1 GROUP BY source, status"), [new Date(sinceMs)]);
         return rows.map((r) => ({ source: r.source ?? null, status: String(r.status), count: Number(r.c) }));
     }
+    /** 用量扫窗(usage-analytics):按时间窗取 {owner,created_at,status,result} 四列,行内投影
+     *  stats(JSON 提取在 JS,免 SQL JSON 方言分叉);LIMIT+1 探测截断(触顶=truncated:true 诚实上抛)。
+     *  聚合在 src/usage-analytics.ts 纯函数(三后端同代码)。可选 owner 过滤=JWT 主体只看自己。 */
     async usageScan(fromMs, toMs, opts) {
         const limit = Math.min(opts?.limit ?? USAGE_SCAN_LIMIT, USAGE_SCAN_LIMIT);
         const where = [this.q("created_at >= ?", "created_at >= $1"), this.q("created_at < ?", "created_at < $2")];
@@ -328,11 +480,14 @@ export class SqlRunStore {
             })),
         };
     }
+    /** Earliest retained event seq for a task (0 if none) → `retainedFrom` for /turns and the 416 boundary for
+     *  /stream (a resume point below this has been evicted past retention). */
     async retainedFrom(taskId) {
         const { rows } = await this.db.query(this.q("SELECT MIN(seq) AS m FROM task_event WHERE task_id = ?", "SELECT MIN(seq) AS m FROM task_event WHERE task_id = $1"), [taskId]);
         const m = rows[0]?.m;
         return m == null ? 0 : Number(m);
     }
+    /** Events with seq strictly greater than `afterSeq` (use 0 for the whole stream). */
     async getEvents(taskId, afterSeq) {
         const { rows } = await this.db.query(this.q("SELECT seq, type, data, ts FROM task_event WHERE task_id = ? AND seq > ? ORDER BY seq ASC", "SELECT seq, type, data, ts FROM task_event WHERE task_id = $1 AND seq > $2 ORDER BY seq ASC"), [taskId, afterSeq]);
         return rows.map((r) => ({
@@ -342,6 +497,12 @@ export class SqlRunStore {
             ts: iso(r.ts),
         }));
     }
+    /**
+     * Mark stale `running` rows as failed (best-effort recovery for runs whose instance died), then
+     * free any active-run claim whose run is no longer running (reaped here, or a terminal whose
+     * DELETE was lost). `olderThanMs` must exceed the longest expected gap between a run's events
+     * (each event refreshes `updated_at`), else a healthy slow run is wrongly reaped.
+     */
     async reapStale(olderThanMs) {
         const cutoff = new Date(Date.now() - olderThanMs);
         let reaped = 0;
@@ -350,10 +511,32 @@ export class SqlRunStore {
                 "WHERE status = 'running' AND updated_at < ?", "UPDATE task_run SET status = 'failed', error = 'run stalled (instance lost?)', updated_at = $1 " +
                 "WHERE status = 'running' AND updated_at < $2"), [new Date(), cutoff]);
             reaped = affected;
+            // Release task_active for TERMINAL rows only. A 'suspended' row (durable F4) intentionally KEEPS its
+            // claim — the session stays locked until an operator resumes it or reapSuspended expires it. (Was
+            // `<> 'running'`, which would have prematurely unlocked a parked suspended session.)
             await conn.query(this.q("DELETE ta FROM task_active ta JOIN task_run tr ON ta.task_id = tr.task_id WHERE tr.status NOT IN ('running','suspended','needs_review')", "DELETE FROM task_active ta USING task_run tr WHERE ta.task_id = tr.task_id AND tr.status NOT IN ('running','suspended','needs_review')"));
         });
         return reaped;
     }
+    /**
+     * Durable F4 expiry: an approval parked beyond `olderThanMs` (the approval TTL) was never answered → fail
+     * the run + RELEASE its task_active (unlock the session). Mirrors the checkpoint reaper's CAS-expire (≈ deny);
+     * idempotent across replicas. Returns count.
+     *
+     * 🔴 design/80 D-D (adversarial blocker fix): SKIPS any row whose checkpoint is STILL pending — that row is
+     * owned by a checkpoint-state-driven sweep (the SLA deny-sweep for human/irreversible_ask, or
+     * failSuspendedWithExpiredCheckpoint once the checkpoint is expired). Without this guard, this time-based
+     * UPDATE fired at the SAME instant as the deny-sweep (deadline == createdAt + ttl, both keyed on the TTL),
+     * almost always committed FIRST (it is a single UPDATE), and deleted task_active + failed the run BEFORE the
+     * deny-sweep's resumeCheckpoint ran — so resumeCheckpoint saw no task row (markResuming skipped) yet STILL ran
+     * the model on a now-unlocked session (the pending checkpoint's resolve-CAS wins), orphaning a model leg and
+     * opening a two-runs-one-session window. The NOT-EXISTS-pending guard (same shape as
+     * failSuspendedWithExpiredCheckpoint) means this only ever reaps a row whose checkpoint is already gone/expired.
+     *
+     * 🔴 Alias-qualification divergence (kept EXPLICIT, never "fixed" to match): TiDB's SET clause QUALIFIES with
+     * `tr.` (`SET tr.status = …`); PG's SET clause must NOT be alias-qualified (`SET status = …` — PG rejects
+     * `SET a.col`). Both WHERE clauses use the `tr.` alias.
+     */
     async reapSuspended(olderThanMs) {
         const cutoff = new Date(Date.now() - olderThanMs);
         let reaped = 0;
@@ -368,10 +551,26 @@ export class SqlRunStore {
         });
         return reaped;
     }
+    /**
+     * design/80 §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at` sweep): fail a
+     * suspended run whose durable checkpoint was ALREADY EXPIRED by `reapExpired` (past its `deadline` or its
+     * absolute `terminal_at`), and release its task_active (unlock the session). Runs UNCONDITIONALLY (no
+     * approval-TTL gate), CHECKPOINT-STATE-driven not time-driven, so it aligns EXACTLY with the per-row
+     * `terminal_at` (which never falls before an operator's >30d deadline) — unlike a uniform timer, which would
+     * either be inert (gated off at APPROVAL_TIMEOUT_SEC=0) or prematurely kill a long gate. Safe against the two
+     * windows a naive predicate mis-fires on: (a) the transient suspend-write window — a run suspended before its
+     * checkpoint row exists has NO expired checkpoint, so it is not matched; (b) a re-suspended session that minted
+     * a NEW pending checkpoint — the `NOT EXISTS pending` clause excludes it. Idempotent across replicas. Returns count.
+     *
+     * Same alias-qualification divergence as {@link reapSuspended} — see its header note.
+     */
     async failSuspendedWithExpiredCheckpoint() {
         let reaped = 0;
         await this.tx(async (conn) => {
             const { affected } = await conn.query(this.q("UPDATE task_run tr SET tr.status = 'failed', tr.error = 'approval expired before decision', tr.error_code = 'approval.expired', tr.updated_at = ? " +
+                // wq64gmm5e HIGH: a needs_review park is ALSO a non-terminal claim-keeping state; an abandoned review
+                // park whose checkpoint reapExpired already expired must be failed + its task_active released, exactly
+                // like a suspended park — else the run row + session lock leak forever (no other reaper targets it).
                 "WHERE tr.status IN ('suspended','needs_review') " +
                 "AND EXISTS (SELECT 1 FROM checkpoint ce WHERE ce.session_id = tr.session_id AND ce.status = 'expired') " +
                 "AND NOT EXISTS (SELECT 1 FROM checkpoint cp WHERE cp.session_id = tr.session_id AND cp.status = 'pending')", "UPDATE task_run AS tr SET status = 'failed', error = 'approval expired before decision', error_code = 'approval.expired', updated_at = $1 " +
@@ -384,11 +583,13 @@ export class SqlRunStore {
         return reaped;
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBRunStore extends SqlRunStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgRunStore extends SqlRunStore {
     constructor(pool) {
         super(pgDriver(pool));

package/dist/plugins/s3-presign.d.ts

@@ -1,26 +1,37 @@
 export interface S3PresignParams {
+    /** Base endpoint, e.g. `http://minio.minio.svc.cluster.local:9000` (the host the SANDBOX will reach). */
     endpoint: string;
     bucket: string;
+    /** Object key (path within the bucket); each "/" segment is encoded, "/" preserved. */
     key: string;
     method: "GET" | "PUT" | "HEAD" | "DELETE";
     accessKey: string;
     secretKey: string;
     region?: string;
     expiresSec?: number;
+    /** Override the signing clock (tests). Defaults to now. */
     now?: Date;
 }
+/** Build a SigV4 presigned **single-object** URL. Pure string math — no network. */
 export declare function presignS3Url(p: S3PresignParams): string;
 export interface S3BucketPresignParams {
     endpoint: string;
     bucket: string;
+    /** Bucket-level verbs only: PUT = CreateBucket, DELETE = DeleteBucket (MinIO path-style, live-verified). */
     method: "PUT" | "DELETE";
     accessKey: string;
     secretKey: string;
     region?: string;
     expiresSec?: number;
+    /** Override the signing clock (tests). Defaults to now. */
     now?: Date;
 }
+/** Build a SigV4 presigned **bucket-level** URL (`/<bucket>/`, no key) — the explicit face for
+ *  CreateBucket/DeleteBucket (codex 1.189 F8: previously test fixtures smuggled this through
+ *  presignS3Url with key "", which the single-object contract now rejects). Same signing core. */
 export declare function presignS3BucketUrl(p: S3BucketPresignParams): string;
+/** ListObjectsV2 presign(D-1 孤儿对象 GC,clay 拍 2026-07-28):GET `/<bucket>/?list-type=2&prefix=…`。
+ *  bucket 级 GET 是**列举能力**——只给 server 端 sweep 用,URL 绝不外发(与 copy 面同纪律)。 */
 export declare function presignS3ListUrl(p: {
     endpoint: string;
     bucket: string;
@@ -34,9 +45,12 @@ export declare function presignS3ListUrl(p: {
     now?: Date;
 }): string;
 export interface S3CopyPresignParams {
+    /** INTERNAL endpoint — CopyObject is a SERVER-side request with adapter creds; never hand this URL out. */
     endpoint: string;
+    /** Destination coordinates (the PUT target). */
     bucket: string;
     key: string;
+    /** Source coordinates (ride the signed `x-amz-copy-source` header). */
     sourceBucket: string;
     sourceKey: string;
     accessKey: string;
@@ -45,6 +59,12 @@ export interface S3CopyPresignParams {
     expiresSec?: number;
     now?: Date;
 }
+/** Build a SigV4 presigned **CopyObject** request (修3 staging-key two-phase): S3 CopyObject = `PUT
+ *  /<dstBucket>/<dstKey>` with `x-amz-copy-source: /<srcBucket>/<srcKey>`. Query auth requires every
+ *  `x-amz-*` request header to be SIGNED, so the copy-source header goes through the signing core's
+ *  signedHeaders seam; the caller MUST send `headers` verbatim on the fetch (the source key is
+ *  RFC-3986-encoded — MinIO/S3 both accept the encoded copy-source form, and header values must be
+ *  ASCII anyway). Same single-object guards as presignS3Url on BOTH sides. */
 export declare function presignS3CopyUrl(p: S3CopyPresignParams): {
     url: string;
     headers: Record<string, string>;

package/dist/plugins/s3-presign.js

@@ -1,4 +1,16 @@
+/**
+ * Minimal AWS SigV4 **presigned URL** generator for S3-compatible object stores (MinIO) — zero dependencies
+ * (crypto only), matching the repo's no-SDK posture (OTLP exporter, the k8s adapter). We only need presign:
+ * the k8s sandbox adapter uploads/downloads a workspace snapshot by handing the SANDBOX a short-lived,
+ * single-object URL so the adapter's MinIO credentials never enter the sandbox (design/53 lethal-trifecta
+ * red line — "adapter-held, sandbox sees only a presigned URL").
+ *
+ * Path-style addressing (`<endpoint>/<bucket>/<key>`) — MinIO's default and what an IP/cluster-DNS endpoint
+ * needs (no virtual-host bucket subdomain). Payload is UNSIGNED-PAYLOAD so a streamed `curl -T -` body
+ * (chunked, unknown length) verifies — the signature binds method+path+headers+expiry, not the bytes.
+ */
 import { createHash, createHmac } from "node:crypto";
+/** URI-encode per RFC 3986 (S3 canonicalization): unreserved chars stay literal, everything else %XX. */
 function uriEncode(s, encodeSlash) {
     let out = "";
     for (const ch of Buffer.from(s, "utf8")) {
@@ -18,22 +30,40 @@ function uriEncode(s, encodeSlash) {
 function hmac(key, data) {
     return createHmac("sha256", key).update(data, "utf8").digest();
 }
+/** The shared SigV4 signing core: everything below the canonical-URI choice is identical for an
+ *  object URL and a bucket URL — one implementation so the two public faces can never drift.
+ *
+ *  Endpoint PATH PREFIX (三路复审修1): an endpoint like `https://files.example.com/minio` (reverse-proxy
+ *  sub-path in front of MinIO) contributes its path to BOTH the canonical URI (what SigV4 signs) and the
+ *  returned URL — previously only `url.origin` was used, so the signed canonical URI (`/bucket/key`) never
+ *  matched the request path the store actually saw (`/minio/bucket/key`), and the presigned track silently
+ *  diverged from the permanent track's plain string concat (which DID keep the prefix). One rstrip'd
+ *  pathname, prepended to both, keeps signature and request path congruent for any endpoint shape.
+ *
+ *  `signedHeaders` (修3 CopyObject support): extra headers to SIGN beyond `host` — presigned-URL (query)
+ *  auth requires every `x-amz-*` header the request carries to be in X-Amz-SignedHeaders, so a server-side
+ *  CopyObject (`x-amz-copy-source`) must sign it. Names are lowercased; canonical headers are sorted;
+ *  the CALLER must send exactly these header values on the request. */
 function presignCanonical(p) {
     const region = p.region ?? "us-east-1";
     const expires = p.expiresSec ?? 600;
     const now = p.now ?? new Date();
-    const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+    const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, ""); // YYYYMMDDTHHMMSSZ
     const dateStamp = amzDate.slice(0, 8);
     const url = new URL(p.endpoint);
-    const host = url.host;
+    const host = url.host; // includes port
+    // Endpoint path prefix (修1): "" for a root endpoint; "/minio" for a sub-path endpoint (trailing "/"
+    // stripped; `new URL().pathname` is already percent-encoded, which is what the canonical URI wants).
     const basePath = url.pathname.replace(/\/+$/, "");
     const canonicalUri = `${basePath}${p.canonicalUri}`;
     const scope = `${dateStamp}/${region}/s3/aws4_request`;
+    // Signed headers: `host` always; extras (lowercased, value-trimmed) merged in; canonical order = sorted.
     const headerMap = new Map([["host", host]]);
     for (const [k, v] of Object.entries(p.signedHeaders ?? {}))
         headerMap.set(k.toLowerCase(), v.trim());
     const headerNames = [...headerMap.keys()].sort();
     const signedHeaderList = headerNames.join(";");
+    // Query params must be sorted; values URI-encoded (the credential's "/" too).
     const params = {
         ...(p.extraQuery ?? {}),
         "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
@@ -56,18 +86,29 @@ function presignCanonical(p) {
     const signature = createHmac("sha256", kSigning).update(stringToSign, "utf8").digest("hex");
     return `${url.origin}${canonicalUri}?${canonicalQuery}&X-Amz-Signature=${signature}`;
 }
+/** Build a SigV4 presigned **single-object** URL. Pure string math — no network. */
 export function presignS3Url(p) {
+    // codex 1.189 F8: the contract here is SINGLE-OBJECT — an empty key would silently sign the BUCKET URI
+    // (`/<bucket>/` = CreateBucket/DeleteBucket/ListObjects depending on method), a far broader capability
+    // than any caller of this face intends. Refuse; bucket-level operations go through presignS3BucketUrl.
     if (p.key === "") {
         throw new Error("presignS3Url: refusing to sign an empty key (single-object contract) — use presignS3BucketUrl for bucket-level operations");
     }
+    // Backstop (defense in depth): callers MUST pass a pre-sanitized key, but a path-traversal segment here would
+    // sign a URL that escapes its intended prefix once the store normalizes the path — refuse rather than sign it.
     if (p.key.startsWith("/") || p.key.split("/").some((seg) => seg === "." || seg === "..")) {
         throw new Error(`presignS3Url: refusing to sign a key with a traversal segment: ${p.key}`);
     }
     return presignCanonical({ ...p, canonicalUri: `/${uriEncode(p.bucket, true)}/${uriEncode(p.key, false)}` });
 }
+/** Build a SigV4 presigned **bucket-level** URL (`/<bucket>/`, no key) — the explicit face for
+ *  CreateBucket/DeleteBucket (codex 1.189 F8: previously test fixtures smuggled this through
+ *  presignS3Url with key "", which the single-object contract now rejects). Same signing core. */
 export function presignS3BucketUrl(p) {
     return presignCanonical({ ...p, canonicalUri: `/${uriEncode(p.bucket, true)}/` });
 }
+/** ListObjectsV2 presign(D-1 孤儿对象 GC,clay 拍 2026-07-28):GET `/<bucket>/?list-type=2&prefix=…`。
+ *  bucket 级 GET 是**列举能力**——只给 server 端 sweep 用,URL 绝不外发(与 copy 面同纪律)。 */
 export function presignS3ListUrl(p) {
     return presignCanonical({
         endpoint: p.endpoint,
@@ -86,6 +127,12 @@ export function presignS3ListUrl(p) {
         },
     });
 }
+/** Build a SigV4 presigned **CopyObject** request (修3 staging-key two-phase): S3 CopyObject = `PUT
+ *  /<dstBucket>/<dstKey>` with `x-amz-copy-source: /<srcBucket>/<srcKey>`. Query auth requires every
+ *  `x-amz-*` request header to be SIGNED, so the copy-source header goes through the signing core's
+ *  signedHeaders seam; the caller MUST send `headers` verbatim on the fetch (the source key is
+ *  RFC-3986-encoded — MinIO/S3 both accept the encoded copy-source form, and header values must be
+ *  ASCII anyway). Same single-object guards as presignS3Url on BOTH sides. */
 export function presignS3CopyUrl(p) {
     for (const [label, key] of [
         ["destination", p.key],