@sema-agent/server 7.117.0 → 7.119.0

package/dist/plugins/one-time-migrations.js

@@ -1,5 +1,7 @@
-import { acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
-import { acquirePgEnsureSchemaLock, releasePgEnsureSchemaLock } from "./pg-pool.js";
+import { SCHEMA_STATEMENTS, acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
+import { PG_SCHEMA_STATEMENTS, acquirePgEnsureSchemaLock, releasePgEnsureSchemaLock } from "./pg-pool.js";
+import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
+import { ensureIndexes } from "./ensure-index.js";
 import { decodeJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, readNonNullJsonValueColumn } from "./sql-json-column.js";
 import { SESSION_META_INCARNATION_COLUMN, mintSessionIncarnation } from "../session-incarnation.js";
 import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR } from "./store-contracts.js";
@@ -99,7 +101,42 @@ export const ONE_TIME_MIGRATIONS = [
             "「认不得的键按内容脱敏」一条脱敏后原样显示,卡上 `message` 里引擎写好的那句话不受影响",
         reportKeys: ["allowRuleShadowRowsMigrated", "allowRuleShadowRowsUnreadable"],
     },
+    {
+        id: "M9",
+        introducedIn: "7.118.0",
+        releasedOn: "2026-10-07",
+        removableAfter: "2026-11-06",
+        removal: "删 migrateOn 的 M9 步(`reshapeWorkflowParkIndex` / `execAtomically` / `finishParkIndexShape`:收尾段、主键宽度探针、暂存表复制、换名、删旧表、索引补建、主键约束名)与 " +
+            "`primaryKeyWidth` / `WORKFLOW_PARK_INDEX_TABLE` / `WORKFLOW_PARK_INDEX_STAGING` / `WORKFLOW_PARK_INDEX_RETIRED`;报告、日志行与 `NO_SQL_MIGRATIONS` 的 " +
+            "`workflowParkIndexKey` / `workflowParkIndexRowsCarried`;**连同读侧半场一起删**(都是「引擎 7.43 及以前写下的 workflow 子代停驻记录」这同一件事,同窗同删,不另起登记行):" +
+            "`orchestration/workflow-agent-session-index.ts` 的 `older_engine` 读臂(`routeWorkflowPark` 规则 ③、`WorkflowParkRoute` 与 `parked-decide.ts` `ParkOrigin` 上 `cause` 里的这一词," +
+            "`denyWorkflowParksUnreadable` 的对应分支;`unreadable` 成为唯一成因)与随包排空判据 `workflow-park-holder`(`scripts/drain-check.mysql.sql` / `scripts/drain-check.pg.sql` 的那一段" +
+            "与文件头判据清单里的那一行、`scripts/drain-check-local.mjs` 的 `DRAIN_CRITERIA` 那一条与 `readParkIndex`,以及 `MIGRATION.md` / `docs/DEPLOY-PREREQS.md` 里点名它的说明)",
+        afterRemoval: "没有响亮臂:删码之后仍是旧主键(只有 `session_id`)的库(跳过了带本条的版本直接升)上,同一个子会话只能有一枚指针 —— 续跑链 / 分叉里" +
+            "后写的那条记录覆盖先写的,判决只看得到一条记录:分叉判不出、链尾可能被更早的记录盖掉(决定投给那一条)。运维手工照中央 DDL 重建这张表即可" +
+            "(它是派生投影,丢了只丢升级那一刻还停驻着的旧卡的指针 —— 那些卡改答诚实 miss)。读侧半场删后:升级那一刻还停驻着、点名它的条目没有持有者位的存量卡" +
+            "(跳过了带本条的版本直接升的库)路由判 `none` ⇒ 落 legacy 腿,答 `409 conflict.resume_context_unavailable`(响亮,但成因是子会话没有续跑上下文,不再是 " +
+            "`decide.workflow_parks_unreadable`);出路不变(续跑发起它的那条 workflow run);随包排空判据没了,换钉前没有机器读数可数这些卡",
+        reportKeys: ["workflowParkIndexKey", "workflowParkIndexRowsCarried"],
+    },
+    {
+        id: "M10",
+        introducedIn: "7.119.0",
+        releasedOn: "2026-10-08",
+        removableAfter: "2026-11-07",
+        removal: "删 local 车道的认领臂:`LocalSessionStore.register` 里「属主从没被记下的存量会话 ⇒ 带 principal 的登记认领它」那一支、认领日志行 `session_owner_claimed`" +
+            "(连同店构造参数里只为它存在的 `log` 位)与读本表 M10 行的 `ownerClaimWindowOpen`;`security.ts` `createAuthorizer` 里对无主会话的那次认领 `register` 调用;" +
+            "`http/routes/sessions.ts` 409 `conflict.session_ownerless` 句里「Ways out: on the local backend, during the upgrade window …」那半句(连同冻结表 " +
+            "`test/api-error-text-freeze.test.ts` 那一行、契约码目录 `docs/ASSISTANT-WIRE-CONTRACT.md` 那一行);本文件的 `migrationWindowOpen`(若再无别的读者)",
+        afterRemoval: "没有响亮臂(删码本身零行为变化:窗关那一刻起认领臂已经不生效):属主从没被记下的存量会话(边档那一格只有化身 —— 跳过了带本条的版本直接升," +
+            "或窗内从没被带 principal 提交过)照旧答无主(`ownerOf` = null):它的会话规则这条路由读不了也改不了(409 `conflict.session_ownerless`)," +
+            "已存的规则对写下它们的 principal 的 run 照旧生效;出路 = 删会话(`DELETE /v1/sessions/:id`,规则随之删)",
+        reportKeys: [],
+    },
 ];
