@sema-agent/server 7.124.1 → 7.125.1

package/dist/observability/cost-quota.js

@@ -1,3 +1,24 @@
+export const COST_QUOTA_WINDOW_SEC_RANGE = { min: 1, max: 1e10 };
+export function costQuotaWindowSecInRange(sec) {
+    return Number.isFinite(sec) && sec >= COST_QUOTA_WINDOW_SEC_RANGE.min && sec <= COST_QUOTA_WINDOW_SEC_RANGE.max;
+}
+export function alignedWindow(now, windowMs) {
+    const bucket = Math.floor(now / windowMs);
+    return { now, bucket, windowEndsAtMs: (bucket + 1) * windowMs };
+}
+export function retryAfterSecUntil(w) {
+    return Math.max(0, Math.ceil((w.windowEndsAtMs - w.now) / 1000));
+}
+export function decideQuota(limitMicroUsd, w, readUsed) {
+    if (limitMicroUsd <= 0)
+        return { allowed: true, usedMicroUsd: 0, limitMicroUsd: 0, retryAfterSec: 0, windowEndsAtMs: w.windowEndsAtMs };
+    const usedMicroUsd = readUsed(w.bucket);
+    const allowed = usedMicroUsd < limitMicroUsd;
+    return { allowed, usedMicroUsd, limitMicroUsd, retryAfterSec: allowed ? 0 : retryAfterSecUntil(w), windowEndsAtMs: w.windowEndsAtMs };
+}
+export function quotaWindowResetsAt(d) {
+    return new Date(d.windowEndsAtMs).toISOString();
+}
 export class CostQuota {
     now;
     windows = new Map();
@@ -16,33 +37,26 @@ export class CostQuota {
         }
     }
     check(key) {
-        if (this.limitMicroUsd <= 0)
-            return { allowed: true, usedMicroUsd: 0, limitMicroUsd: 0, retryAfterSec: 0 };
-        const t = this.now();
-        const w = this.windows.get(key);
-        const live = w && t - w.start < this.windowMs;
-        const used = live ? w.micro : 0;
-        const allowed = used < this.limitMicroUsd;
-        const retryAfterSec = !allowed && live ? Math.ceil((w.start + this.windowMs - t) / 1000) : 0;
-        return { allowed, usedMicroUsd: used, limitMicroUsd: this.limitMicroUsd, retryAfterSec };
+        return decideQuota(this.limitMicroUsd, alignedWindow(this.now(), this.windowMs), (bucket) => this.windows.get(entryKey(key, bucket))?.micro ?? 0);
     }
     add(key, micro) {
         if (this.limitMicroUsd <= 0)
             return;
         if (micro <= 0)
             return;
-        const t = this.now();
-        const w = this.windows.get(key);
-        if (!w || t - w.start >= this.windowMs)
-            this.windows.set(key, { start: t, micro });
+        const { bucket } = alignedWindow(this.now(), this.windowMs);
+        const k = entryKey(key, bucket);
+        const e = this.windows.get(k);
+        if (e)
+            e.micro += micro;
         else
-            w.micro += micro;
+            this.windows.set(k, { bucket, micro });
     }
     reap() {
-        const t = this.now();
+        const { bucket } = alignedWindow(this.now(), this.windowMs);
         let dropped = 0;
-        for (const [k, w] of this.windows) {
-            if (t - w.start >= this.windowMs) {
+        for (const [k, e] of this.windows) {
+            if (e.bucket < bucket) {
                 this.windows.delete(k);
                 dropped++;
             }
@@ -50,4 +64,8 @@ export class CostQuota {
         return dropped;
     }
 }
+const SEP = "\u0000";
+function entryKey(key, bucket) {
+    return `${key}${SEP}${bucket}`;
+}
 //# sourceMappingURL=cost-quota.js.map

package/dist/observability/fail-open.d.ts

@@ -225,7 +225,7 @@ export declare const FAIL_OPEN_TAGS: {
     };
     readonly "server.hooks.matcher-unjudged": {
         readonly cls: "F";
-        readonly note: "S-995(`hooks/hook-runner.ts` 的 `deadToolMatcherIssue`,fresh 受理面「工具事件 matcher 选中别名而选不中正名 ⇒ 400」判据的**未判**臂;detail = `event=… reason=… matcherChars=…`,不带 matcher 原字节):一只 matcher 没能被判 ⇒ 照旧受理。判据一条顺序、两档共用(7.114.0 修复轮):长度上限 → 空 / `*` → 字面读法(两档都先走、不占预算)→ 正则形。三种 reason 同一个 tag —— `oversize`(两档:超 8 192 字符不读;多租户车道上 hooks 不装配,这一笔只为让超长输入显形)/ `over_budget`(regex 档正则形:一次受理共享的 100 ms 墙钟预算用尽,`node:vm` 的 timeout 打断正则回溯)/ `invalid_regex`(regex 档正则形编不过;确定性的坏配置,运行期另记 `hook_matcher_invalid`,拒它是新检测臂、不在本规则)。**不记**的:literal 档(多租户车道)遇正则形 = 不适用 —— 该车道 hooks 整只不装配,没有被守的对象,不是未判。放行的最坏后果 = **那一只 matcher 没被这条判据守住**:它若真写了别名,照旧永不命中(7.112.0 对正则形一律不判,同一后果);**不是安全闸**(受理面的有效性判 = S-924 的「响亮」,决定不了任何放行 / 拒绝 / 权限;hook 的 deny 语义在运行期 hook-runner)。反方向(越界即拒)会把负载抖动 / 病态但合法的 matcher 变成对合法请求的 400。拒放集合相对 7.113.0 的一处放宽:超过上限的字面别名 matcher 7.113.0 拒、7.114.0 两档未判受理(已披露)。计数让「受理面一直判不了」(攻击者喂灾难正则 / 超长 matcher)显形。";
+        readonly note: "S-995(`hooks/hook-runner.ts` 的 `deadToolMatcherIssue`,fresh 受理面「工具事件 matcher 选中别名而选不中正名 ⇒ 400」判据的**未判**臂;detail = `event=… reason=… matcherChars=…`,不带 matcher 原字节):一只 matcher 没能被判 ⇒ 照旧受理。判据一条顺序、两档共用(7.114.0 修复轮):长度上限 → 形只问契约包的 `hookMatcherForm`(literal 形〔名字表 / 空 / `*`〕两档都直接问 `hookMatcherSelects`、不占预算;regex 形 regex 档把同一只契约函数交进 vm 带预算、literal 档不适用;invalid 形 regex 档直接记 `invalid_regex`、literal 档不适用)。三种 reason 同一个 tag —— `oversize`(两档:超 8 192 字符不读;多租户车道上 hooks 不装配,这一笔只为让超长输入显形)/ `over_budget`(regex 档正则形:一次受理共享的 100 ms 墙钟预算用尽,`node:vm` 的 timeout 打断正则回溯)/ `invalid_regex`(regex 档正则形编不过;确定性的坏配置,运行期另记 `hook_matcher_invalid`,拒它是新检测臂、不在本规则)。**不记**的:literal 档(多租户车道)遇正则形 = 不适用 —— 该车道 hooks 整只不装配,没有被守的对象,不是未判。放行的最坏后果 = **那一只 matcher 没被这条判据守住**:它若真写了别名,照旧永不命中(7.112.0 对正则形一律不判,同一后果);**不是安全闸**(受理面的有效性判 = S-924 的「响亮」,决定不了任何放行 / 拒绝 / 权限;hook 的 deny 语义在运行期 hook-runner)。反方向(越界即拒)会把负载抖动 / 病态但合法的 matcher 变成对合法请求的 400。拒放集合相对 7.113.0 的一处放宽:超过上限的字面别名 matcher 7.113.0 拒、7.114.0 两档未判受理(已披露)。计数让「受理面一直判不了」(攻击者喂灾难正则 / 超长 matcher)显形。";
     };
     readonly "server.hooks.notice-sink-threw": {
         readonly cls: "F";

package/dist/observability/fail-open.js

@@ -206,7 +206,7 @@ export const FAIL_OPEN_TAGS = {
     },
     "server.hooks.matcher-unjudged": {
         cls: "F",
-        note: "S-995(`hooks/hook-runner.ts` 的 `deadToolMatcherIssue`,fresh 受理面「工具事件 matcher 选中别名而选不中正名 ⇒ 400」判据的**未判**臂;detail = `event=… reason=… matcherChars=…`,不带 matcher 原字节):一只 matcher 没能被判 ⇒ 照旧受理。判据一条顺序、两档共用(7.114.0 修复轮):长度上限 → 空 / `*` → 字面读法(两档都先走、不占预算)→ 正则形。三种 reason 同一个 tag —— `oversize`(两档:超 8 192 字符不读;多租户车道上 hooks 不装配,这一笔只为让超长输入显形)/ `over_budget`(regex 档正则形:一次受理共享的 100 ms 墙钟预算用尽,`node:vm` 的 timeout 打断正则回溯)/ `invalid_regex`(regex 档正则形编不过;确定性的坏配置,运行期另记 `hook_matcher_invalid`,拒它是新检测臂、不在本规则)。**不记**的:literal 档(多租户车道)遇正则形 = 不适用 —— 该车道 hooks 整只不装配,没有被守的对象,不是未判。放行的最坏后果 = **那一只 matcher 没被这条判据守住**:它若真写了别名,照旧永不命中(7.112.0 对正则形一律不判,同一后果);**不是安全闸**(受理面的有效性判 = S-924 的「响亮」,决定不了任何放行 / 拒绝 / 权限;hook 的 deny 语义在运行期 hook-runner)。反方向(越界即拒)会把负载抖动 / 病态但合法的 matcher 变成对合法请求的 400。拒放集合相对 7.113.0 的一处放宽:超过上限的字面别名 matcher 7.113.0 拒、7.114.0 两档未判受理(已披露)。计数让「受理面一直判不了」(攻击者喂灾难正则 / 超长 matcher)显形。",
+        note: "S-995(`hooks/hook-runner.ts` 的 `deadToolMatcherIssue`,fresh 受理面「工具事件 matcher 选中别名而选不中正名 ⇒ 400」判据的**未判**臂;detail = `event=… reason=… matcherChars=…`,不带 matcher 原字节):一只 matcher 没能被判 ⇒ 照旧受理。判据一条顺序、两档共用(7.114.0 修复轮):长度上限 → 形只问契约包的 `hookMatcherForm`(literal 形〔名字表 / 空 / `*`〕两档都直接问 `hookMatcherSelects`、不占预算;regex 形 regex 档把同一只契约函数交进 vm 带预算、literal 档不适用;invalid 形 regex 档直接记 `invalid_regex`、literal 档不适用)。三种 reason 同一个 tag —— `oversize`(两档:超 8 192 字符不读;多租户车道上 hooks 不装配,这一笔只为让超长输入显形)/ `over_budget`(regex 档正则形:一次受理共享的 100 ms 墙钟预算用尽,`node:vm` 的 timeout 打断正则回溯)/ `invalid_regex`(regex 档正则形编不过;确定性的坏配置,运行期另记 `hook_matcher_invalid`,拒它是新检测臂、不在本规则)。**不记**的:literal 档(多租户车道)遇正则形 = 不适用 —— 该车道 hooks 整只不装配,没有被守的对象,不是未判。放行的最坏后果 = **那一只 matcher 没被这条判据守住**:它若真写了别名,照旧永不命中(7.112.0 对正则形一律不判,同一后果);**不是安全闸**(受理面的有效性判 = S-924 的「响亮」,决定不了任何放行 / 拒绝 / 权限;hook 的 deny 语义在运行期 hook-runner)。反方向(越界即拒)会把负载抖动 / 病态但合法的 matcher 变成对合法请求的 400。拒放集合相对 7.113.0 的一处放宽:超过上限的字面别名 matcher 7.113.0 拒、7.114.0 两档未判受理(已披露)。计数让「受理面一直判不了」(攻击者喂灾难正则 / 超长 matcher)显形。",
     },
     "server.hooks.notice-sink-threw": {
         cls: "F",

package/dist/observability/run-terminal.d.ts

@@ -103,15 +103,11 @@ export declare function redactErrorMessage(raw: string | undefined): string | un
  * 它**不是第二只脱敏器**:零自有规则表、零自有词表,判「什么算凭据」的仍然只有 {@link redactSecrets} 一只。
  * 本函数只定两件**写回**的事,而这两件事在三条既有纪律面前各只有一个正确答案:
  *
- * ① **认出凭据形才改写字节;没认出就回原串**(codex 对抗复审 r1 [medium],亲核实测后修)。
- *    `redactSecrets` 自 S-103 起**无条件先剥** `\p{Cf}`,所以 `redactSecrets(x) !== x` 对任何含 Cf 的文本都为真 ——
- *    实测:`👨‍👩‍👧`(ZWJ 家庭 emoji)被拆成三个独立 emoji、波斯语 `می‌خواهم`(ZWNJ)被粘成 `میخواهم`。
- *    诊断文本上这是成文代价(那一族本就要「先扫描后渲染」);**用户最终答复**上它是每一条含 ZWJ/ZWNJ 的
- *    正常答案被永久改坏,而本件对外的承诺逐字是「不含凭据形的文本逐字节不变」。判据用的是本模块**自己成文的
- *    那一条**(`redact.ts` 的 `normalizeForRedaction` 顶注:「正确的谓词是 `redactSecrets(x) !== normalizeForRedaction(x)`」),
- *    既有消费方 `tool-approval.ts` 的规则车道闸用的也是它 —— 一条谓词两处用,不是新规矩。
- *    ⚠️ **命中那一次仍然给剥后文本**(S-103 的「先扫描后渲染」不动摇):把零宽字符塞进密钥中间的那条文本,
- *    渲染的必须是剥后那份,否则消费端把残片拼回原钥。
+ * ① **认出凭据形才改写字节;没认出就回原串** —— 这就是 `redactSecrets` 自己的语义,本函数不另立读法(S-1435 起):
+ *    臂只在剥 `\p{Cf}` 后的视图上认凭据,产物按**原文**坐标拼 ⇒ 没有跨度的文本逐字节原样(`👨‍👩‍👧` 的 ZWJ、波斯语
+ *    `می‌خواهم` 的 ZWNJ 都在),有跨度时只有跨度内的字节被盖 —— 夹在密钥中间的零宽字符随整段密钥一起换成记号,
+ *    消费端拿不到可拼回原钥的残片。此前 `redactSecrets` 的产物是剥后文本,本函数为此另比一次「输出 === 剥后原文 ⇒
+ *    回原字节」(同一问两处答),已随产物回原文退役。
  * ② **扫描器抛 ⇒ 登记过的占位(fail-closed),不把整条 run 拖下水**(codex r1 [high],亲核实测后修)。
  *    立案时 `redactSecrets` 的 JSON 秘密字段臂含多字符循环体(`(?:\\.[^"\\]*)*`),实测
  *    `{"password":"<400 万个 \\n 转义对>"}`(8MB)抛 `RangeError`。`result` 接进来之前这条路不存在;接进来之后,

package/dist/observability/run-terminal.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { redactSecrets, normalizeForRedaction } from "../trace/redact.js";
+import { redactSecrets } from "../trace/redact.js";
 import { isProviderEchoShape } from "@sema-agent/core";
 import { isModelTextLedgerEventType, isParkLedgerEventType } from "../trace/ledger-events.js";
 import { isUnsuccessfulRunStatus } from "../plugins/store-contracts.js";
@@ -86,12 +86,7 @@ export function redactErrorMessage(raw) {
 }
 export function redactModelText(raw) {
     try {
-        const out = redactSecrets(raw);
-        if (out === raw)
-            return raw;
-        if (out === normalizeForRedaction(raw))
-            return raw;
-        return out;
+        return redactSecrets(raw);
     }
     catch (err) {
         recordFailOpen("server.run-terminal.redact-threw", `model-text len=${raw.length} err=${errorText(err)}`);

package/dist/plugins/approval-ask-store-sql.js

@@ -144,7 +144,7 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     -- rule_command 与 permission_rule_approval.command 同款 LONGTEXT:命令行没有入口上限,VARCHAR
     -- 会造一个静默截断面,而截断过的命令与原命令是两条不同的命令(覆盖门会据一条我们自己改过的命令判)。
     rule_command LONGTEXT NULL,
-    -- rule_scope_root:root 的真上界 = task-cwd.ts 的 MAX_CWD_CHARS(4096,入口 isValidCwd 硬拒更长者),
+    -- rule_scope_root:root 的真上界 = 主机路径形判的 ABSOLUTE_HOST_PATH_MAX(4096,入口 isAbsoluteHostPath 硬拒更长者),
     -- 宽度与那把尺同源 —— 与 MAX_RULE_SCOPE_CHARS 的取值法(由铸侧的尺派生)逐字同精神。
     rule_scope_root VARCHAR(4096) NULL,
     schema_version INT NOT NULL,

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

@@ -1,5 +1,5 @@
 import type { AcquiredSession, PlacedSessionRow, RetentionDeclaration, SessionPlacementRecord, SessionStore, SessionTreeEntry } from "@sema-agent/core";
-import type { SessionListItem } from "../security.js";
+import type { OwnerAwareSessionStore, SessionListItem } from "../security.js";
 import type { StagingHandle } from "../session-sync-kernel.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import type { InstructionSourceStore } from "../instruction-source-notice.js";
@@ -57,7 +57,12 @@ export declare class CachingSessionStore implements SessionStore {
     }) => Promise<SessionListItem[]>;
     readonly fork?: (sourceId: string, owner: string | null) => Promise<string | null>;
     readonly deleteSession?: (sessionId: string, owner: string | null) => Promise<boolean>;
-    /** Write-once auto-title (SQL twins + local sidecar carry it; pure pass-through). */
+    /** The session row's list projection for one id + its writable bits (`title` / `pinned`) — DURABLE, pure pass-through
+     *  (they read / write `session_meta` / the local sidecars, never the warm cache). 🔴 Must forward (the retention / placements
+     *  lesson): the production default wraps the real store in this class, and the route's fact `sessionPatch` reads THIS object. */
+    readonly sessionSummaryOf?: (sessionId: string) => Promise<SessionListItem | undefined>;
+    readonly patchSessionMeta?: OwnerAwareSessionStore["patchSessionMeta"];
+    /** The auto-titler's NULL-only title write (SQL twins + local sidecar carry it; pure pass-through). */
     readonly setTitleIfNull?: (sessionId: string, title: string) => Promise<boolean>;
     readonly probeTitle?: (sessionId: string) => Promise<"none" | "untitled" | "titled">;
     /** S-690 —— 换源通告的基线面(`session_meta.instruction_source` / local sidecar),纯转发、不经暖缓存。

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

@@ -11,6 +11,8 @@ export class CachingSessionStore {
     listSessions;
     fork;
     deleteSession;
+    sessionSummaryOf;
+    patchSessionMeta;
     setTitleIfNull;
     probeTitle;
     readInstructionSource;
@@ -51,6 +53,10 @@ export class CachingSessionStore {
             this.register = ownerAware.register.bind(inner);
         if (ownerAware.listSessions)
             this.listSessions = ownerAware.listSessions.bind(inner);
+        if (ownerAware.sessionSummaryOf)
+            this.sessionSummaryOf = ownerAware.sessionSummaryOf.bind(inner);
+        if (ownerAware.patchSessionMeta)
+            this.patchSessionMeta = ownerAware.patchSessionMeta.bind(inner);
         if (ownerAware.setTitleIfNull)
             this.setTitleIfNull = ownerAware.setTitleIfNull.bind(inner);
         if (ownerAware.probeTitle)

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

@@ -22,7 +22,7 @@ export const TIDB_DEVICE_STATEMENTS = [
     -- Ed25519 公钥 b64(44 字符);VARBINARY 因为它参与 UNIQUE 与身份比对。
     pubkey           VARBINARY(128) NOT NULL,
     pubkey_rotated_at DATETIME(3)   NULL,
-    -- 设备工作区根:上界取 task-cwd.ts 的 MAX_CWD_CHARS 家族(4096 过宽、1024 是路径的实用上界)。
+    -- 设备工作区根:上界取主机路径形判 ABSOLUTE_HOST_PATH_MAX 家族(4096 过宽、1024 是路径的实用上界)。
     workspace_root   VARCHAR(1024)  NOT NULL,
     workspace_root_rev BIGINT       NOT NULL DEFAULT 0,
     status           VARCHAR(16)    NOT NULL DEFAULT 'active',

package/dist/plugins/ensure-index.js

@@ -1,4 +1,5 @@
 import { recordFailOpen } from "../observability/fail-open.js";
+import { readLiveColumns } from "./schema-live-columns.js";
 function rowsOf(res) {
     if (Array.isArray(res)) {
         const first = res[0];
@@ -30,6 +31,27 @@ const refusal = (spec, unique, what) => `ensureIndex: PostgreSQL 索引 ${spec.n
     `CREATE ${unique}INDEX CONCURRENTLY ${quoteId("pg", spec.name)} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)});` +
     " 常见根因 = 池级 statement_timeout(DB_QUERY_TIMEOUT_MS)把构建切断(见 cause),或 UNIQUE 索引撞上存量重复行。";
 export async function ensureIndex(q, dialect, spec) {
+    try {
+        await applyIndex(q, dialect, spec);
+    }
+    catch (err) {
+        let live;
+        try {
+            live = await readLiveColumns(async (sql) => rowsOf(await q(sql)), dialect);
+        }
+        catch {
+            throw err;
+        }
+        if (indexColumnMissing(live, spec))
+            return;
+        throw err;
+    }
+}
+function indexColumnMissing(live, spec) {
+    const columns = live.get(spec.table);
+    return columns !== undefined && spec.columns.some((c) => !columns.has(c));
+}
+async function applyIndex(q, dialect, spec) {
     switch (dialect) {
         case "mysql": {
             const present = rowsOf(await q("SELECT 1 AS present FROM information_schema.statistics WHERE table_schema = DATABASE() " +

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

@@ -1,6 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
-import { StoreBootRefusalError, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { StoreBootRefusalError, type CreateRunOutcome, type NewRunMeta, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 /**
@@ -29,6 +29,8 @@ export declare class FileRunStore {
     private readonly runs;
     /** sessionId → taskId — the single-active-run claim (the task_active table; index of active/*). */
     private readonly active;
+    /** idemKey → taskId — the file twin of `uq_task_run_idem` (rebuilt from run.json at hydrate; one writer per data root). */
+    private readonly byIdem;
     /** taskId → events (kept seq-sorted on read), the event-log index. */
     private readonly events;
     /** taskId → the open append log (one O_APPEND fd per run, lazily opened, held for lifetime). */
@@ -91,19 +93,20 @@ export declare class FileRunStore {
     /** Commit a RunRow to disk (whole-file atomic replace) AND the index — the single write path for every status change. */
     private persist;
     private eventLogFor;
-    /** Create a run iff the session has no active run (the task_active unique-key claim). The claim file is created with
-     *  writeThenLink (atomic): if it already exists (EEXIST) the session has an active run → lose, return the holder. */
-    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;
-    }>;
-    /** [ref] —— createRun 临界区的后半段:落 claim 索引 + run 行(两者一体,行写失败即回滚 claim)。 */
+    /** Create a run iff the session has no active run (the task_active unique-key claim) AND no submission key of this
+     *  request already names a row (submission idempotency: `idemKey` or a caller-minted `taskId`) — the file twin of the
+     *  SQL store's **atomic win or observe** ({@link CreateRunOutcome}). The claim file is created with writeThenLink
+     *  (atomic): if it already exists (EEXIST) the session has an active run → lose, return the holder — unless a key of
+     *  this submission names a row, which is then OBSERVED (a same-key retry whose original still holds the session is a
+     *  replay, not a busy session). */
+    createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: NewRunMeta): Promise<CreateRunOutcome>;
+    /** The row a submission's keys name — `idemKey` first, then `taskId` (the two keys of one law; see {@link CreateRunOutcome}). */
+    private submittedRow;
+    /** Release a claim this create just took (index + claim file) — the rollback half of the critical section. */
+    private releaseFreshClaim;
+    /** [ref] —— createRun 临界区的后半段:落 claim 索引 + run 行(两者一体,行写失败即回滚 claim)。
+     *  Synchronous from the key check to the index write ⇒ two same-key creates in this process (different sessions,
+     *  different claim locks) cannot both pass the check: the loser observes the winner's row. */
     private commitNewRun;
     requestCancel(taskId: string, owner: string | null): Promise<boolean>;
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
@@ -128,6 +131,13 @@ export declare class FileRunStore {
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     getRun(taskId: 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>;
+    /** The run a submission's scoped `Idempotency-Key` names (the file twin of `uq_task_run_idem`), if any. */
+    getRunByIdem(idemKey: string): Promise<RunRecord | undefined>;
     /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
     listRuns(opts: {
         status?: string;

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

@@ -55,6 +55,7 @@ export class FileRunStore {
     tmpDir;
     runs = new Map();
     active = new Map();
+    byIdem = new Map();
     events = new Map();
     eventLogs = new Map();
     checkpointProbe;
@@ -97,7 +98,7 @@ export class FileRunStore {
         return join(this.activeDir, sanitizePathComponent(sessionId));
     }
     toRow(d) {
-        return { ...d, createdAt: new Date(d.createdAt), updatedAt: new Date(d.updatedAt) };
+        return { ...d, idemKey: typeof d.idemKey === "string" ? d.idemKey : null, createdAt: new Date(d.createdAt), updatedAt: new Date(d.updatedAt) };
     }
     toDisk(r) {
         return { ...r, createdAt: r.createdAt.toISOString(), updatedAt: r.updatedAt.toISOString() };
@@ -189,7 +190,10 @@ export class FileRunStore {
             const disk = singleRecordOf(this.replay(jsonPath, RUN_ROW_SHAPE));
             if (!disk)
                 continue;
-            this.runs.set(disk.taskId, this.toRow(disk));
+            const row = this.toRow(disk);
+            this.runs.set(disk.taskId, row);
+            if (row.idemKey !== null)
+                this.byIdem.set(row.idemKey, row.taskId);
             const eventsPath = join(dir, "events.jsonl");
             const recs = this.replay(eventsPath, EVENT_RECORD_SHAPE).records;
             if (recs.length) {
@@ -279,14 +283,34 @@ export class FileRunStore {
         return log;
     }
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
+        const idemKey = meta.idemKey ?? null;
         return this.withClaimLock(sessionId, async () => {
             const acquired = await this.acquireClaim(sessionId, taskId);
-            if (!acquired.ok)
-                return acquired;
-            return this.commitNewRun(taskId, sessionId, owner, instanceId, meta);
+            if (!acquired.ok) {
+                const existing = this.submittedRow(taskId, idemKey);
+                return existing ? { ok: false, existing: this.toRecord(existing) } : acquired;
+            }
+            return this.commitNewRun(taskId, sessionId, owner, instanceId, meta, idemKey);
         });
     }
-    commitNewRun(taskId, sessionId, owner, instanceId, meta) {
+    submittedRow(taskId, idemKey) {
+        const byKey = idemKey !== null ? this.byIdem.get(idemKey) : undefined;
+        return (byKey !== undefined ? this.runs.get(byKey) : undefined) ?? this.runs.get(taskId);
+    }
+    releaseFreshClaim(sessionId) {
+        this.active.delete(sessionId);
+        try {
+            rmSync(this.activePath(sessionId), { force: true });
+        }
+        catch {
+        }
+    }
+    commitNewRun(taskId, sessionId, owner, instanceId, meta, idemKey) {
+        const existing = this.submittedRow(taskId, idemKey);
+        if (existing) {
+            this.releaseFreshClaim(sessionId);
+            return { ok: false, existing: this.toRecord(existing) };
+        }
         this.active.set(sessionId, taskId);
         const now = new Date();
         try {
@@ -302,6 +326,7 @@ export class FileRunStore {
                 source: meta.source ?? null,
                 instanceId,
                 objectivePreview: meta.objectivePreview ?? null,
+                idemKey,
                 createdAt: now,
                 updatedAt: now,
                 cancelRequested: false,
@@ -309,14 +334,11 @@ export class FileRunStore {
             });
         }
         catch (e) {
-            this.active.delete(sessionId);
-            try {
-                rmSync(this.activePath(sessionId), { force: true });
-            }
-            catch {
-            }
+            this.releaseFreshClaim(sessionId);
             throw e;
         }
+        if (idemKey !== null)
+            this.byIdem.set(idemKey, taskId);
         return { ok: true };
     }
     async requestCancel(taskId, owner) {
@@ -453,6 +475,20 @@ export class FileRunStore {
         const r = this.runs.get(taskId);
         return r ? this.toRecord(r) : undefined;
     }
+    async releaseIdemKey(taskId) {
+        const r = this.runs.get(taskId);
+        if (!r || r.idemKey === null)
+            return;
+        const key = r.idemKey;
+        this.persist({ ...r, idemKey: null });
+        if (this.byIdem.get(key) === taskId)
+            this.byIdem.delete(key);
+    }
+    async getRunByIdem(idemKey) {
+        const taskId = this.byIdem.get(idemKey);
+        const r = taskId !== undefined ? this.runs.get(taskId) : undefined;
+        return r ? this.toRecord(r) : undefined;
+    }
     async listRuns(opts) {
         if (opts.cursor && Number.isNaN(Date.parse(opts.cursor.createdAt)))
             return [];
@@ -519,6 +555,7 @@ export class FileRunStore {
                 lastRunId: latest.taskId,
                 ...(typeof latestRunId === "string" && latestRunId !== "" ? { lastTaskRunId: latestRunId } : {}),
                 title: null,
+                pinned: false,
             });
         }
         return summaries
@@ -871,6 +908,9 @@ export class FileRunStore {
             this.eventLogs.delete(taskId);
         }
         this.events.delete(taskId);
+        const dropped = this.runs.get(taskId);
+        if (dropped?.idemKey != null && this.byIdem.get(dropped.idemKey) === taskId)
+            this.byIdem.delete(dropped.idemKey);
         this.runs.delete(taskId);
         const dir = this.runDir(taskId);
         if (existsSync(dir)) {

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

@@ -24,7 +24,7 @@ export interface LeaderRunRecord {
 export interface NewLeaderRun {
     objective: string;
     owner: string | null;
-    /** 已 scope 过的幂等键的 sha256 hex(见 {@link leaderIdemKey});null = 不去重。 */
+    /** 已 scope 过的幂等键(唯一铸法 `idemKeyOf(raw, caller, "leader")`,`http/idempotency.ts`;sha256 hex 定宽 64);null = 不去重。 */
     idemKey: string | null;
 }
 /** 终局补丁 —— `finishRun` 一次写完(状态 + 结果/错误 + 完成时刻)。 */
@@ -35,16 +35,6 @@ export interface LeaderRunTerminal {
 }
 /** `objective_preview` 的字符上限,与 DDL 的 VARCHAR(160) 同源(`task_run.objective_preview` 先例同宽)。 */
 export declare const LEADER_OBJECTIVE_PREVIEW_CHARS = 160;
-/**
- * 幂等键的**落库形** = `sha256(scope \x1f raw)` 的 hex(64 字符,定宽)。
- *
- * 为什么 hash 而不是像 bake 店那样存 scope 过的明文:明文形的列宽(VARCHAR(255))与「principal(≤190)
- * + 调用方自选的 raw 键(≤255)」的上界对不上 —— 溢出时 PG 报 `value too long`、非严格 MySQL **静默截断**,
- * 而截断一个去重键的后果是**两个不同的请求折叠成同一次 leader run**(= 一次该跑的 run 被静默吞掉)。
- * 定宽 hash 让这条路径按构造不存在;顺带,库里也不再留调用方的原始键字面量。
- * (碰撞面:sha256,不在工程风险量级。)
- */
-export declare function leaderIdemKey(raw: string, owner: string | null): string;
 /** MySQL 协议方言的建表语句(真源;由 `tidb-pool.ts` 展开进中央 SCHEMA_STATEMENTS)。 */
 export declare const TIDB_LEADER_RUN_STATEMENTS: readonly string[];
 /** PG 方言的建表语句(MySQL 孪生的逐条翻译:JSON→JSONB,逐列 `COLLATE "C"`,内联 KEY→独立 CREATE INDEX)。 */

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

@@ -1,5 +1,4 @@
 import { uuidv7 } from "@sema-agent/core";
-import { createHash } from "node:crypto";
 import { isDupKeyError } from "./sql-errors.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { decodeNullableJsonColumn, foldJsonColumn, jsonColumnText, readNonNullJsonValueColumn } from "./sql-json-column.js";
@@ -8,13 +7,10 @@ import { buildObjectivePreview } from "../user-authored-text.js";
 export const LEADER_RUN_TABLE = "leader_run";
 const LEADER_RUN_STATUSES = new Set(["running", "completed", "failed", "needs_human"]);
 export const LEADER_OBJECTIVE_PREVIEW_CHARS = 160;
-export function leaderIdemKey(raw, owner) {
-    return createHash("sha256").update(`${owner ?? ""}\x1f${raw}`).digest("hex");
-}
 export const TIDB_LEADER_RUN_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${LEADER_RUN_TABLE} (
      leader_run_id  VARCHAR(64)  NOT NULL,
-     -- idem_key:提交幂等的**唯一**执法点(sha256 hex,定宽 64;见 leaderIdemKey 的头注)。NULL = 调用方
+     -- idem_key:提交幂等的**唯一**执法点(sha256 hex,定宽 64;铸法 = http/idempotency.ts 的 idemKeyOf,族 leader)。NULL = 调用方
      -- 没带 Idempotency-Key ⇒ 不参与去重(MySQL/PG 的 UNIQUE 都不约束 NULL,两方言同形)。
      idem_key       VARCHAR(64)  NULL,
      -- owner:BL-4 提交者(null = 匿名/单租)。GET 的属主门读它 —— 非属主 404(不是 403),不给存在性预言机。

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

@@ -1,5 +1,6 @@
 import { FileSessionRepo, type AcquiredSession, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
 import type { SessionRunRollupSource, SessionSummary } from "./store-contracts.js";
+import type { SessionRowPatch } from "../session-row.js";
 import { type Logger } from "../observability/logger.js";
 import { type SessionFace } from "../session-incarnation.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
@@ -49,10 +50,14 @@ export declare class LocalSessionStore implements SessionStore {
     private lastWarnAt;
     /** Absolute path to the lastActivity JSON sidecar, or undefined when not persisting (in-memory-only deployment). */
     private readonly sidecarPath?;
-    /** Auto-title map (`session-titles.json`). Separate file from the lastActivity sidecar ON PURPOSE (that format is a
-     *  #10 clobber area); titles are write-once + ultra-low-rate (one per session, ever). Cross-instance sharing: see
-     *  {@link SidecarMap}. */
+    /** Title map (`session-titles.json`) — the local twin of the SQL `session_meta.title` column: one cell, two writers
+     *  (the user's {@link patchSessionMeta}, unconditional; the auto-titler's {@link setTitleIfNull}, fills an absent cell
+     *  only — writer order: `src/session-row.ts`). Separate file from the lastActivity sidecar ON PURPOSE (that format is a
+     *  #10 clobber area); ultra-low-rate. Cross-instance sharing: see {@link SidecarMap}. */
     private readonly titles;
+    /** Pin map (`session-pinned.json`, {@link readPinnedSidecar}) — the local twin of `session_meta.pinned`. Its own file for
+     *  the same reason titles have theirs (one small map per concern, no format coupling); absent key = not pinned. */
+    private readonly pinned;
     /** S-690 — instruction-source baselines (`session-instruction-sources.json`): the chain member the session's previous
      *  run selected, encoded like the SQL twins' `session_meta.instruction_source` column ('' = none; missing key = never
      *  recorded). Its own file for the same reason titles have theirs: one small map per concern, no format coupling. */
@@ -103,10 +108,28 @@ export declare class LocalSessionStore implements SessionStore {
     /** Cheap pre-LLM probe (local twin). The map write needs no session_meta row, so there is
      *  no "none" (register-lag) dimension here — two states only. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
-    /** Write-once auto-title (the local twin of the SQL setTitleIfNull). Persists the whole
-     *  (small) map via a SERIALIZED tmp+rename snapshot; a write failure keeps the in-memory title (degrades to
-     *  re-title after restart). */
+    /** The auto-titler's write (the local twin of the SQL setTitleIfNull): lands only on an absent cell — a title already
+     *  there (the user's included) wins. Persists the whole (small) map via a SERIALIZED tmp+rename snapshot; a write
+     *  failure keeps the in-memory title (degrades to re-title after restart). */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /**
+     * 会话行的可写位 —— 用户标题 / 置顶的**唯一**写口(SQL 孪生 `patchSessionMeta` 的 local 对位;写者次序见 `src/session-row.ts`)。
+     * 只写列表面上的会话(会话仓里有它),且只写调用方验过的那一位住客(`face.incarnation` 与会话元数据那一格的化身相等 —— SQL 孪生的
+     * `AND incarnation = ?`):住客判在每只边档 `commit` 的写链节里、对着那一刻的元数据格判(判、写、落盘后才发布),读回同一判据
+     * ⇒ 回执是那一位住客的列表行,或 `undefined`(期间被删 / 被谁重新登记 —— 什么都没写)。
+     * `title` 串 ⇒ 无条件写进那一格(自动标题器的 {@link setTitleIfNull} 见格在就不写 ⇒ 用户那笔恒留下);`title: null` ⇒ 删那一格(清回自动标题);
+     * `pinned:true` 写 `true`、`false` 删键。
+     * 落不了盘 ⇒ 抛、内存不动(用户的一笔写,不做「内存里先记着」的降级)。⚠️ 两键同一体时是两只文件、两次落盘:第二只落不了时第一只已在盘上
+     * (SQL 孪生是一条 UPDATE);抛出的错点名哪一只,重发同一体收敛。`lastActivity` 不动(改名不是活动 —— 列表的新近序不变)。
+     */
+    patchSessionMeta(sessionId: string, patch: SessionRowPatch, face: SessionFace): Promise<SessionSummary | undefined>;
+    /** 会话元数据那一格此刻坐的是不是 `face` 那一位住客(同步读已发布的格;调用方先 `meta.ensureLoaded()`)。 */
+    private occupiedBy;
+    /** ONE session's list row — {@link listSessions}' projection ({@link summaryOf}, the same synthesis) for one id;
+     *  `undefined` = not a row of the list face (not in the session repo). */
+    sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
+    /** 会话仓里这只会话的列表元数据(列表面上的行 = `repo.list()` 里的一项)。 */
+    private listedMeta;
     /** S-690 —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_meta.instruction_source` 同一只编解码)。 */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**
@@ -224,6 +247,12 @@ export declare class LocalSessionStore implements SessionStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** 列表行要读的边档一次装齐(lastActivity / 标题 / 置顶 / 会话元数据);各自记忆化,只有第一次真读盘。 */
+    private loadRowSidecars;
+    /** 列表行上的属主:那一格的属主(没有格 / 属主从没被记下 ⇒ null —— 与 `ownerOf` 同答;列表不补铸缺的格,`ownerOf` / `sessionFaceOf` 在第一次读时补)。 */
+    private ownerCellOf;
+    /** 一只会话的列表行 —— {@link listSessions} 与 {@link sessionSummaryOf} 的**同一只**合成(字段来源逐位见 listSessions 的头注)。调用方先 {@link loadRowSidecars}。 */
+    private summaryOf;
     /** S-1371:run 店里每个会话的 run 投影(按 sessionId 索引)。
      *  **一次读**:run 店的 `listSessions` 本来就按会话聚合全账(无会话过滤口),这里取全量再按会话仓的 id 查表 —— 比逐会话 N 次读便宜,
      *  也不在会话店里另存一份 run 账。读失败 ⇒ 抛(不吞成 `0 / ""`:那会把「读不到」说成「没跑过」)。 */