@sema-agent/server 1.284.0 → 1.285.1

package/README.md

@@ -77,6 +77,16 @@ model gateways, and cloud agent execution behind an HTTP/SSE contract.
 
 Requirements: Node ≥ 20 (npm path) and an OpenAI-compatible model gateway.
 
+> **A note on the `glob@11` deprecation warning at install time.** `npm install` prints a deprecation
+> warning for `glob@11.1.0`, pulled in transitively by `e2b` (the E2B sandbox SDK). It is **install-time
+> noise with no runtime exposure here**: `glob` has exactly one load site inside `e2b` — a `dynamicImport`
+> in its *template-build* file-packing path — and this server only ever touches E2B's *sandbox runtime*
+> API. Verified by execution, not by reading: importing `e2b`, constructing the adapter and driving a real
+> `exec` never puts `glob` in the module cache. We cannot silence it for you — npm `overrides` only apply
+> when the package.json being read *is the project npm was invoked on*, so ours is ignored when this
+> package is installed as a dependency. If the warning bothers you, add `"overrides": { "glob": "^13" }`
+> to **your own** project's package.json (that is the one npm reads); the real fix is upstream in `e2b`.
+
 ```bash
 # A) npm
 npm install @sema-agent/server

package/dist/plugins/background-agent-store-sql.js

@@ -105,6 +105,7 @@ export async function ensureTiDBBackgroundAgentSchema(pool) {
     session_scoped TINYINT NOT NULL,
     session_id VARCHAR(190) NULL,
     parent_session_id VARCHAR(190) NULL,
+    -- core 1.367 δ(additive):root 锚(listBySession 第二臂;NULL = 该记录无 root 锚,谓词天然拒)
     root_session_id VARCHAR(190) NULL,
     session_anchor VARCHAR(190) NULL,
     name VARCHAR(255) NULL,
@@ -115,6 +116,8 @@ export async function ensureTiDBBackgroundAgentSchema(pool) {
     settled_at_ms BIGINT NULL,
     usage_json TEXT NULL,
     rev BIGINT NOT NULL,
+    -- core 1.383([1565] / design/153 件3a)ε:updateIf 的 CAS 守卫**专用列**——守卫必须在库侧对当前
+    -- 行状态原子求值,不能只靠 record_json blob(那要求先读后写,读写之间就是 CAS 本要堵的竞态窗)。
     parked_checkpoint_token VARCHAR(190) NULL,
     park_claim_id VARCHAR(190) NULL,
     record_json LONGTEXT NOT NULL,
@@ -122,18 +125,6 @@ export async function ensureTiDBBackgroundAgentSchema(pool) {
     KEY idx_bga_anchor (scope_key, session_anchor, spawned_at_ms),
     KEY idx_bga_status (scope_key, status, updated_at_ms)
   ) COLLATE utf8mb4_bin`);