+export function migrationWindowOpen(window, today) {
+    return window.removableAfter === null || today <= window.removableAfter;
+}
 export const NO_SQL_MIGRATIONS = {
     retiredSnapshotTable: "absent",
     retiredSnapshotRows: 0,
@@ -110,6 +147,8 @@ export const NO_SQL_MIGRATIONS = {
     sessionIncarnationsBackfilled: 0,
     allowRuleShadowRowsMigrated: 0,
     allowRuleShadowRowsUnreadable: 0,
+    workflowParkIndexKey: "file-ledger",
+    workflowParkIndexRowsCarried: 0,
 };
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT_COLUMN = "pending_steer";
@@ -250,6 +289,7 @@ async function migrateOn(db, dialect) {
             ? "UPDATE task_run SET error_code = ? WHERE status = 'failed' AND error_code IS NULL AND (error = ? OR error LIKE ?)"
             : "UPDATE task_run SET error_code = $1 WHERE status = 'failed' AND error_code IS NULL AND (error = $2 OR error LIKE $3)", [RUN_HOLDER_DEATH_CODES.orphaned, RUN_ORPHANED_ERROR, `${RUN_ORPHANED_ERROR} (%`]));
     const { migrated: allowRuleShadowRowsMigrated, unreadable: allowRuleShadowRowsUnreadable } = await migrateShadowedRuleKey(db, dialect);
+    const { key: workflowParkIndexKey, carried: workflowParkIndexRowsCarried } = await reshapeWorkflowParkIndex(db, dialect);
     let retiredSnapshotTable = "absent";
     let retiredSnapshotRows = 0;
     let retiredSteerSeatColumn = "absent";
@@ -283,8 +323,87 @@ async function migrateOn(db, dialect) {
     return {
         retiredSnapshotTable, retiredSnapshotRows, retiredSteerSeatColumn, retiredSteerSeatStaleRows, askOriginRowsMigrated, auditDetailJsonNullRows,
         sessionIncarnationColumn, sessionIncarnationsBackfilled, holderDeathCodeRowsBackfilled, allowRuleShadowRowsMigrated, allowRuleShadowRowsUnreadable,
+        workflowParkIndexKey, workflowParkIndexRowsCarried,
     };
 }
