@sema-agent/server 7.124.1 → 7.125.1

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

@@ -2,7 +2,7 @@ import type { TaskStatus } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
-import { type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { type CreateRunOutcome, type NewRunMeta, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import { type SqlDriver } from "./sql-driver.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 export type { RunRecord, SessionSummary, RunEvent, LatestRunRef } from "./store-contracts.js";
@@ -20,23 +20,27 @@ export declare class SqlRunStore {
     /** Run statements atomically; rolls back on failure. */
     private tx;
     /**
-     * Create a run, but only if the session has no other active run (double-text guard).
+     * Create a run, but only if the session has no other active run (double-text guard) and no submission key
+     * of this request already names a row (submission idempotency) — **atomic win or observe**.
      *
      * 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).
+     *
+     * Submission idempotency rides the SAME mechanism on the row itself: `task_run` carries two unique keys a
+     * submission can name — `task_id` (a caller-minted `body.taskId`) and `idem_key` (the scoped
+     * `Idempotency-Key`; NULL = none, which neither dialect's UNIQUE constrains). Claim + row are ONE
+     * transaction, so a concurrent same-key submit on another replica either commits first (we collide on the
+     * unique index — after its commit, PG/InnoDB/TiDB-pessimistic block on the uncommitted entry; TiDB-optimistic
+     * reports it at COMMIT, which is why the commit sits inside the same classification) or loses to us.
+     *
+     * Any dup-key ⇒ roll back (our claim goes with it) ⇒ OBSERVE, keys first: a row named by `idem_key`, else by
+     * `task_id` ⇒ `{ ok:false, existing }` (no new row; the submission surface renders the receipt); otherwise the
+     * session claim was the collision ⇒ `{ ok:false, activeTaskId }`. A dup on the ROW insert that names no
+     * observable row is not attributable to either key ⇒ rethrown (loud), never reported as a busy session.
      */
-    createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: {
-        jobId?: string | null;
-        source?: string | null;
-        objectivePreview?: string | null;
-    }): Promise<{
-        ok: true;
-    } | {
-        ok: false;
-        activeTaskId: string;
-    }>;
+    createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: NewRunMeta): Promise<CreateRunOutcome>;
     /** 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.
@@ -134,6 +138,16 @@ export declare class SqlRunStore {
      *  (今天没有消费点,所以没人发现)。列表收成一个常量 = 这类漏选从此不可能发生。 */
     private rowToRun;
     getRun(taskId: string): Promise<RunRecord | undefined>;
+    /** The row a submission's keys name — `idem_key` first, then `task_id` — read on the caller's (already rolled-back) connection. */
+    private observeSubmittedRow;
+    /** The run a submission's `Idempotency-Key` names (`idem_key` = the scoped key, `idemKeyOf(raw, caller, "run")`), if any.
+     *  `uq_task_run_idem` makes it at most one row. */
+    getRunByIdem(idemKey: string): Promise<RunRecord | undefined>;
+    /** Undo THIS submission's key binding (`idem_key` → NULL) — called only where the submit surface refuses the submission
+     *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, a device-placement reject):
+     *  the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
+     *  is the refusal's record); only the key is freed. */
+    releaseIdemKey(taskId: string): Promise<void>;
     /** 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).

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

@@ -74,40 +74,48 @@ export class SqlRunStore {
         }
     }
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
+        const idemKey = meta.idemKey ?? null;
         const conn = await this.db.connect();
+        let stage = "claim";
         try {
             await conn.begin();
             const now = new Date();
             try {
                 await conn.query(this.q("INSERT INTO task_active (session_id, task_id, since) VALUES (?,?,?)", "INSERT INTO task_active (session_id, task_id, since) VALUES ($1,$2,$3)"), [sessionId, taskId, now]);
+                stage = "row";
+                await conn.query(this.q("INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, objective_preview, idem_key, created_at, updated_at) " +
+                    "VALUES (?,?,?,'running',?,?,?,?,?,?,?)", "INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, objective_preview, idem_key, created_at, updated_at) " +
+                    "VALUES ($1,$2,$3,'running',$4,$5,$6,$7,$8,$9,$10)"), [
+                    taskId,
+                    sessionId,
+                    owner,
+                    instanceId,
+                    meta.jobId ?? null,
+                    meta.source ?? null,
+                    this.db.dialect === "tidb"
+                        ? meta.objectivePreview ?? null
+                        : meta.objectivePreview == null
+                            ? null
+                            : pgSanitizeText(meta.objectivePreview),
+                    idemKey,
+                    now,
+                    now,
+                ]);
+                await conn.commit();
+                return { ok: true };
             }
             catch (err) {
-                if (this.isDupKey(err)) {
-                    await conn.rollback();
-                    const { rows: active } = await conn.query(this.q("SELECT task_id FROM task_active WHERE session_id = ?", "SELECT task_id FROM task_active WHERE session_id = $1"), [sessionId]);
-                    return { ok: false, activeTaskId: String(active[0]?.task_id ?? "") };
-                }
-                throw err;
+                if (!this.isDupKey(err))
+                    throw err;
+                await conn.rollback();
+                const existing = await this.observeSubmittedRow(conn, taskId, idemKey);
+                if (existing)
+                    return { ok: false, existing };
+                if (stage === "row")
+                    throw err;
+                const { rows: active } = await conn.query(this.q("SELECT task_id FROM task_active WHERE session_id = ?", "SELECT task_id FROM task_active WHERE session_id = $1"), [sessionId]);
+                return { ok: false, activeTaskId: String(active[0]?.task_id ?? "") };
             }
-            await conn.query(this.q("INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, objective_preview, created_at, updated_at) " +
-                "VALUES (?,?,?,'running',?,?,?,?,?,?)", "INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, objective_preview, created_at, updated_at) " +
-                "VALUES ($1,$2,$3,'running',$4,$5,$6,$7,$8,$9)"), [
-                taskId,
-                sessionId,
-                owner,
-                instanceId,
-                meta.jobId ?? null,
-                meta.source ?? null,
-                this.db.dialect === "tidb"
-                    ? meta.objectivePreview ?? null
-                    : meta.objectivePreview == null
-                        ? null
-                        : pgSanitizeText(meta.objectivePreview),
-                now,
-                now,
-            ]);
-            await conn.commit();
-            return { ok: true };
         }
         catch (err) {
             try {
@@ -228,6 +236,22 @@ export class SqlRunStore {
         const { rows } = await this.db.query(this.q(`SELECT ${runRowCols("tidb")} FROM task_run WHERE task_id = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE task_id = $1`), [taskId]);
         return rows[0] ? this.rowToRun(rows[0]) : undefined;
     }
+    async observeSubmittedRow(conn, taskId, idemKey) {
+        if (idemKey !== null) {
+            const { rows } = await conn.query(this.q(`SELECT ${runRowCols("tidb")} FROM task_run WHERE idem_key = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE idem_key = $1`), [idemKey]);
+            if (rows[0])
+                return this.rowToRun(rows[0]);
+        }
+        const { rows } = await conn.query(this.q(`SELECT ${runRowCols("tidb")} FROM task_run WHERE task_id = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE task_id = $1`), [taskId]);
+        return rows[0] ? this.rowToRun(rows[0]) : undefined;
+    }
+    async getRunByIdem(idemKey) {
+        const { rows } = await this.db.query(this.q(`SELECT ${runRowCols("tidb")} FROM task_run WHERE idem_key = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE idem_key = $1`), [idemKey]);
+        return rows[0] ? this.rowToRun(rows[0]) : undefined;
+    }
+    async releaseIdemKey(taskId) {
+        await this.db.query(this.q("UPDATE task_run SET idem_key = NULL WHERE task_id = ?", "UPDATE task_run SET idem_key = NULL WHERE task_id = $1"), [taskId]);
+    }
     async listRuns(opts) {
         if (opts.cursor && Number.isNaN(Date.parse(opts.cursor.createdAt)))
             return [];
@@ -360,6 +384,7 @@ export class SqlRunStore {
             lastRunId: r.task_id ?? null,
             ...(typeof lastTaskRunId === "string" && lastTaskRunId !== "" ? { lastTaskRunId } : {}),
             title: null,
+            pinned: false,
         };
     }
     async deleteBySession(sessionId, expectedSessionOwner) {

package/dist/plugins/schema-consistency.d.ts

@@ -32,6 +32,7 @@
  * `recordFailOpen` 在这条腿上**不适用** —— 它是 F 类(装饰/缓存)的登记口,不是 P 类保护臂的逃生门。
  */
 import { type SchemaDialect } from "./schema-ensure-legs.js";
+import { type SchemaProbeRead } from "./schema-live-columns.js";
 /** 一列:名字 + 它在 `CREATE TABLE` 里的**原样定义文本**(生成 ADD COLUMN 指路用,不另手写)。 */
 export interface ParsedColumn {
     readonly name: string;
@@ -62,19 +63,6 @@ export interface TableMismatch {
     /** 库有、代码没有(库比代码**新** —— 滚动窗里的旧副本)。 */
     readonly ghost: readonly string[];
 }
-/** 探针读口:一条 SQL → 行数组(两方言由调用方各自绑)。 */
-export type SchemaProbeRead = (sql: string) => Promise<Array<Record<string, unknown>>>;
-/**
- * 库里实际的列集(表名 → 列名集合)。
- *
- * 🔴 **PG 侧读的是「查询真正会解析到的那个关系」,不是 `current_schema()`**(codex 对抗复审本轮 [medium]
- * 采纳):店里的 SQL 全是**不限定 schema** 的裸表名,它按 `search_path` **逐个** schema 解析,命中第一个;
- * 而 `current_schema()` 只是路径的第一段。两者不等的部署是真的存在(角色的 `search_path` 配了多段),那时
- * 只读第一段会让探针对「表其实住在路径后段、而且缺列」这一形**完全沉默**。⇒ 按 `current_schemas(false)`
- * 的**顺序**取每张表的第一次命中 —— 探针于是与执行器看同一张表。MySQL 协议没有这个概念(库 = 连接上的
- * `DATABASE()`),那条臂一个字不变。
- */
-export declare function readLiveColumns(read: SchemaProbeRead, dialect: SchemaDialect): Promise<Map<string, Set<string>>>;
 /** 对账(纯函数:期望 × 实况 → 不符表清单)。 */
 export declare function diffSchema(expected: Map<string, ParsedTable>, live: Map<string, Set<string>>): TableMismatch[];
 /** 拒启文案(表名 + 缺/多列 + 两条路;ADD COLUMN 句由解析结果**生成**)。 */

package/dist/plugins/schema-consistency.js

@@ -1,4 +1,5 @@
 import { recordEnsureStatements } from "./schema-ensure-legs.js";
+import { readLiveColumns } from "./schema-live-columns.js";
 const QUOTES = new Set(["'", '"', "`"]);
 function stripLineComments(sql) {
     let out = "";
@@ -104,47 +105,6 @@ export async function expectedTableShapes(dialect) {
     return shapes;
 }
 export const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
-export async function readLiveColumns(read, dialect) {
-    const live = new Map();
-    if (dialect !== "pg") {
-        for (const row of await read("SELECT table_name AS t, column_name AS c FROM information_schema.columns WHERE table_schema = DATABASE()")) {
-            addColumn(live, row["t"], row["c"], "fold");
-        }
-        return live;
-    }
-    const order = new Map();
-    for (const row of await read("SELECT s AS s, ord AS ord FROM unnest(current_schemas(false)) WITH ORDINALITY AS t(s, ord)")) {
-        const s = String(row["s"] ?? "");
-        if (s !== "")
-            order.set(s, Number(row["ord"]));
-    }
-    const winner = new Map();
-    for (const row of await read("SELECT table_schema AS s, table_name AS t, column_name AS c FROM information_schema.columns WHERE table_schema = ANY (current_schemas(false))")) {
-        const t = String(row["t"] ?? "");
-        const rank = order.get(String(row["s"] ?? "")) ?? Number.MAX_SAFE_INTEGER;
-        const held = winner.get(t);
-        if (held !== undefined && rank > held)
-            continue;
-        if (held === undefined || rank < held) {
-            winner.set(t, rank);
-            live.delete(t);
-        }
-        addColumn(live, t, row["c"], "verbatim");
-    }
-    return live;
-}
-function addColumn(live, table, column, mode) {
-    const t = mode === "fold" ? String(table ?? "").toLowerCase() : String(table ?? "");
-    const c = mode === "fold" ? String(column ?? "").toLowerCase() : String(column ?? "");
-    if (t === "" || c === "")
-        return;
-    let set = live.get(t);
-    if (set === undefined) {
-        set = new Set();
-        live.set(t, set);
-    }
-    set.add(c);
-}
 export function diffSchema(expected, live) {
     const out = [];
     for (const [table, shape] of expected) {

package/dist/plugins/schema-indexes.js

@@ -3,6 +3,7 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "task_run", name: "idx_task_run_owner", columns: ["owner"] },
     { table: "task_run", name: "idx_task_run_created", columns: ["created_at"] },
     { table: "task_run", name: "idx_task_run_job", columns: ["job_id"] },
+    { table: "task_run", name: "uq_task_run_idem", columns: ["idem_key"], unique: true },
     { table: "task_active", name: "idx_task_active_task", columns: ["task_id"] },
     { table: "checkpoint", name: "idx_checkpoint_status_deadline", columns: ["status", "deadline"] },
     { table: "checkpoint", name: "idx_checkpoint_session_status", columns: ["session_id", "status"] },

package/dist/plugins/schema-live-columns.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 库里**实际**的列集 —— 唯一读者(S-547 列册探针 `schema-consistency.ts` 的对账读它;`ensure-index.ts` 的索引补建在失败之后判「是不是这张表
+ * 缺这条索引的列」也读它)。叶子模块:不值依赖任何模块(列册探针那边经录制驱动 / 建表腿值依赖 `ensure-index.ts`,读者若住在那边,
+ * `ensure-index.ts` 读它就是一个运行时环)。方言词是 `ensure-index.ts` 的闭集(类型边,擦除)。
+ */
+import type { SqlDialect } from "./ensure-index.js";
+/** 探针读口:一条 SQL → 行数组(两方言由调用方各自绑)。 */
+export type SchemaProbeRead = (sql: string) => Promise<Array<Record<string, unknown>>>;
+/**
+ * 库里实际的列集(表名 → 列名集合)。
+ *
+ * 🔴 **PG 侧读的是「查询真正会解析到的那个关系」,不是 `current_schema()`**(codex 对抗复审本轮 [medium]
+ * 采纳):店里的 SQL 全是**不限定 schema** 的裸表名,它按 `search_path` **逐个** schema 解析,命中第一个;
+ * 而 `current_schema()` 只是路径的第一段。两者不等的部署是真的存在(角色的 `search_path` 配了多段),那时
+ * 只读第一段会让探针对「表其实住在路径后段、而且缺列」这一形**完全沉默**。⇒ 按 `current_schemas(false)`
+ * 的**顺序**取每张表的第一次命中 —— 探针于是与执行器看同一张表。MySQL 协议没有这个概念(库 = 连接上的
+ * `DATABASE()`),那条臂一个字不变。
+ */
+export declare function readLiveColumns(read: SchemaProbeRead, dialect: SqlDialect): Promise<Map<string, Set<string>>>;
+//# sourceMappingURL=schema-live-columns.d.ts.map

package/dist/plugins/schema-live-columns.js

@@ -0,0 +1,42 @@
+export async function readLiveColumns(read, dialect) {
+    const live = new Map();
+    if (dialect !== "pg") {
+        for (const row of await read("SELECT table_name AS t, column_name AS c FROM information_schema.columns WHERE table_schema = DATABASE()")) {
+            addColumn(live, row["t"], row["c"], "fold");
+        }
+        return live;
+    }
+    const order = new Map();
+    for (const row of await read("SELECT s AS s, ord AS ord FROM unnest(current_schemas(false)) WITH ORDINALITY AS t(s, ord)")) {
+        const s = String(row["s"] ?? "");
+        if (s !== "")
+            order.set(s, Number(row["ord"]));
+    }
+    const winner = new Map();
+    for (const row of await read("SELECT table_schema AS s, table_name AS t, column_name AS c FROM information_schema.columns WHERE table_schema = ANY (current_schemas(false))")) {
+        const t = String(row["t"] ?? "");
+        const rank = order.get(String(row["s"] ?? "")) ?? Number.MAX_SAFE_INTEGER;
+        const held = winner.get(t);
+        if (held !== undefined && rank > held)
+            continue;
+        if (held === undefined || rank < held) {
+            winner.set(t, rank);
+            live.delete(t);
+        }
+        addColumn(live, t, row["c"], "verbatim");
+    }
+    return live;
+}
+function addColumn(live, table, column, mode) {
+    const t = mode === "fold" ? String(table ?? "").toLowerCase() : String(table ?? "");
+    const c = mode === "fold" ? String(column ?? "").toLowerCase() : String(column ?? "");
+    if (t === "" || c === "")
+        return;
+    let set = live.get(t);
+    if (set === undefined) {
+        set = new Set();
+        live.set(t, set);
+    }
+    set.add(c);
+}
+//# sourceMappingURL=schema-live-columns.js.map

package/dist/plugins/store-contracts.d.ts

@@ -221,6 +221,40 @@ export interface RunRecord {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * `RunStore.createRun` 的行元数据(写进 `task_run` 的附加列)。
+ *
+ * `idemKey` = 这次提交的幂等键(唯一铸法 `idemKeyOf(raw, caller, "run")`,`http/idempotency.ts`;sha256 hex 定宽 64)。
+ * 缺席 / `null` = 调用方没带 `Idempotency-Key` ⇒ 列 NULL,不参与去重(UNIQUE 不约束 NULL,两方言同形)。
+ */
+export interface NewRunMeta {
+    jobId?: string | null;
+    source?: string | null;
+    objectivePreview?: string | null;
+    idemKey?: string | null;
+}
+/**
+ * `RunStore.createRun` 的结局 —— 三形,一形一句话:
+ *  · `{ ok: true }` —— 新行已建、会话 claim 已拿;
+ *  · `{ ok: false, existing }` —— 这次提交的一把**幂等钥匙**已经指向一条行:`idem_key`(`Idempotency-Key`)或
+ *    `task_id`(调用方自铸的 `body.taskId`)—— 两把钥匙是**同一条律**(资源行上的唯一键),先认 `idem_key` 再认 `task_id`。
+ *    这是「原子赢或观察」的**观察**臂:行原样交回,没建新行、没动会话;回执由提交面的唯一回执函数判。
+ *  · `{ ok: false, activeTaskId }` —— 会话被**别的** run 占着(双发守卫),没建行。
+ * 另两位在每一形上恒 `undefined`(读 `created.existing` / `created.activeTaskId` 不用先窄化,判别仍是穷举的)。
+ */
+export type CreateRunOutcome = {
+    ok: true;
+    existing?: undefined;
+    activeTaskId?: undefined;
+} | {
+    ok: false;
+    existing: RunRecord;
+    activeTaskId?: undefined;
+} | {
+    ok: false;
+    existing?: undefined;
+    activeTaskId: string;
+};
 /**
  * `RunRecord["status"]`(= `"running" | TaskStatus`)的**唯一分类表** —— 词表的属主 = 判据的属主,
  * 与类型定义同住一个文件。四个类:
@@ -402,9 +436,13 @@ export interface SessionSummary {
      *  零迁移路线 —— result 在终局与 park 时写、认领续跑即清空(S-173)⇒ 在跑 run 键诚实缺席);OMIT-when-absent,恒不铸 null。轴辨析与
      *  wire 半场见 `security.ts SessionListItem.lastTaskRunId`(同名同义)。 */
     lastTaskRunId?: string;
-    /** The auto-generated session title (cheap-model one-liner, write-once). null = not (yet)
-     *  titled OR the lister face has no session_meta (the legacy task_run aggregate / memory twins — honest degrade). */
+    /** The session's title: the user's (`patchSessionMeta`, unconditional; `null` clears it back to automatic) or the auto-titler's
+     *  (cheap-model one-liner, `setTitleIfNull` — fills NULL only). null = not (yet) titled OR the lister face has no session_meta (the legacy
+     *  task_run aggregate / memory twins — honest degrade). Writer order: `src/session-row.ts`. */
     title: string | null;
+    /** Pinned by the user (`patchSessionMeta`). Always present, `false` by default; the legacy task_run aggregate / memory
+     *  twins answer `false` (no session_meta ⇒ nothing there can pin it). */
+    pinned: boolean;
 }
 /**
  * S-1371 —— 会话**枚举面**读 run 账里「每会话的 run 投影」的窄读面:`runCount` / `lastStatus` / `lastRunId` / `lastTaskRunId` 四位,

package/dist/plugins/tidb-cost-quota.d.ts

@@ -5,7 +5,7 @@
  * `maxCostUsd` gate). `scope_key` is opaque (principal today; team/feature later — [ref] N3).
  */
 import type { Pool } from "mysql2/promise";
-import type { QuotaDecision, QuotaLimits, QuotaTracker } from "../observability/cost-quota.js";
+import { type QuotaDecision, type QuotaLimits, type QuotaTracker } from "../observability/cost-quota.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class TiDBCostQuota implements QuotaTracker {
     private readonly counter;

package/dist/plugins/tidb-cost-quota.js

@@ -1,3 +1,4 @@
+import { decideQuota } from "../observability/cost-quota.js";
 import { WriteBehindCounter } from "./write-behind-counter.js";
 export class TiDBCostQuota {
     counter;
@@ -22,11 +23,7 @@ export class TiDBCostQuota {
             this.counter.stop();
     }
     check(scopeKey) {
-        if (this.limitMicroUsd <= 0)
-            return { allowed: true, usedMicroUsd: 0, limitMicroUsd: 0, retryAfterSec: 0 };
-        const used = this.counter.used(scopeKey);
-        const allowed = used < this.limitMicroUsd;
-        return { allowed, usedMicroUsd: used, limitMicroUsd: this.limitMicroUsd, retryAfterSec: allowed ? 0 : this.counter.retryAfterSec() };
+        return decideQuota(this.limitMicroUsd, this.counter.window(), (bucket) => this.counter.usedIn(scopeKey, bucket));
     }
     add(scopeKey, micro) {
         if (this.limitMicroUsd <= 0)

package/dist/plugins/tidb-pool.js

@@ -7,6 +7,7 @@ import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
 import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
 import { SESSION_META_INCARNATION_COLUMN } from "../session-incarnation.js";
+import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 import { SESSION_INDEXES } from "./pg-session-storage.js";
@@ -56,9 +57,13 @@ 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,
+     -- title: ONE column, two writers, one law (src/session-row.ts): the user's write (PATCH /v1/sessions/:id →
+     -- patchSessionMeta, unconditional; null = cleared back to the automatic title) and the auto-titler (cheap-model
+     -- one-liner on a submit that finds it NULL; setTitleIfNull, fills NULL only) — a user-set title is never overwritten,
+     -- a cleared one is filled again. Width = SESSION_TITLE_MAX_CHARS (the wire bound).
+     title       VARCHAR(${SESSION_TITLE_MAX_CHARS}) NULL,
+     -- pinned: the user's pin (PATCH /v1/sessions/:id → patchSessionMeta); every list row carries it, false by default.
+     pinned      BOOLEAN      NOT NULL DEFAULT FALSE,
      -- instruction_source(S-690):本会话**上一次 run** 选中的项目指令文件 = 换源通告(instructions.source_changed)
      -- 的基线。NULL = 还没有任何 run 记过(首 run 只写不发);'' = 记过、那一次没有项目指令文件;其余 = 链成员相对路径
      -- (CLAUDE.md / .claude/CLAUDE.md / AGENTS.md / .claude/AGENTS.md)。服务端元数据:不进模型上下文、不进 wire
@@ -160,9 +165,15 @@ export const SCHEMA_STATEMENTS = [
      -- (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,
+     -- idem_key: the submission's scoped Idempotency-Key (sha256 hex, fixed width 64; minted only by
+     -- http/idempotency.ts idemKeyOf, resource family run). The ONE enforcement point of submission idempotency for
+     -- runs: uq_task_run_idem makes createRun an atomic win-or-observe across replicas and restarts. NULL = the caller
+     -- sent no key (UNIQUE does not constrain NULL; same on both dialects).
+     idem_key    VARCHAR(64)  NULL,
      created_at  DATETIME(3)  NOT NULL,
      updated_at  DATETIME(3)  NOT NULL,
      PRIMARY KEY (task_id),
+     UNIQUE KEY uq_task_run_idem (idem_key),
      KEY idx_task_run_session_status (session_id, status),
      KEY idx_task_run_owner (owner),
      -- idx_job: WHERE job_id = ? (work-view grouping) would full-scan without it.

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

@@ -15,6 +15,7 @@ import type { Pool } from "mysql2/promise";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type SessionFace } from "../session-incarnation.js";
 import type { SessionSummary } from "./store-contracts.js";
+import type { SessionRowPatch } from "../session-row.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 export declare class TiDBSessionStore implements SessionStore {
@@ -115,11 +116,30 @@ export declare class TiDBSessionStore implements SessionStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** ONE session's list row — {@link listSessions}' projection (same SELECT, same mapper) scoped to one id; `undefined` = not a
+     *  row of the list face (no such session / placed). The run-preview subqueries are scoped to the same id (an index read on
+     *  `task_run.session_id`, not the whole-ledger aggregate the list pays). */
+    sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
+    /** The session row's writable bits — the ONLY writer of a user-set title / pin (writer order: `src/session-row.ts`):
+     *  `title` unconditional (a string = the user's title — the auto-titler's {@link setTitleIfNull} fills NULL only, so it always
+     *  wins; `null` = cleared back to the automatic title, which the auto-titler fills again on a later submit), `pinned` as given.
+     *  Only a row of the list face takes it (`placement_kind IS NULL`), and only the occupant the caller verified (`incarnation = ?`
+     *  from `face` — a session deleted and re-registered by anyone after the caller's gate is another occupant: zero rows updated).
+     *  The read-back carries the same condition, so the answer is that occupant's list row or `undefined` (the decision does not
+     *  read `affectedRows`: an UPDATE that wrote identical values and one that matched nothing differ there by driver flags, the
+     *  conditioned read-back does not). `updated_at` is NOT touched (a rename is not activity — the list's newest-first order stays put). */
+    patchSessionMeta(sessionId: string, patch: SessionRowPatch, face: SessionFace): Promise<SessionSummary | undefined>;
+    /**
+     * The list projection's ONE SELECT + row mapper ({@link listSessions} and {@link sessionSummaryOf} both read through it).
+     * `runSessionId` scopes the two run-preview subqueries to one session (the single-row read); the list leaves them whole.
+     * Placeholder order follows the text: subquery params, then `where` params, then the LIMIT.
+     */
+    private selectSummaries;
     /** Cheap pre-LLM probe: "none" = session_meta row not yet REGISTERED (createRun fires
      *  before the Runner's session acquire — the titler retries), "untitled" / "titled" as read. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
-    /** Write-once auto-title: lands ONLY when title IS NULL (a concurrent/prior title wins;
-     *  the user-facing rename layer is BFF-side). Returns whether this call set it. */
+    /** The auto-titler's write: lands ONLY when title IS NULL (a concurrent/prior title — the user's included — wins;
+     *  writer order: `src/session-row.ts`). Returns whether this call set it. */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
     /**
      * S-690 —— 换源通告的基线读(一行 PK SELECT;列的三态读法见 `tidb-pool.ts` 的列注)。行不在 ⇒ 读作「没记过」

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

@@ -153,18 +153,44 @@ export class TiDBSessionStore {
             where.push("(sm.updated_at < ? OR (sm.updated_at = ? AND sm.session_id < ?))");
             params.push(new Date(opts.cursor.lastActivityAt), new Date(opts.cursor.lastActivityAt), opts.cursor.sessionId);
         }
-        const sql = "SELECT sm.session_id, sm.owner, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, " +
+        return this.selectSummaries({ where, params, limit: opts.limit });
+    }
+    async sessionSummaryOf(sessionId) {
+        const rows = await this.selectSummaries({ where: ["sm.placement_kind IS NULL", "sm.session_id = ?"], params: [sessionId], limit: 1, runSessionId: sessionId });
+        return rows[0];
+    }
+    async patchSessionMeta(sessionId, patch, face) {
+        const sets = [];
+        const params = [];
+        if (patch.title !== undefined) {
+            sets.push("title = ?");
+            params.push(patch.title);
+        }
+        if (patch.pinned !== undefined) {
+            sets.push("pinned = ?");
+            params.push(patch.pinned);
+        }
+        if (sets.length > 0) {
+            params.push(sessionId, face.incarnation);
+            await this.pool.query(`UPDATE session_meta SET ${sets.join(", ")} WHERE session_id = ? AND incarnation = ? AND placement_kind IS NULL`, params);
+        }
+        const rows = await this.selectSummaries({ where: ["sm.placement_kind IS NULL", "sm.session_id = ?", "sm.incarnation = ?"], params: [sessionId, face.incarnation], limit: 1, runSessionId: sessionId });
+        return rows[0];
+    }
+    async selectSummaries(q) {
+        const runWhere = q.runSessionId !== undefined ? " WHERE session_id = ?" : "";
+        const runParams = q.runSessionId !== undefined ? [q.runSessionId, q.runSessionId] : [];
+        const sql = "SELECT sm.session_id, sm.owner, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, sm.pinned, " +
             "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
             "FROM session_meta sm " +
-            "LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run GROUP BY session_id) r ON r.session_id = sm.session_id " +
+            "LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run" + runWhere + " GROUP BY session_id) r ON r.session_id = sm.session_id " +
             "LEFT JOIN (SELECT session_id, objective_preview, status, task_id, last_task_run_id FROM (" +
             "    SELECT session_id, objective_preview, status, task_id, JSON_UNQUOTE(JSON_EXTRACT(result, '$.runId')) AS last_task_run_id, " +
-            "      ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn FROM task_run" +
+            "      ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn FROM task_run" + runWhere +
             "  ) lr WHERE rn = 1) latest ON latest.session_id = sm.session_id " +
-            (where.length ? "WHERE " + where.join(" AND ") + " " : "") +
+            (q.where.length ? "WHERE " + q.where.join(" AND ") + " " : "") +
             "ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ?";
-        params.push(opts.limit);
-        const [rows] = await this.pool.query(sql, params);
+        const [rows] = await this.pool.query(sql, [...runParams, ...q.params, q.limit]);
         return rows.map((r) => {
             const runId = r.last_task_run_id;
             return {
@@ -178,6 +204,7 @@ export class TiDBSessionStore {
                 lastRunId: r.last_run_id ?? null,
                 ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
                 title: r.title ?? null,
+                pinned: Number(r.pinned) === 1,
             };
         });
     }

package/dist/plugins/write-behind-counter.d.ts

@@ -16,8 +16,9 @@
  * up to (replicas × per-flush-interval spend/requests) at the boundary before peers' totals propagate.
  * Right for cost/fairness ceilings (and backstopped, for cost, by the hard per-task `maxCostUsd` gate).
  * A HARD compliance ceiling would instead need a linearizable CAS/atomic count, not write-behind — same
- * trade as the cross-replica circuit breaker. Windows are aligned fixed buckets (`floor(now/windowMs)`),
- * the standard distributed choice (a rolling per-key window is the hard part to coordinate cross-replica).
+ * trade as the cross-replica circuit breaker. Windows are clock-aligned fixed buckets — the ONE anchor
+ * {@link alignedWindow} (`observability/cost-quota.ts`), shared with the in-memory cost quota — the standard
+ * distributed choice (a rolling per-key window is the hard part to coordinate cross-replica).
  *
  * ── Dialect deltas, kept EXPLICIT (the four the PG twins' file headers used to list) ──────────────────
  *   - placeholders `?` vs `$1..$n`
@@ -32,6 +33,7 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+import { type AlignedWindow } from "../observability/cost-quota.js";
 export interface CounterTable {
     /** Table name; must have columns (<keyCol>, window_bucket BIGINT, <valCol>, updated_at). */
     table: string;
@@ -80,12 +82,17 @@ export declare class SqlWriteBehindCounter {
     /** S9: track the consecutive-failure streak per kind and notify on every failure + on the recovery edge
      *  (streak>0 → 0). Steady healthy state stays silent. The hook must never break the counter. */
     private bump;
+    /** One clock read → the current aligned window (bucket + end), via the ONE anchor {@link alignedWindow}. */
+    window(): AlignedWindow;
     bucket(): number;
     private rk;
-    /** Cached fleet total (peers, from the last refresh) + this replica's unflushed delta, current window. */
+    /** Cached fleet total (peers, from the last refresh) + this replica's unflushed delta, in `bucket`
+     *  (the caller's own clock read — a decision reads its spend and its window end from ONE `now`). */
+    usedIn(key: string, bucket: number): number;
+    /** {@link usedIn} for the current window. */
     used(key: string): number;
     addLocal(key: string, n: number): void;
-    /** Seconds until the current aligned window rolls over. */
+    /** Seconds until the current aligned window rolls over (the ONE formula {@link retryAfterSecUntil}). */
     retryAfterSec(): number;
     /** Atomically push pending deltas, then refresh the current window's fleet totals + reap old buckets.
      *  Reentrancy-guarded: two overlapping flushes would each apply `+delta` from the same snapshot and
@@ -111,7 +118,7 @@ export declare class SqlWriteBehindCounter {
     /**
      * [ref] 批1:窗长换代(`costQuotaWindowSec` 热更新)。
      *
-     * 🔴 如实语义:窗长是**桶键的一部分**(`floor(now/windowMs)`),不是行里的一个可改字段。换窗长 ⇒ 当代
+     * 🔴 如实语义:窗长是**桶键的一部分**(桶号由 {@link alignedWindow} 算),不是行里的一个可改字段。换窗长 ⇒ 当代
      * 桶重算 ⇒ 本副本对「当前窗已用多少」的读数从新桶起算(旧桶的行还在库里,按它自己的窗长归属)。
      * 未 flush 的本地增量仍带着**它自己的**桶键(rowKey 里已含),所以它们仍落回原来那个桶,不会被搬家。
      * 这与限额值的换代不同(那个是纯比较参数,窗内计数一个不动),因此单独成注:运营改窗长要知道自己在