-    const [rootCol] = (await pool.query(`SELECT 1 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = 'root_session_id'`, [BACKGROUND_AGENT_TABLE]));
-    if (rootCol.length === 0) {
-        await pool.query(`ALTER TABLE ${BACKGROUND_AGENT_TABLE} ADD COLUMN root_session_id VARCHAR(190) NULL AFTER parent_session_id`);
-    }
-    const [parkCols] = (await pool.query(`SELECT COLUMN_NAME FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME IN ('parked_checkpoint_token', 'park_claim_id')`, [BACKGROUND_AGENT_TABLE]));
-    const existingParkCols = new Set(parkCols.map((r) => r.COLUMN_NAME));
-    if (!existingParkCols.has("parked_checkpoint_token")) {
-        await pool.query(`ALTER TABLE ${BACKGROUND_AGENT_TABLE} ADD COLUMN parked_checkpoint_token VARCHAR(190) NULL`);
-    }
-    if (!existingParkCols.has("park_claim_id")) {
-        await pool.query(`ALTER TABLE ${BACKGROUND_AGENT_TABLE} ADD COLUMN park_claim_id VARCHAR(190) NULL`);
-    }
 }
 export async function ensurePgBackgroundAgentSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${BACKGROUND_AGENT_TABLE} (
@@ -144,6 +135,7 @@ export async function ensurePgBackgroundAgentSchema(q) {
     session_scoped BOOLEAN NOT NULL,
     session_id VARCHAR(190),
     parent_session_id VARCHAR(190),
+    -- core 1.367 δ(additive,TiDB 同案):root 锚(listBySession 第二臂)
     root_session_id VARCHAR(190),
     session_anchor VARCHAR(190),
     name VARCHAR(255),
@@ -154,6 +146,7 @@ export async function ensurePgBackgroundAgentSchema(q) {
     settled_at_ms BIGINT,
     usage_json TEXT,
     rev BIGINT NOT NULL,
+    -- core 1.383([1565] / design/153 件3a)ε(TiDB 同案注):updateIf 的 CAS 守卫专用列
     parked_checkpoint_token VARCHAR(190),
     park_claim_id VARCHAR(190),
     record_json TEXT NOT NULL,
@@ -161,9 +154,6 @@ export async function ensurePgBackgroundAgentSchema(q) {
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_bga_anchor ON ${BACKGROUND_AGENT_TABLE} (scope_key, session_anchor, spawned_at_ms)`);
     await q(`CREATE INDEX IF NOT EXISTS idx_bga_status ON ${BACKGROUND_AGENT_TABLE} (scope_key, status, updated_at_ms)`);
-    await q(`ALTER TABLE ${BACKGROUND_AGENT_TABLE} ADD COLUMN IF NOT EXISTS root_session_id VARCHAR(190)`);
-    await q(`ALTER TABLE ${BACKGROUND_AGENT_TABLE} ADD COLUMN IF NOT EXISTS parked_checkpoint_token VARCHAR(190)`);
-    await q(`ALTER TABLE ${BACKGROUND_AGENT_TABLE} ADD COLUMN IF NOT EXISTS park_claim_id VARCHAR(190)`);
 }
 export class TiDBBackgroundAgentStore {
     pool;

package/dist/plugins/pg-approval-store.js

@@ -6,6 +6,9 @@ export const PG_APPROVAL_SCHEMA = [
      task_id     VARCHAR(64),
      session_id  VARCHAR(64),
      owner       VARCHAR(190),
+     -- Single-DB fleet scope guard (tenant isolation). NULLABLE on purpose: a NULL-scope row is an untenanted
+     -- run, and every read/decide path matches it with \`scope IS NOT DISTINCT FROM $n\` (the PG twin of TiDB
+     -- \`<=>\`) so NULL matches only NULL and one tenant's scope NEVER matches another's.
      scope       VARCHAR(190),
      tool_name   VARCHAR(190) NOT NULL,
      args        JSONB,
@@ -16,7 +19,6 @@ export const PG_APPROVAL_SCHEMA = [
      decided_at  TIMESTAMPTZ(3),
      PRIMARY KEY (id)
    )`,
-    `ALTER TABLE approval ADD COLUMN IF NOT EXISTS scope VARCHAR(190)`,
     `CREATE INDEX IF NOT EXISTS idx_approval_owner_status ON approval (owner, status)`,
     `CREATE INDEX IF NOT EXISTS idx_approval_status ON approval (status)`,
     `CREATE INDEX IF NOT EXISTS idx_approval_scope_status ON approval (scope, status)`,

package/dist/plugins/pg-outcome-ledger.js

@@ -22,11 +22,13 @@ export const PG_OUTCOME_LEDGER_SCHEMA = [
      outcome        VARCHAR(8),
      llm_assisted   JSONB,
      signature_inputs JSONB,
+     -- design/73 §1 bridge: the VERBATIM core TaskOutcome fact (oracleHadRedRun / status / oracle blob) as it
+     -- came off core, kept alongside the derived mechanical columns. NULL when the caller recorded through the
+     -- non-core \`record()\` path (no core fact to bridge).
      core_outcome   JSONB,
      created_at     TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (id)
    )`,
-    `ALTER TABLE outcome_ledger ADD COLUMN IF NOT EXISTS core_outcome JSONB`,
     `CREATE INDEX IF NOT EXISTS idx_outcome_ledger_sig_model ON outcome_ledger (task_signature, model, run_status)`,
     `CREATE INDEX IF NOT EXISTS idx_outcome_ledger_outcome ON outcome_ledger (outcome)`,
     `CREATE INDEX IF NOT EXISTS idx_outcome_ledger_created ON outcome_ledger (created_at)`,

package/dist/plugins/pg-pool.js

@@ -111,6 +111,9 @@ export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS session_policy (
      policy_key CHAR(64)       NOT NULL,
      session_id VARCHAR(64)    NOT NULL,
+     -- 2c DENORMALIZED principal, carried solely so listBySession can ENUMERATE: policy_key is a one-way
+     -- sha256, so the principal is not recoverable from it. Enumeration-only — it is NOT part of the key and
+     -- NOT part of the CAS / tighten-only path. NULL = a session-wide (principal-less) policy row.
      principal  VARCHAR(190),
      rules      JSONB          NOT NULL,
      rev        BIGINT         NOT NULL,
@@ -118,7 +121,6 @@ export const PG_SCHEMA_STATEMENTS = [
      updated_at TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (policy_key)
    )`,
-    `ALTER TABLE session_policy ADD COLUMN IF NOT EXISTS principal VARCHAR(190)`,
     `CREATE INDEX IF NOT EXISTS idx_session_policy_session ON session_policy (session_id)`,
     `CREATE TABLE IF NOT EXISTS snapshot_manifest (
      scope     VARCHAR(64)   NOT NULL,
@@ -131,21 +133,30 @@ export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS snapshot_blob (
      blob_hash  CHAR(64)       PRIMARY KEY,
      byte_len   BIGINT         NOT NULL,
+     -- \`bytes\` is NULLABLE and that nullability is LOAD-BEARING, not laxness: a SQL-backend row carries the
+     -- bytes inline; a MinIO-backend row keeps ONLY the INDEX (blob_hash, byte_len, created_at) here with
+     -- bytes NULL — the bytes themselves live in MinIO. The orphan/grace reference-tracking (gcOrphanBlobs /
+     -- reap / deleteBySession / sweepOrphanBlobs) reads snapshot_blob, so it works IDENTICALLY for BOTH
+     -- backends (and an E21 purge can delete the MinIO object). See blob-backend.ts MinioBlobBackend.
+     -- ⇒ NEVER re-add NOT NULL here: it would make the MinIO-backend index-only row un-insertable.
      bytes      BYTEA          NULL,
      created_at TIMESTAMPTZ(3) NOT NULL
    )`,
     `CREATE INDEX IF NOT EXISTS idx_snapshot_blob_created ON snapshot_blob (created_at)`,
-    `ALTER TABLE snapshot_blob ALTER COLUMN bytes DROP NOT NULL`,
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id     VARCHAR(191) NOT NULL,
      ordinal    INT          NOT NULL,
+     -- SVC-2 / CORE-9 audit BLOCKER: cross-tenant resume isolation (the WorkflowJournalStore seam takes a scope
+     -- param). NOT NULL DEFAULT '' — a row written without a scope lands in the '' bucket, which is
+     -- CROSS-SCOPE-ORPHANED but harmless: a real resume always filters \`WHERE scope = <caller>\`, so '' rows are
+     -- never handed to a tenant. Keep the DEFAULT: it is what makes a scope-less write land in that dead bucket
+     -- instead of failing or leaking into a real tenant's scope.
      scope      VARCHAR(190) NOT NULL DEFAULT '',
      call_key   VARCHAR(255) NOT NULL,
      result     TEXT         NOT NULL,
      created_at BIGINT       NOT NULL,
      PRIMARY KEY (run_id, ordinal)
    )`,
-    `ALTER TABLE workflow_journal ADD COLUMN IF NOT EXISTS scope VARCHAR(190) NOT NULL DEFAULT ''`,
     `CREATE TABLE IF NOT EXISTS workflow_run (
      id         VARCHAR(191) NOT NULL,
      scope      VARCHAR(190) NOT NULL,
@@ -166,13 +177,21 @@ export const PG_SCHEMA_STATEMENTS = [
      status      VARCHAR(16)  NOT NULL,
      summary     TEXT         NOT NULL,
      enqueued_at BIGINT       NOT NULL,
+     -- 1.109 delivery envelope. kind NULL = a LEGACY \`workflow_complete\` row (the shape that predates the
+     -- envelope); readers must keep treating NULL as that kind, it is not "unknown". payload = the kind's
+     -- body, NULL for the legacy shape.
      kind        VARCHAR(24),
      payload     TEXT,
-     PRIMARY KEY (session_id, run_id)
+     PRIMARY KEY (session_id, run_id),
+     -- Twin-alignment with TiDB's \`UNIQUE KEY uq_wfinbox_seq (seq)\` (same constraint name on purpose, so the two
+     -- schemas can be diffed by name). This is NOT a correctness fix: seq is BIGSERIAL, so it is already unique in
+     -- practice, and the only seq-keyed write — the overflow trim \`DELETE … WHERE session_id = $1 AND seq = ANY(…)\`
+     -- — is fenced by its session_id predicate, so a hypothetical duplicate seq could not cross sessions anyway.
+     -- What it buys: the implicit "BIGSERIAL is unique" assumption behind \`ORDER BY seq\` (the inbox's total order)
+     -- becomes MACHINE-ENFORCED rather than merely conventional, in both engines.
+     CONSTRAINT uq_wfinbox_seq UNIQUE (seq)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_wfinbox_session_seq ON workflow_completion_inbox (session_id, seq)`,
-    `ALTER TABLE workflow_completion_inbox ADD COLUMN IF NOT EXISTS kind VARCHAR(24)`,
-    `ALTER TABLE workflow_completion_inbox ADD COLUMN IF NOT EXISTS payload TEXT`,
     `CREATE TABLE IF NOT EXISTS workflow_inbox_fence (
      session_id  VARCHAR(190) NOT NULL,
      kind        VARCHAR(8)   NOT NULL,

package/dist/plugins/pg-session-storage.js

@@ -23,11 +23,12 @@ export const PG_SESSION_SCHEMA = [
      updated_at  TIMESTAMPTZ(3) NOT NULL,
      leaf_id     VARCHAR(64),
      leaf_seq    BIGINT       NOT NULL DEFAULT 0,
+     -- Write-once auto-title (setTitleIfNull / probeTitle): NULL = "untitled", i.e. still claimable; the
+     -- three-state probe distinguishes it from "no such session". PG twin of the TiDB COLUMN_MIGRATIONS leg.
      title       VARCHAR(120),
      PRIMARY KEY (session_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_session_meta_owner ON session_meta (owner)`,
-    `ALTER TABLE session_meta ADD COLUMN IF NOT EXISTS title VARCHAR(120)`,
     `CREATE TABLE IF NOT EXISTS session_event (
      session_id  VARCHAR(64) NOT NULL,
      seq         BIGINT      NOT NULL,

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

@@ -27,27 +27,19 @@ export async function ensureTiDBRosterSchema(pool) {
     agent_id VARCHAR(190) NOT NULL,
     session_id VARCHAR(190) NULL,
     tool_use_id VARCHAR(190) NULL,
+    -- owner/scope:core 1.365 BREAKING 双轴必填(default-deny 谓词的两根轴;顶注 ① 记了曾 nullable 的由来)
     owner VARCHAR(190) NOT NULL,
     scope VARCHAR(190) NOT NULL,
     session_scoped TINYINT NULL,
+    -- core 1.367 δ(additive):RosterEntry.rootSessionId verbatim 存(枚举/恢复读者;谓词暂无臂)
     root_session_id VARCHAR(190) NULL,
+    -- core 1.373 additive:spawn 记录的解析后模型 id(NULL = 该 spawn 未记录模型)
     model VARCHAR(190) NULL,
     created_at_ms BIGINT NOT NULL,
     recorded_at_ms BIGINT NOT NULL,
     PRIMARY KEY (name_key, owner_key, scope_key),
     KEY idx_roster_agent (agent_id)
   ) COLLATE utf8mb4_bin`);
-    await pool.query(`DELETE FROM ${ROSTER_TABLE} WHERE owner IS NULL OR scope IS NULL`);
-    await pool.query(`ALTER TABLE ${ROSTER_TABLE} MODIFY COLUMN owner VARCHAR(190) NOT NULL`);
-    await pool.query(`ALTER TABLE ${ROSTER_TABLE} MODIFY COLUMN scope VARCHAR(190) NOT NULL`);
-    const [rootCol] = (await pool.query(`SELECT 1 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = 'root_session_id'`, [ROSTER_TABLE]));
-    if (rootCol.length === 0) {
-        await pool.query(`ALTER TABLE ${ROSTER_TABLE} ADD COLUMN root_session_id VARCHAR(190) NULL AFTER session_scoped`);
-    }
-    const [modelCol] = (await pool.query(`SELECT 1 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = 'model'`, [ROSTER_TABLE]));
-    if (modelCol.length === 0) {
-        await pool.query(`ALTER TABLE ${ROSTER_TABLE} ADD COLUMN model VARCHAR(190) NULL AFTER root_session_id`);
-    }
 }
 export async function ensurePgRosterSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${ROSTER_TABLE} (
@@ -58,21 +50,19 @@ export async function ensurePgRosterSchema(q) {
     agent_id VARCHAR(190) NOT NULL,
     session_id VARCHAR(190),
     tool_use_id VARCHAR(190),
+    -- owner/scope:core 1.365 BREAKING 双轴必填(TiDB 同案;曾 nullable 的由来见两 ensure 上方顶注 ①)
     owner VARCHAR(190) COLLATE "C" NOT NULL,
     scope VARCHAR(190) COLLATE "C" NOT NULL,
     session_scoped BOOLEAN,
+    -- core 1.367 δ(additive,TiDB 同案):RosterEntry.rootSessionId verbatim 存
     root_session_id VARCHAR(190),
+    -- core 1.373 additive(TiDB 同案):解析后模型 id(NULL = 该 spawn 未记录模型)
     model VARCHAR(190),
     created_at_ms BIGINT NOT NULL,
     recorded_at_ms BIGINT NOT NULL,
     PRIMARY KEY (name_key, owner_key, scope_key)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_roster_agent ON ${ROSTER_TABLE} (agent_id)`);
-    await q(`DELETE FROM ${ROSTER_TABLE} WHERE owner IS NULL OR scope IS NULL`);
-    await q(`ALTER TABLE ${ROSTER_TABLE} ALTER COLUMN owner SET NOT NULL`);
-    await q(`ALTER TABLE ${ROSTER_TABLE} ALTER COLUMN scope SET NOT NULL`);
-    await q(`ALTER TABLE ${ROSTER_TABLE} ADD COLUMN IF NOT EXISTS root_session_id VARCHAR(190)`);
-    await q(`ALTER TABLE ${ROSTER_TABLE} ADD COLUMN IF NOT EXISTS model VARCHAR(190)`);
 }
 function upsertParams(entry, now) {
     return [

package/dist/plugins/tidb-pool.js

@@ -33,6 +33,8 @@ export const SCHEMA_STATEMENTS = [
      updated_at  DATETIME(3)  NOT NULL,
      leaf_id     VARCHAR(64)  NULL,
      leaf_seq    BIGINT       NOT NULL DEFAULT 0,
+     -- title: auto-generated session title (cheap-model one-liner at first submit; write-once via
+     -- setTitleIfNull — the user-facing RENAME layer lives BFF-side as a label overlay, not here).
      title       VARCHAR(120) NULL,
      PRIMARY KEY (session_id),
      KEY idx_owner (owner)
@@ -55,21 +57,46 @@ export const SCHEMA_STATEMENTS = [
      status      VARCHAR(16)  NOT NULL,
      result      JSON         NULL,
      error       TEXT         NULL,
+     -- error_code: the structured failure code denormalized out of the result blob (tidb-run-store fail()).
+     -- ⚠️ NO DESIGN PROVENANCE ON RECORD: its ADD COLUMN seam carried no rationale comment and neither git
+     -- history nor any doc records who asked for it (verified 2026-07-26 while folding the seams in). The only
+     -- consumer today is the projection (getRun/listRuns → errorCode) — nothing FILTERS on it; see the
+     -- deliberately-absent idx_error_code note below.
      error_code  VARCHAR(64)  NULL,
      instance_id VARCHAR(64)  NULL,
+     -- job_id (work-view correlation substrate): groups the runs of one logical task across BOTH client doors.
      job_id      VARCHAR(64)  NULL,
+     -- source (credential-derived system identity, clay 2026-06-12): which door submitted the run
+     -- (oa / cc-mcp / portal).
      source      VARCHAR(64)  NULL,
+     -- objective_preview: the list's "what is this task" glance — redacted + truncated at write.
      objective_preview VARCHAR(160) NULL,
+     -- cancel_requested: durable cross-replica CANCEL flag. The running instance's heartbeat tick honors it
+     -- (+ a local AbortController fast path when the cancel lands on the same replica).
+     -- Terminal = "failed" + errorCode:"cancelled".
      cancel_requested TINYINT(1) NOT NULL DEFAULT 0,
+     -- preempt_requested (design/80 seam #2): durable cross-replica PREEMPT flag — the SCHEDULER's graceful
+     -- "yield this task" (≠ cancel's kill). The owning instance's heartbeat tick honors it (+ a local
+     -- preemptSignal fast path when the preempt lands on the same replica) → the task durably SUSPENDS at the
+     -- next clean turn boundary (gate resource_limit, reason preempt) and is resumable. Reset to 0 on resume
+     -- (markResuming) so a resumed leg is not re-preempted by a stale flag (the durable twin of core's
+     -- pre-aborted-signal strip).
      preempt_requested TINYINT(1) NOT NULL DEFAULT 0,
      created_at  DATETIME(3)  NOT NULL,
      updated_at  DATETIME(3)  NOT NULL,
      PRIMARY KEY (task_id),
      KEY idx_session_status (session_id, status),
      KEY idx_owner (owner),
-     KEY idx_error_code (error_code),
+     -- idx_job: WHERE job_id = ? (work-view grouping) would full-scan without it.
      KEY idx_job (job_id),
+     -- idx_created: listRuns ALWAYS ORDER BY created_at DESC — without this the trace list does a filesort on
+     -- every query (deepseek council #2). Covers the unfiltered newest-first list; filtered lists narrow via
+     -- idx_owner / idx_job first.
      KEY idx_created (created_at)
+     -- ⛔ DELIBERATELY NO KEY idx_error_code (error_code) (dropped 2026-07-26, clay 裁): a whole-repo sweep found
+     -- ZERO code paths that filter on error_code — every reference is a SET or a projection — so the index only
+     -- ever served an operator's ad-hoc WHERE error_code LIKE 'budget.%', while every task_run write paid its
+     -- maintenance cost. If you need that ad-hoc query, build the index temporarily and drop it after.
    )`,
     `CREATE TABLE IF NOT EXISTS circuit_breaker (
      breaker_key VARCHAR(190) NOT NULL,
@@ -122,6 +149,11 @@ export const SCHEMA_STATEMENTS = [
      task_id     VARCHAR(64)  NULL,
      session_id  VARCHAR(64)  NULL,
      owner       VARCHAR(190) NULL,
+     -- scope — single-DB fleet scope guard (defense-in-depth): the run's tenant identity (owner-sourced), so the
+     -- approval READ paths (getStatus / get / listPending / decide) can null-safe-filter on it. A NULL scope row
+     -- (an untenanted run — and, on the pre-folding schema, any PRE-MIGRATION row) is matched by a NULL scope arg
+     -- via MySQL <=> / PG IS NOT DISTINCT FROM — see tidb-approval-store.ts / pg-approval-store.ts.
+     -- expireStale deliberately stays GLOBAL (fleet maintenance, not a tenant read).
      scope       VARCHAR(190) NULL,
      tool_name   VARCHAR(190) NOT NULL,
      args        JSON         NULL,
@@ -132,6 +164,7 @@ export const SCHEMA_STATEMENTS = [
      decided_at  DATETIME(3)  NULL,
      PRIMARY KEY (id),
      KEY idx_owner_status (owner, status),
+     -- idx_scope_status: the scope-filtered READ paths (listPending WHERE scope <=> ?) would full-scan without it.
      KEY idx_scope_status (scope, status),
      KEY idx_status (status)
    )`,
@@ -143,18 +176,48 @@ export const SCHEMA_STATEMENTS = [
      status       VARCHAR(16)  NOT NULL DEFAULT 'pending',
      tool_name    VARCHAR(190) NULL,
      tool_call_id VARCHAR(190) NULL,
+     -- tool_input: the pending-approval tool args = the approval card's payload, surfaced in listPending so the
+     -- BFF need not N+1-fetch trace.turns per pending item. Redacted + bounded at put().
+     -- NULL on PRE-MIGRATION rows (suspended before the column existed) ⇒ the consumer falls back.
      tool_input   JSON         NULL,
      checkpoint   JSON         NOT NULL,
      outcome      JSON         NULL,
      deadline     BIGINT       NULL,
      created_at   BIGINT       NOT NULL,
      decided_at   BIGINT       NULL,
+     -- rev (design/80 D-1): monotonic optimistic-concurrency counter bumped on every resolve/reopen, so a
+     -- resolve(expect) requires the rev the resume observed to still be live → fail-closed on a concurrent
+     -- resolve-reopen cycle (core → checkpoint.reopened_concurrently).
+     -- PRE-MIGRATION rows ⇒ 0 (the LEGACY CONTRACT; core's .d.ts spells it "Absent ⇒ legacy 0").
      rev          BIGINT       NOT NULL DEFAULT 0,
+     -- reopen_reason — reopen-by-reason: env_failed (a re-resume MUST replay the persisted winner) vs
+     -- tool_unavailable (a fresh decision is allowed). Drives core's reopen-revote validation.
+     -- NULL = NEVER REOPENED (the first resume is unconstrained).
      reopen_reason VARCHAR(32)  NULL,
+     -- terminal_at: crash-safe ABSOLUTE lifetime backstop (design/80 §3 inv#3), distinct from the per-approval
+     -- deadline, stamped at put(). NULL on PRE-MIGRATION rows — those keep their DEADLINE-BASED expiry (the old
+     -- path); the backstop only covers rows suspended after the column existed.
      terminal_at  BIGINT       NULL,
+     -- gate_kind (design/80 D-D, SLA-timer): the CheckpointGate.kind, stamped at put(), so the SLA sweep splits by
+     -- kind WITHOUT parsing the JSON blob per row — human/irreversible_ask past deadline are resolve-DENIED (the
+     -- model continues with a denial), resource_limit/needs_review are abandonment-TTL → expire().
+     -- NULL (a PRE-MIGRATION row, or a gate carrying no kind) ⇒ the LEGACY UNIFORM expire() path: the deny split
+     -- is NEW-ROWS-ONLY. See tidb-checkpoint-store.ts reapExpired / listExpiredApprovalGates.
      gate_kind    VARCHAR(32)  NULL,
+     -- bound_input_hash (design/80 D-1): the server-minted opaque boundInputHash, stamped at put() from
+     -- pendingAction.boundInputHash, surfaced via listPending so the operator/portal can ECHO it on /decide (the
+     -- D-1 TOCTOU binding guard is UNREACHABLE by the portal without it — it can then only do the unbound legacy
+     -- fallback). NULL on PRE-D-1 rows ⇒ that unbound fallback.
      bound_input_hash VARCHAR(190) NULL,
+     -- pending_steer (design/80 D-A, durable steering): the parked steer ({text,trusted} JSON) set by
+     -- setPendingSteer on a STILL-PENDING checkpoint (last-writer-wins, CAS on status='pending'), surfaced via
+     -- get() as state.pendingSteer so core injects it on resume. NULL when no steer is parked.
+     -- Never touches status/resolve (design/80 inv #4).
      pending_steer TEXT         NULL,
+     -- risk_descriptor (design/80 riskDescriptor inbox): core's INERT CheckpointGate.riskDescriptor ({severity
+     -- 1-5, axes, toolName, redacted summary, touchedPaths}), stamped at put() so listPending can surface it +
+     -- triage-sort the supervisor inbox by severity DESC — WITHOUT parsing the checkpoint blob per row.
+     -- NULL on gates with no descriptor.
      risk_descriptor TEXT        NULL,
      PRIMARY KEY (token),
      KEY idx_status_deadline (status, deadline),
@@ -200,6 +263,10 @@ export const SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS session_policy (
      policy_key CHAR(64)     NOT NULL,
      session_id VARCHAR(64)  NOT NULL,
+     -- principal (2c session-sync): DENORMALIZED so listBySession can ENUMERATE a session's per-principal rows
+     -- (the sha256 policy_key is one-way → the principal is not recoverable from it). Enumeration-ONLY: not a key,
+     -- not part of the CAS/tighten logic — putRules just writes it. NULL = the session-wide row (principal
+     -- undefined). PRE-MIGRATION rows (E6 was new when the column landed) ⇒ NULL, i.e. read as session-wide.
      principal  VARCHAR(190) NULL,
      rules      JSON         NOT NULL,
      rev        BIGINT       NOT NULL,
@@ -219,6 +286,13 @@ export const SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS snapshot_blob (
      blob_hash  CHAR(64)    NOT NULL,
      byte_len   BIGINT      NOT NULL,
+     -- bytes is NULLABLE — and that nullability IS the two-backend reference-tracking contract (see the block
+     -- comment above; this column is where it is enforced). It was originally LONGBLOB NOT NULL back when the
+     -- SQL store was the ONLY blob backend; the MinIO offload then required an INDEX-ONLY row here (bytes NULL,
+     -- the bytes living in MinIO) so that gcOrphanBlobs / reap / deleteBySession (E21 purge) / sweepOrphanBlobs
+     -- keep computing the orphan/grace SET from snapshot_blob for BOTH backends identically — and so an E21 purge
+     -- can DELETE the MinIO object instead of leaking it. Re-adding NOT NULL here would silently break MinIO-mode
+     -- reference tracking. See blob-backend.ts MinioBlobBackend.
      bytes      LONGBLOB    NULL,
      created_at DATETIME(3) NOT NULL,
      PRIMARY KEY (blob_hash),
@@ -227,6 +301,12 @@ export const SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id     VARCHAR(191) NOT NULL,
      ordinal    INT          NOT NULL,
+     -- scope (SVC-2 / CORE-9 audit BLOCKER): the table predates scope — it was added when the
+     -- WorkflowJournalStore seam grew a scope param for cross-tenant resume isolation. Every new append writes the
+     -- run's REAL scope. EXISTING (pre-migration) rows carry '' = CROSS-SCOPE ORPHANS, harmless by construction: a
+     -- real resume filters WHERE scope = <caller>, so the blank-scope residue never matches a tenant. The
+     -- NOT NULL DEFAULT '' is what let the original ALTER succeed on a table that already had rows — keep the
+     -- default so the "'' = orphan, never a tenant" reading stays true.
      scope      VARCHAR(190) NOT NULL DEFAULT '',
      call_key   VARCHAR(255) NOT NULL,
      result     MEDIUMTEXT   NOT NULL,
@@ -253,7 +333,14 @@ export const SCHEMA_STATEMENTS = [
      status      VARCHAR(16)  NOT NULL,
      summary     TEXT         NOT NULL,
      enqueued_at BIGINT       NOT NULL,
+     -- kind (1.109): task_notification entries SHARE this inbox — kind discriminates the drain frame family.
+     -- 🔴 NULL = a legacy workflow_complete row, AND it stays a LIVE value: the workflow_complete enqueue path
+     -- never sets kind, so new rows are written NULL too. The read side has the matching compat branch —
+     -- tidb-workflow-run-store.ts projects kind only when non-null and workflow-completion-inbox.ts routes
+     -- kind === "task_notification" vs everything-else. Do NOT "tidy" this into NOT NULL DEFAULT.
      kind        VARCHAR(24)  NULL,
+     -- payload: bounded + redacted JSON extras (task_type / result / …) for the task_notification family.
+     -- NULL for legacy / plain workflow_complete rows.
      payload     TEXT         NULL,
      PRIMARY KEY (session_id, run_id),
      UNIQUE KEY uq_wfinbox_seq (seq),
@@ -299,6 +386,8 @@ export const SCHEMA_STATEMENTS = [
      outcome        VARCHAR(8)   NULL,
      llm_assisted   JSON         NULL,
      signature_inputs JSON       NULL,
+     -- core_outcome (design/73 §1 bridge): the VERBATIM core TaskOutcome fact
+     -- (oracleHadRedRun / status / oracle blob). The PG twin adds it via ADD COLUMN IF NOT EXISTS.
      core_outcome   JSON         NULL,
      created_at     DATETIME(3)  NOT NULL,
      PRIMARY KEY (id),
@@ -390,37 +479,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (pool)
    )`,
 ];
-const COLUMN_MIGRATIONS = [
-    { table: "session_meta", column: "title", ddl: "ALTER TABLE session_meta ADD COLUMN title VARCHAR(120) NULL" },
-    { table: "outcome_ledger", column: "core_outcome", ddl: "ALTER TABLE outcome_ledger ADD COLUMN core_outcome JSON NULL" },
-    { table: "workflow_completion_inbox", column: "kind", ddl: "ALTER TABLE workflow_completion_inbox ADD COLUMN kind VARCHAR(24) NULL" },
-    { table: "workflow_completion_inbox", column: "payload", ddl: "ALTER TABLE workflow_completion_inbox ADD COLUMN payload TEXT NULL" },
-    { table: "task_run", column: "error_code", ddl: "ALTER TABLE task_run ADD COLUMN error_code VARCHAR(64) NULL" },
-    { table: "task_run", column: "job_id", ddl: "ALTER TABLE task_run ADD COLUMN job_id VARCHAR(64) NULL" },
-    { table: "task_run", column: "cancel_requested", ddl: "ALTER TABLE task_run ADD COLUMN cancel_requested TINYINT(1) NOT NULL DEFAULT 0" },
-    { table: "task_run", column: "preempt_requested", ddl: "ALTER TABLE task_run ADD COLUMN preempt_requested TINYINT(1) NOT NULL DEFAULT 0" },
-    { table: "task_run", column: "source", ddl: "ALTER TABLE task_run ADD COLUMN source VARCHAR(64) NULL" },
-    { table: "task_run", column: "objective_preview", ddl: "ALTER TABLE task_run ADD COLUMN objective_preview VARCHAR(160) NULL" },
-    { table: "checkpoint", column: "tool_input", ddl: "ALTER TABLE checkpoint ADD COLUMN tool_input JSON NULL" },
-    { table: "checkpoint", column: "rev", ddl: "ALTER TABLE checkpoint ADD COLUMN rev BIGINT NOT NULL DEFAULT 0" },
-    { table: "checkpoint", column: "reopen_reason", ddl: "ALTER TABLE checkpoint ADD COLUMN reopen_reason VARCHAR(32) NULL" },
-    { table: "checkpoint", column: "terminal_at", ddl: "ALTER TABLE checkpoint ADD COLUMN terminal_at BIGINT NULL" },
-    { table: "checkpoint", column: "gate_kind", ddl: "ALTER TABLE checkpoint ADD COLUMN gate_kind VARCHAR(32) NULL" },
-    { table: "checkpoint", column: "bound_input_hash", ddl: "ALTER TABLE checkpoint ADD COLUMN bound_input_hash VARCHAR(190) NULL" },
-    { table: "checkpoint", column: "pending_steer", ddl: "ALTER TABLE checkpoint ADD COLUMN pending_steer TEXT NULL" },
-    { table: "checkpoint", column: "risk_descriptor", ddl: "ALTER TABLE checkpoint ADD COLUMN risk_descriptor TEXT NULL" },
-    { table: "approval", column: "scope", ddl: "ALTER TABLE approval ADD COLUMN scope VARCHAR(190) NULL" },
-    { table: "session_policy", column: "principal", ddl: "ALTER TABLE session_policy ADD COLUMN principal VARCHAR(190) NULL" },
-    { table: "workflow_journal", column: "scope", ddl: "ALTER TABLE workflow_journal ADD COLUMN scope VARCHAR(190) NOT NULL DEFAULT ''" },
-];
-const INDEX_MIGRATIONS = [
-    { table: "task_run", index: "idx_job", ddl: "CREATE INDEX idx_job ON task_run (job_id)" },
-    { table: "task_run", index: "idx_created", ddl: "CREATE INDEX idx_created ON task_run (created_at)" },
-    { table: "approval", index: "idx_scope_status", ddl: "CREATE INDEX idx_scope_status ON approval (scope, status)" },
-];
-const NULLABILITY_MIGRATIONS = [
-    { table: "snapshot_blob", column: "bytes", ddl: "ALTER TABLE snapshot_blob MODIFY COLUMN bytes LONGBLOB NULL" },
-];
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
 export async function acquireEnsureSchemaLock(conn, tag = "ensureSchema") {
     await new Promise((r) => setTimeout(r, Math.floor(Math.random() * 400)));
@@ -454,42 +512,6 @@ export async function ensureSchema(pool) {
             await conn.query(stmt);
         }
         await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES ('standard')");
-        for (const m of COLUMN_MIGRATIONS) {
-            const [rows] = await conn.query("SELECT 1 FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = ? AND column_name = ? LIMIT 1", [m.table, m.column]);
-            if (rows.length === 0) {
-                try {
-                    await conn.query(m.ddl);
-                }
-                catch (err) {
-                    if (Number(err.errno) !== 1060)
-                        throw err;
-                }
-            }
-        }
-        for (const m of INDEX_MIGRATIONS) {
-            const [rows] = await conn.query("SELECT 1 FROM information_schema.statistics WHERE table_schema = DATABASE() AND table_name = ? AND index_name = ? LIMIT 1", [m.table, m.index]);
-            if (rows.length === 0) {
-                try {
-                    await conn.query(m.ddl);
-                }
-                catch (err) {
-                    if (Number(err.errno) !== 1061)
-                        throw err;
-                }
-            }
-        }
-        for (const m of NULLABILITY_MIGRATIONS) {
-            const [rows] = await conn.query("SELECT 1 FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = ? AND column_name = ? AND is_nullable = 'YES' LIMIT 1", [m.table, m.column]);
-            if (rows.length === 0) {
-                try {
-                    await conn.query(m.ddl);
-                }
-                catch (err) {
-                    if (Number(err.errno) !== 1060)
-                        throw err;
-                }
-            }
-        }
     }
     finally {
         if (locked)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "1.284.0",
+  "version": "1.285.1",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",