+const WORKFLOW_PARK_INDEX_TABLE = "workflow_agent_session";
+async function primaryKeyWidth(db, dialect, table) {
+    const sql = dialect === "tidb"
+        ? `SELECT COUNT(*) AS n FROM information_schema.key_column_usage WHERE table_schema = DATABASE() AND table_name = '${table}' AND constraint_name = 'PRIMARY'`
+        : `SELECT COUNT(*) AS n FROM information_schema.table_constraints tc JOIN information_schema.key_column_usage kcu ` +
+            `ON kcu.constraint_name = tc.constraint_name AND kcu.table_schema = tc.table_schema AND kcu.table_name = tc.table_name ` +
+            `WHERE tc.table_schema = current_schema() AND tc.table_name = '${table}' AND tc.constraint_type = 'PRIMARY KEY'`;
+    return Number((await db.rows(sql))[0]?.n ?? 0);
+}
+const WORKFLOW_PARK_INDEX_STAGING = `${WORKFLOW_PARK_INDEX_TABLE}_m9`;
+const WORKFLOW_PARK_INDEX_RETIRED = `${WORKFLOW_PARK_INDEX_TABLE}_m9_old`;
+async function reshapeWorkflowParkIndex(db, dialect) {
+    const T = WORKFLOW_PARK_INDEX_TABLE;
+    const S = WORKFLOW_PARK_INDEX_STAGING;
+    const O = WORKFLOW_PARK_INDEX_RETIRED;
+    const exists = (t) => tableExists(db, dialect, t);
+    const ddl = (dialect === "tidb" ? SCHEMA_STATEMENTS : PG_SCHEMA_STATEMENTS).find((stmt) => stmt.includes(`CREATE TABLE IF NOT EXISTS ${T} (`));
+    if (ddl === undefined)
+        throw new Error(`one-time migration M9: the central schema carries no definition of ${T} — refusing to reshape a table it cannot rebuild`);
+    const copyPointers = (to, from) => db.exec(dialect === "tidb"
+        ? `INSERT IGNORE INTO ${to} (session_id, run_id, agent_key, scope) SELECT session_id, run_id, agent_key, scope FROM ${from}`
+        : `INSERT INTO ${to} (session_id, run_id, agent_key, scope) SELECT session_id, run_id, agent_key, scope FROM ${from} ON CONFLICT DO NOTHING`);
+    let carried = 0;
+    const resumed = await exists(S);
+    if (resumed) {
+        await db.exec(ddl);
+        carried += await copyPointers(T, S);
+        await execUntil(db, `DROP TABLE ${S}`, async () => !(await exists(S)));
+    }
+    if (await exists(O))
+        await execUntil(db, `DROP TABLE ${O}`, async () => !(await exists(O)));
+    if ((await primaryKeyWidth(db, dialect, T)) !== 1) {
+        if (await exists(T))
+            await finishParkIndexShape(db, dialect);
+        return resumed ? { key: "reshaped", carried } : { key: "current", carried: 0 };
+    }
+    await db.exec(ddl.replace(`CREATE TABLE IF NOT EXISTS ${T} (`, `CREATE TABLE IF NOT EXISTS ${S} (`));
+    carried += await copyPointers(S, T);
+    const swapped = async () => !(await exists(S)) && (await exists(T)) && (await primaryKeyWidth(db, dialect, T)) !== 1;
+    if (dialect === "tidb") {
+        await execUntil(db, `RENAME TABLE ${T} TO ${O}, ${S} TO ${T}`, swapped);
+        await execUntil(db, `DROP TABLE IF EXISTS ${O}`, async () => !(await exists(O)));
+    }
+    else {
+        await execAtomically(db, [`ALTER TABLE ${T} RENAME TO ${O}`, `ALTER TABLE ${S} RENAME TO ${T}`, `DROP TABLE ${O}`], async () => (await swapped()) && !(await exists(O)));
+    }
+    await finishParkIndexShape(db, dialect);
+    return { key: "reshaped", carried };
+}
+async function execAtomically(db, statements, postcondition) {
+    try {
+        await db.exec("BEGIN");
+        for (const sql of statements)
+            await db.exec(sql);
+        await db.exec("COMMIT");
+    }
+    catch (e) {
+        try {
+            await db.exec("ROLLBACK");
+        }
+        catch (rollbackError) {
+            throw new Error(`one-time migration: a transactional DDL step failed (${e instanceof Error ? e.message : String(e)}) and could not be rolled back on this connection ` +
+                `(${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}) — the database rolls the transaction back when the connection closes; the next start resumes`, { cause: e });
+        }
+        if (!(await postcondition()))
+            throw e;
+    }
+}
+async function finishParkIndexShape(db, dialect) {
+    await ensureIndexes(async (sql, params) => (dialect === "tidb" ? [await db.rows(sql, params)] : { rows: await db.rows(sql, params) }), dialect === "tidb" ? "mysql" : "pg", CENTRAL_SCHEMA_INDEXES.filter((spec) => spec.table === WORKFLOW_PARK_INDEX_TABLE));
+    if (dialect !== "pg")
+        return;
+    const conventional = `${WORKFLOW_PARK_INDEX_TABLE}_pkey`;
+    const pk = await db.rows(`SELECT constraint_name FROM information_schema.table_constraints WHERE table_schema = current_schema() AND table_name = '${WORKFLOW_PARK_INDEX_TABLE}' AND constraint_type = 'PRIMARY KEY'`);
+    const name = pk[0]?.constraint_name;
+    if (typeof name === "string" && name !== conventional)
+        await db.exec(`ALTER TABLE ${WORKFLOW_PARK_INDEX_TABLE} RENAME CONSTRAINT ${name} TO ${conventional}`);
+}
 const RETIRED_SHADOWED_RULE_KEY = "shadowedRule";
 export function migrateShadowedRuleDescriptor(text) {
     let parsed;
@@ -405,7 +524,8 @@ export function migrateRetiredAskOrigin(type, data) {
 }
 export function logOneTimeMigrations(log, backend, report) {
     const changed = report.retiredSnapshotTable === "dropped" || report.retiredSteerSeatColumn === "dropped" || report.askOriginRowsMigrated > 0 || report.auditDetailJsonNullRows > 0 ||
-        report.sessionIncarnationColumn === "added" || report.sessionIncarnationsBackfilled > 0 || report.holderDeathCodeRowsBackfilled > 0 || report.allowRuleShadowRowsMigrated > 0 || report.allowRuleShadowRowsUnreadable > 0;
+        report.sessionIncarnationColumn === "added" || report.sessionIncarnationsBackfilled > 0 || report.holderDeathCodeRowsBackfilled > 0 || report.allowRuleShadowRowsMigrated > 0 || report.allowRuleShadowRowsUnreadable > 0 ||
+        report.workflowParkIndexKey === "reshaped";
     (changed ? log.warn : log.info).call(log, "one_time_migrations_applied", {
         backend,
         retiredSnapshotTable: report.retiredSnapshotTable,
@@ -419,6 +539,8 @@ export function logOneTimeMigrations(log, backend, report) {
         holderDeathCodeRowsBackfilled: report.holderDeathCodeRowsBackfilled,
         allowRuleShadowRowsMigrated: report.allowRuleShadowRowsMigrated,
         allowRuleShadowRowsUnreadable: report.allowRuleShadowRowsUnreadable,
+        workflowParkIndexKey: report.workflowParkIndexKey,
+        workflowParkIndexRowsCarried: report.workflowParkIndexRowsCarried,
         removableAfter: Object.fromEntries(ONE_TIME_MIGRATIONS.map((w) => [w.id, w.removableAfter])),
         note: "one-time persisted-data migrations (M1: retired whole-tree snapshot index table dropped; M2: retired single-seat " +
             "steering column dropped; M3: retired ask-origin spelling rewritten in place; M4: audit details written as the JSON " +
@@ -427,7 +549,9 @@ export function logOneTimeMigrations(log, backend, report) {
             "holder-death verdict written by an earlier version with only the sentence got the machine-readable code run.stalled / " +
             "run.orphaned; M7 writes nothing — it is the window of the refusal that keeps a suspended task whose stored allow list was written " +
             "under an earlier reading from resuming under the current one; M8: parked rows' allow-layer disclosure written by an earlier engine " +
-            "under its old key shadowedRule rewritten to allowRuleShadowed). Each step " +
+            "under its old key shadowedRule rewritten to allowRuleShadowed; M9: the workflow park pointer index rebuilt with the key (session, run), " +
+            "its rows carried over; M10 writes nothing at boot — on the local backend, while its window is open, the first task submitted with a principal " +
+            "on a session written by an earlier version (which recorded no owner) claims that session for the principal, one session_owner_claimed line per claim). Each step " +
             "runs on every boot until its window closes (the release that introduced it + 30 days; the per-step date is in " +
             "removableAfter, null while that release is not published yet) and is deleted in the first minor after that — start a " +
             "version that still carries a step at least once before upgrading past its deletion.",

package/dist/plugins/pg-pool.js

@@ -282,7 +282,7 @@ export const PG_SCHEMA_STATEMENTS = [
      run_id     VARCHAR(191) COLLATE "C" NOT NULL,
      agent_key  VARCHAR(191) COLLATE "C" NOT NULL,
      scope      VARCHAR(190) COLLATE "C" NOT NULL,
-     PRIMARY KEY (session_id)
+     PRIMARY KEY (session_id, run_id)
    )`,
     `CREATE TABLE IF NOT EXISTS workflow_completion_inbox (
      seq            BIGSERIAL,

package/dist/plugins/snapshot-bucket-presence.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 对象存储配了快照桶却**不存在** = 部署错 —— boot 期核**一次**,缺 ⇒ 响亮拒启(不是每一拍 sweep 一条静默的 404)。
+ *
+ * ## 病
+ * `SESSION_SNAPSHOT_BUCKET`(缺省 `session-snapshots`)是 snapshot-BLOB offload 与 SendUserFile 私有 presigned 轨 / 沙箱 staging 的桶。server 不建桶
+ * (`docs/DEPLOY-PREREQS.md`「对象存储桶」),sema-up 的建桶清单又漏过它 ⇒ 起服绿,之后每一次对象写、每一拍孤儿 sweep 的列举(每分钟)都是
+ * 404 NoSuchBucket —— 运维读到的是一串「失败的请求」,不是「桶没建」。
+ *
+ * ## 形(一条规则,不加特例)
+ *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
+ *    NoSuchBucket 的 404)⇒ **不拒**、照常起服,走登记过的 F 类兜底口 `recordFailOpen("server.snapshot-bucket.presence-unproven")`(计数 + 探针行 + 记录器的一次性 warn;
+ *    三问写在该 tag 的 note 里)—— 拒启要有证据,没有证据只留痕;
+ *  · 缺 = 配置好的店资源还没就绪,与「库连不上」同一类处境:在 `STORE_LOCK_WAIT_MS` 窗内重试({@link openWithinWait},同一只窗、同一只节拍、同一条窗尾规则 —— 编排里
+ *    建桶晚于 server 起是常态),到窗时手上有缺桶的证据 ⇒ 拒启,拒句点名桶名、`MINIO_ENDPOINT` 的显示安全形(`buildDisplaySafeUrl` 的产物:userinfo 落地、
+ *    query 值成记号,不带密钥)与出路;探针从头到尾没答过(每一次都挂到窗尾)⇒ 同样是「证明不了」,走上面那只兜底口、照常起服。
+ *  · 只核**快照桶**(`config.snapshotBlobStore.bucket`;SendUserFile 的私桶缺省同一只);公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ */
+import type { ServiceConfig } from "../config-types.js";
+import { type StoreOpenWaitClock } from "./store-open-wait.js";
+type SnapshotBlobStoreConfig = NonNullable<ServiceConfig["snapshotBlobStore"]>;
+/** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。 */
+export declare const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10000;
+/** 缺桶的拒启句(唯一铸点)。 */
+/** @param endpoint `MINIO_ENDPOINT` 的**显示安全形**(调用方过 {@link buildDisplaySafeUrl};本函数不碰原串)。 */
+export declare function buildSnapshotBucketRefusal(bucket: string, endpoint: string, waitedMs: number): string;
+/** 探针到窗尾一次都没答过时,兜底口 detail 里的成因(证明不了缺桶的一形)。 */
+export declare const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
+/**
+ * boot 期核一次快照桶(`boot/stores.ts`)。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
+ * @param waitMs `config.storeLockWaitMs`。`0` ⇒ 只核一次(缺就当场拒)。
+ */
+export declare function ensureSnapshotBucket(store: SnapshotBlobStoreConfig, waitMs: number, logger: {
+    warn(msg: string, meta?: Record<string, unknown>): void;
+}, clock?: StoreOpenWaitClock): Promise<void>;
+export {};
+//# sourceMappingURL=snapshot-bucket-presence.d.ts.map

package/dist/plugins/snapshot-bucket-presence.js

@@ -0,0 +1,40 @@
+import { buildDisplaySafeUrl } from "../trace/redact.js";
+import { MinioBlobBackend } from "./blob-backend.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { isStoreOpenWindowExpired, openWithinWait } from "./store-open-wait.js";
+export const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10_000;
+class SnapshotBucketMissing extends Error {
+    constructor() {
+        super("snapshot bucket missing");
+    }
+}
+export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs) {
+    const waited = waitedMs > 0 ? `after retrying for ${waitedMs}ms (STORE_LOCK_WAIT_MS)` : "on the first check (STORE_LOCK_WAIT_MS=0: no wait)";
+    return (`Object storage is configured (MINIO_ENDPOINT → ${endpoint}) but the snapshot bucket "${bucket}" (SESSION_SNAPSHOT_BUCKET; default session-snapshots) does not exist there ${waited} — refusing to boot: ` +
+        `the server never creates buckets, so every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever). ` +
+        `Next: create the bucket (mc mb <alias>/${bucket}; this version's sema-up scripts create it — re-run them on an existing sema-up deployment), or set SESSION_SNAPSHOT_BUCKET to a bucket that exists.`);
+}
+export const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
+export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
+    const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), ...(store.keyPrefix ? { keyPrefix: store.keyPrefix } : {}) });
+    let verdict;
+    try {
+        verdict = await openWithinWait(async () => {
+            const r = await probe.probeBucket(SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS);
+            if (r.state === "missing")
+                throw new SnapshotBucketMissing();
+            return r;
+        }, waitMs, (w) => logger.warn("snapshot_bucket_wait", { bucket: store.bucket, endpoint: buildDisplaySafeUrl(store.endpoint), waitMs: w.waitMs, error: w.error }), clock);
+    }
+    catch (err) {
+        if (err instanceof SnapshotBucketMissing)
+            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs), { cause: err });
+        if (!isStoreOpenWindowExpired(err))
+            throw err;
+        verdict = { state: "unknown", detail: SNAPSHOT_BUCKET_PROBE_PENDING };
+    }
+    if (verdict.state === "unknown") {
+        recordFailOpen("server.snapshot-bucket.presence-unproven", `bucket=${store.bucket} endpoint=${buildDisplaySafeUrl(store.endpoint)} ${verdict.detail}`);
+    }
+}
+//# sourceMappingURL=snapshot-bucket-presence.js.map

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

@@ -398,8 +398,11 @@ export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootL
  *  而 LocalBackend 的 `ensureSchema` 是**空实现**,真正会抛的 mkdir + 数据根 BootLock 在构造函数里、
  *  落在 try 之外。于是那条降级臂对 local 形从来没生效过,注释宣称的行为与代码真做的事撕裂。
  *
- *  降级条件不变(两形同一姿势):`sessionBackend=auto`(配置的 DB 不可达,S5 原形)或**默认推导**的
- *  local(`dbBackend=local && !dbBackendExplicit`)。**显式** DB_BACKEND=local / tidb 仍 fail-loud——
+ *  **降级臂只有一条:缺省推导的 local**(`dbBackend=local && !dbBackendExplicit`)。🔴 **SQL 族没有降级臂** —— 配了 DSN 就是要这只库:
+ *  `SESSION_BACKEND=auto` 与显式 `DB_BACKEND=mysql|pg` 同一待遇,库当下打不开 ⇒ 在 `STORE_LOCK_WAIT_MS` 的窗内重试
+ *  ({@link openWithinWait}),到窗仍打不开 ⇒ 拒启(拒句 {@link buildSqlStoreOpenRefusal} 点名后端与库的显示安全形)。修前 `auto` 在这里
+ *  静默落内存(只留一行 warn):会话 / 停驻 / run 账本进进程内存、重启即丢,而 `/health` 照样 200 —— [ref] P 类 fail-open。
+ *  零 DSN 的内存是配置说的(`config.ts` 的 `auto` 在无坐标时就不探测),不经过本函数。**显式** DB_BACKEND=local 仍 fail-loud——
  *  operator 要了 durable,静默丢=丢数据。 */
 export declare function openStoreBackendWithFallback(config: ServiceConfig, logger: {
     warn: (msg: string, meta?: Record<string, unknown>) => void;
@@ -409,9 +412,17 @@ export declare function openStoreBackendWithFallback(config: ServiceConfig, logg
     degradedReason: StoreDegradedReason | undefined;
 }>;
 /**
- * S-866 ⑤c / G4 —— SQL 族「显式要了持久而店打不开」的拒启句(唯一铸点)。点名 `DB_BACKEND=<引擎>`,给三条出路:修坐标 / 连通性;
- * `SESSION_BACKEND=auto`(尽力而为:店不可达时以内存起服,什么都不持久);`DB_BACKEND=memory`(显式内存部署)。驱动原文只取 message
- * (与修前 `fatalExit` 打出的同一句),凭据不在其中(驱动不回显口令)。
+ * 已配置的 SQL 库坐标 → 一条只含 `scheme://host:port` 的 URL 串,**交给**配置型 URL 的唯一显示铸点 {@link buildDisplaySafeUrl}
+ * (出口处写 `buildDisplaySafeUrl(sqlStoreCoordinatesAsUrl(config))`)。它**不是**一份显示投影:显示形只有铸点一只;这里只做「结构化坐标 → URL 串」的拼装
+ * (`config.tidb` / `config.pg` 本来就是结构化坐标,没有 DSN 字符串),user / password / database 一概不进产物。
+ * host 过不了闭字符集(拼进 URL 会把 `/` `@` `?` 之类带成别的成分)或无坐标 ⇒ 交出一个不是 URL 的串,铸点答它的占位 `«redacted:url»`。
+ * scheme 只是引擎名(`postgres` / `mysql`),不对应任何连接。
  */
-export declare function buildSqlStoreOpenRefusal(engine: "mysql" | "pg", err: unknown): string;
+export declare function sqlStoreCoordinatesAsUrl(config: Pick<ServiceConfig, "dbBackend" | "tidb" | "pg">): string;
+/**
+ * SQL 族「配了 DSN 而店打不开(窗内重试过了)」的拒启句(唯一铸点)。点名 `DB_BACKEND=<引擎>`、库的显示安全形(`postgres://host:port` / `mysql://host:port`,经 {@link sqlStoreCoordinatesAsUrl} 拼出、再过 {@link buildDisplaySafeUrl},
+ * 不带口令)、等了多久,出路两条:修坐标 / 连通性(窗是 `STORE_LOCK_WAIT_MS`);或**显式**内存部署(`DB_BACKEND=memory`)。🔴 没有第三条
+ * 「`SESSION_BACKEND=auto` 内存起服」—— 那一条就是被删掉的静默降级。驱动原文只取 message(与修前 `fatalExit` 打出的同一句),凭据不在其中(驱动不回显口令)。
+ */
+export declare function buildSqlStoreOpenRefusal(engine: "mysql" | "pg", endpoint: string, waitedMs: number, err: unknown): string;
 //# sourceMappingURL=store-backend.d.ts.map

package/dist/plugins/store-backend.js

@@ -1,7 +1,8 @@
 import { homedir } from "node:os";
 import { createCorruptReadFailOpenSeat, createDurableAbsenceSeat } from "../observability/corrupt-read-seat.js";
+import { createLogger } from "../observability/logger.js";
 import { join } from "node:path";
-import { AdoptionError, FileStorageBackend, FileSessionRepo } from "@sema-agent/core";
+import { AdoptionError, FileStorageBackend } from "@sema-agent/core";
 import { FileWorkflowJournalStore } from "@sema-agent/core";
 import { fileSessionCaptureRecordStore } from "@sema-agent/core";
 import { TiDBOutcomeLedger, PgOutcomeLedger } from "./outcome-ledger-sql.js";
@@ -12,8 +13,7 @@ import { StoreBootRefusalError } from "./store-contracts.js";
 import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
 import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
-import { LocalSessionStore } from "./local-session-store.js";
-import { noteReplayInSessionOpenScope } from "../session-records-skipped-notice.js";
+import { LocalSessionStore, createLocalSessionRepo } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { TiDBApprovalExemptionStore, PgApprovalExemptionStore, FileApprovalExemptionStore } from "./approval-exemption-store.js";
@@ -30,6 +30,7 @@ import { TiDBSessionPolicyStore, PgSessionPolicyStore } from "./session-policy-s
 import { TiDBWorkflowJournalStore, PgWorkflowJournalStore } from "./workflow-journal-store-sql.js";
 import { TiDBFileHistoryStore, PgFileHistoryStore, FILE_HISTORY_BLOB_TABLE, FILE_HISTORY_BLOB_KEY_PREFIX } from "./file-history-store-sql.js";
 import { MinioBlobBackend, SqlBlobBackend } from "./blob-backend.js";
+import { buildDisplaySafeUrl } from "../trace/redact.js";
 import { fileMemoryControlDirFor } from "../memory-scope.js";
 import { createTidbPool, ensureSchema as ensureTidbSchema } from "./tidb-pool.js";
 import { createPgPool, ensurePgSchema, pgPoolOptions } from "./pg-pool.js";
@@ -55,6 +56,7 @@ import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
 import { createFilePermissionRuleStores } from "./permission-rule-store-file.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { storeDegradedReasonFor } from "../store-posture.js";
+import { openWithinWait } from "./store-open-wait.js";
 function historyBlobBackend(config, dialect, pool) {
     const s = config.snapshotBlobStore;
     if (!s)
@@ -240,9 +242,7 @@ class LocalBackend {
             throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)}` +
                 (tail === undefined ? "" : ` ${tail}`));
         }
-        this.sessionStore = new LocalSessionStore(new FileSessionRepo(this.fileBackend.root, {
-            onCorruptRead: createCorruptReadFailOpenSeat("server.session-repo.corrupt-record-skipped", noteReplayInSessionOpenScope),
-        }), this.fileBackend.root);
+        this.sessionStore = new LocalSessionStore(createLocalSessionRepo(this.fileBackend.root), this.fileBackend.root, { log: createLogger(config.logLevel) });
         const corruptReadWarn = (msg, fields) => this.discloseWarn(msg, fields);
         this.runStore = new FileRunStore(this.fileBackend.root, {
             error: (msg, fields) => void (this.onError ?? this.onWarn)?.(msg, fields),
@@ -344,21 +344,41 @@ export function createStoreBackend(config, onWarn, onError) {
     return new TiDBBackend(createTidbPool(config), config);
 }
 export async function openStoreBackendWithFallback(config, logger) {
-    const mayFallback = config.dbBackend === "local" ? !config.dbBackendExplicit : config.sessionBackend === "auto";
+    const sqlEngine = config.dbBackend === "mysql" || config.dbBackend === "pg" ? config.dbBackend : undefined;
+    const mayFallback = config.dbBackend === "local" && !config.dbBackendExplicit;
     let backend;
+    let inFlight;
     try {
-        backend = createStoreBackend(config, (msg, meta) => logger.warn(msg, meta), logger.error === undefined ? undefined : (msg, meta) => logger.error(msg, meta));
-        if (backend)
-            await backend.ensureSchema();
+        const attempt = async () => {
+            let built;
+            try {
+                built = createStoreBackend(config, (msg, meta) => logger.warn(msg, meta), logger.error === undefined ? undefined : (msg, meta) => logger.error(msg, meta));
+                inFlight = built;
+                if (built)
+                    await built.ensureSchema();
+                inFlight = undefined;
+                return built;
+            }
+            catch (err) {
+                inFlight = undefined;
+                await built?.close().catch(() => undefined);
+                throw err;
+            }
+        };
+        backend =
+            sqlEngine === undefined
+                ? await attempt()
+                : await openWithinWait(attempt, config.storeLockWaitMs, (w) => logger.warn("store_sql_open_wait", { engine: sqlEngine, endpoint: buildDisplaySafeUrl(sqlStoreCoordinatesAsUrl(config)), waitMs: w.waitMs, error: w.error }));
     }
     catch (err) {
+        void inFlight?.close().catch(() => undefined);
         if (err instanceof AdoptionError)
             throw err;
         if (err instanceof StoreBootRefusalError)
             throw err;
         if (!mayFallback) {
-            if (config.dbBackend === "mysql" || config.dbBackend === "pg")
-                throw new Error(buildSqlStoreOpenRefusal(config.dbBackend, err), { cause: err });
+            if (sqlEngine !== undefined)
+                throw new Error(buildSqlStoreOpenRefusal(sqlEngine, buildDisplaySafeUrl(sqlStoreCoordinatesAsUrl(config)), config.storeLockWaitMs, err), { cause: err });
             throw err;
         }
         logger.warn("store_db_unreachable_fallback_memory", {
@@ -370,11 +390,21 @@ export async function openStoreBackendWithFallback(config, logger) {
     }
     return { backend, degradedReason: undefined };
 }
-export function buildSqlStoreOpenRefusal(engine, err) {
+const SQL_HOST = /^(?:[A-Za-z0-9._-]{1,253}|\[[0-9A-Fa-f:.]{2,45}\])$/;
+const SQL_COORDINATES_UNPRINTABLE = "<unprintable-coordinates>";
+export function sqlStoreCoordinatesAsUrl(config) {
+    const coords = config.dbBackend === "pg" ? config.pg : config.tidb;
+    if (coords === undefined || !SQL_HOST.test(coords.host))
+        return SQL_COORDINATES_UNPRINTABLE;
+    return `${config.dbBackend === "pg" ? "postgres" : "mysql"}://${coords.host}:${coords.port}`;
+}
+export function buildSqlStoreOpenRefusal(engine, endpoint, waitedMs, err) {
     const coords = engine === "pg" ? "PG_*" : "MYSQL_*";
     const detail = err instanceof Error ? err.message : String(err);
-    return (`DB_BACKEND=${engine}: cannot open the configured ${engine === "pg" ? "PostgreSQL" : "MySQL-protocol"} store (${detail}) — refusing to boot, because DB_BACKEND asks for a durable store and SESSION_BACKEND does not allow running without it. ` +
-        `Next: fix the ${coords} coordinates or the store's reachability; or set SESSION_BACKEND=auto to boot in memory while the store is unreachable (best effort — nothing persists, and /health reports storeDegraded); ` +
-        `or set DB_BACKEND=memory for an explicitly in-memory deployment.`);
+    const waited = waitedMs > 0 ? `after retrying for ${waitedMs}ms (STORE_LOCK_WAIT_MS)` : "on the first attempt (STORE_LOCK_WAIT_MS=0: no wait)";
+    return (`DB_BACKEND=${engine}: cannot open the configured ${engine === "pg" ? "PostgreSQL" : "MySQL-protocol"} store at ${endpoint} ${waited} (${detail}) — refusing to boot, because a configured SQL store is never replaced by an in-memory one ` +
+        `(SESSION_BACKEND=auto included: sessions, parked runs and every durable record would silently live in memory and vanish on restart). ` +
+        `Next: fix the ${coords} coordinates or the store's reachability (the boot wait is STORE_LOCK_WAIT_MS); ` +
+        `or run explicitly in memory with DB_BACKEND=memory (and remove the ${coords} coordinates).`);
 }
 //# sourceMappingURL=store-backend.js.map

package/dist/plugins/store-open-wait.d.ts

@@ -0,0 +1,33 @@
+/** 进入等待腿时的**一次性**披露(结构上只在第一次失败时调一次,不是靠一个 flag 挡刷屏)。 */
+export type StoreOpenWaitSink = (fields: {
+    readonly waitMs: number;
+    readonly error: string;
+}) => void;
+/** 时钟三面(异步形:`sleep` 返回 Promise)。三面都是形参,判据不靠真时间。`deadline` = 一只可取消的到点信号(窗尾打断挂起的尝试用)。 */
+export interface StoreOpenWaitClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    deadline(ms: number): {
+        readonly expired: Promise<void>;
+        cancel(): void;
+    };
+}
+/** {@link openWithinWait} 抛出的是不是「到窗仍未返回、且从没有过一次真失败」那一形(调用方据此区分「没有证据」与「有一次确定的失败」)。 */
+export declare function isStoreOpenWindowExpired(err: unknown): boolean;
+/**
+ * 跑 `open`;失败且窗为正 ⇒ 在窗内每 {@link STORE_LOCK_POLL_MS} 重试。
+ *
+ * 🔴 **窗尾只有一条规则**:到窗时手上有一次**完成了的**真失败 ⇒ **原样**抛最近那一次(同一个对象,不重铸 —— 库的拒句读驱动原文,桶的拒句读
+ * 「缺桶」那只错);**从头到尾一次真失败都没有**(每次尝试都挂着)⇒ 抛 {@link StoreOpenWindowExpired}(「到窗仍未返回」,{@link isStoreOpenWindowExpired} 判别)。
+ *  · 窗从**第一次尝试开始**算,每次尝试与**剩余**窗赛跑 —— 挂起的尝试到窗尾也被打断(库接受了 TCP 却永不回握手、DDL 被长期锁住);被打断的那次尝试
+ *    不再有人等它:它迟到的结局被吞掉(没人接 = 未处理拒绝会杀进程),它手上的资源由调用方的 `open` 自己收(见 `openStoreBackendWithFallback` 的在飞登记)。
+ *  · 剩余窗 ≤ 0 **不再起新一次尝试**:一次失败之后的等待吃完了窗,就抛那次失败 —— 不起一次注定跟 0 ms 的到点赛跑、又几乎总是输的尝试
+ *    (那一形会把一次确定的失败换成「到窗仍未返回」:口令错读成库挂住、缺桶读成没有证据)。
+ * 窗为 0 ⇒ **只试一次、不设界**(与 7.118.x 同形:一次尝试挂多久由驱动自己的超时决定 —— 本腿不替它造一个)。
+ *
+ * @param open    一次完整尝试(造后端 + `ensureSchema()` / 一次桶探针);**失败时必须自己把这次造出的池还回去**,窗内会被再调用。
+ * @param waitMs  `config.storeLockWaitMs`。`> 0` 才等;`0` / 非数 ⇒ 只试一次(`!(waitMs > 0)` 同时盖住「键缺席」的手搓 config)。
+ * @param onWait  进入等待腿的一次性披露口(第一次完成的失败时调一次)。
+ */
+export declare function openWithinWait<T>(open: () => Promise<T>, waitMs: number, onWait: StoreOpenWaitSink, clock?: StoreOpenWaitClock): Promise<T>;
+//# sourceMappingURL=store-open-wait.d.ts.map

package/dist/plugins/store-open-wait.js

@@ -0,0 +1,73 @@
+import { STORE_LOCK_POLL_MS } from "./store-lock-wait.js";
+const REAL_CLOCK = {
+    now: () => performance.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    deadline: (ms) => {
+        let timer;
+        const expired = new Promise((resolve) => {
+            timer = setTimeout(resolve, ms);
+        });
+        return { expired, cancel: () => clearTimeout(timer) };
+    },
+};
+class StoreOpenWindowExpired extends Error {
+    constructor(waitMs) {
+        super(`the open attempt was still pending when the ${waitMs}ms window ended`);
+    }
+}
+export function isStoreOpenWindowExpired(err) {
+    return err instanceof StoreOpenWindowExpired;
+}
+export async function openWithinWait(open, waitMs, onWait, clock = REAL_CLOCK) {
+    if (!(waitMs > 0))
+        return await open();
+    const startedAt = clock.now();
+    let lastFailure;
+    for (;;) {
+        const remainingMs = waitMs - (clock.now() - startedAt);
+        if (lastFailure !== undefined && remainingMs <= 0)
+            throw lastFailure.error;
+        const deadline = clock.deadline(Math.max(remainingMs, 0));
+        let outcome;
+        try {
+            outcome = await Promise.race([
+                attemptOnce(open).then((value) => ({ kind: "opened", value }), (error) => ({ kind: "failed", error })),
+                deadline.expired.then(() => ({ kind: "window_ended" })),
+            ]);
+        }
+        finally {
+            deadline.cancel();
+        }
+        switch (outcome.kind) {
+            case "opened":
+                return outcome.value;
+            case "window_ended":
+                if (lastFailure !== undefined)
+                    throw lastFailure.error;
+                throw new StoreOpenWindowExpired(waitMs);
+            case "failed": {
+                if (lastFailure === undefined)
+                    onWait({ waitMs, error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) });
+                lastFailure = { error: outcome.error };
+                const left = waitMs - (clock.now() - startedAt);
+                if (left <= 0)
+                    throw outcome.error;
+                await clock.sleep(Math.min(STORE_LOCK_POLL_MS, left));
+                break;
+            }
+            default: {
+                const unhandled = outcome;
+                throw new Error(`unhandled open attempt outcome: ${JSON.stringify(unhandled)}`);
+            }
+        }
+    }
+}
+function attemptOnce(open) {
+    try {
+        return open();
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
+}
+//# sourceMappingURL=store-open-wait.js.map

package/dist/plugins/tidb-pool.js

@@ -528,7 +528,7 @@ export const SCHEMA_STATEMENTS = [
      run_id     VARCHAR(191) NOT NULL,
      agent_key  VARCHAR(191) NOT NULL,
      scope      VARCHAR(190) NOT NULL,
-     PRIMARY KEY (session_id),
+     PRIMARY KEY (session_id, run_id),
      KEY idx_wfagentsess_run (run_id)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS workflow_completion_inbox (

package/dist/plugins/web-search.d.ts

@@ -106,7 +106,7 @@ export interface WebSearchCapability {
 export declare function projectWebSearchCapability(provider: WebSearchProvider | undefined): WebSearchCapability;
 export interface WebSearchBackendConfig {
     readonly provider: WebSearchProvider;
-    /** API key (brave/tavily). From `WEB_SEARCH_API_KEY` — never reaches the model. */
+    /** API key (brave/tavily). From `WEB_SEARCH_API_KEY` — never reaches the model. Must be usable as an HTTP header value ({@link isHttpHeaderValue}); the judges refuse one that is not, and the brave / tavily legs refuse it again before fetch. */
     readonly apiKey?: string;
     /** SearXNG 实例特定查询参数(`engines=` / `language=` 等)——透传给 core adapter 的 `extraParams`。
      *  一键装 SearXNG 的向导用它把「选了哪些上游引擎」落到引擎侧。仅 searxng 腿消费。 */
@@ -136,6 +136,25 @@ export interface WebSearchBackend {
     search: WebSearchFn;
     maxResults: number;
 }
+/**
+ * 🔴 「这个串能不能当 HTTP 头值」的**唯一**判据 —— 受理面(请求腿 `settings.webSearch.apiKey`)、部署 env 腿
+ * (`WEB_SEARCH_API_KEY`)与后端腿(brave / tavily 交给 fetch 之前)**同问这一只**。
+ *
+ * ## 病
+ * `apiKey` 以前只判「是串」。带换行 / NUL / 其它控制字符 / U+00FF 以上字符的 key 两条载体都采纳,到 fetch 构造或发出请求头的那一刻运行时当场抛;
+ * 构造腿那一抛是 `Headers.append: "<整串 key>" is an invalid header value.` —— 凭据明文就在 message 里,经 WebSearch 工具失败卡进模型与转写面。
+ *
+ * ## 判据就是运行时的那条流水线,问的是 Node 自带的两只校验
+ * fetch 对一个头值做两步:① `Headers` 构造 —— 首尾 HTTP 空白(含 CR / LF)归一化剥掉,其余位置的 CR / LF / NUL 与 U+00FF 以上字符抛;
+ * ② 发送层(undici)对**归一化后的值**再过一遍字符表(HT、U+0020..U+007E、U+0080..U+00FF 可发;其余控制字符与 U+007F 抛 `invalid <name> header`)。
+ * 本判据逐步问同样两只:`new Headers(...)` 取归一化值,再交 `node:http` 的 `validateHeaderValue`(与发送层同一张字符表)。**不自写字符表**
+ * (第二份表迟早与运行时漂开);两步合起来与真 fetch 的对拍钉在 `test/web-search.test.ts`(本地受控端点,U+0000..U+017F 逐字符全扫)—— 运行时改了头值律,那一格先红。
+ * 只问 `Headers` 构造是不够的:它接受 U+0001 / U+007F,发送层拒绝(两步缺一步 ⇒ 判官收下、每次搜索必失败)。
+ * 镜像运行时的后果如实:首尾空白(含 CR / LF)归一化后不剩,所以 `"key\n"` 这种从密钥文件带出尾随换行的串**照收**、发出去的是剥后的值 ——
+ * 与 {@link judgeEndpoint} 对 `https://@host` 同一条姿势:不比运行时多拒。
+ * 抛出的错误对象在这里**当场丢弃**(构造腿那条的 message 就是那串明文),调用方拿到的只有布尔。
+ */
+export declare function isHttpHeaderValue(value: string): boolean;
 export declare function setWebSearchBadPayloadObserver(fn: ((provider: string) => void) | undefined): void;
 /**
  * Build the `WebSearchConfig` (a `search` fn + `maxResults`) for `assembleFullBodyTools({ webSearch })`. The API key