@sema-agent/server 7.132.0 → 7.133.0

package/dist/plugins/workflow-journal-store-sql.d.ts

@@ -11,17 +11,50 @@
  * journal is LOAD-BEARING (unlike the best-effort {@link import("./run-store-sql.js")} observation layer):
  * append/load failures MUST throw — a silently-dropped entry would silently re-run already-done work.
  *
- * Schema = `workflow_journal (run_id, ordinal) PK` (DDL in tidb-pool.ts / pg-pool.ts ensureSchema). `ordinal`
- * is the positional index a callKey was minted at, derived with core's {@link callKeyOrdinal} (NEVER
+ * Schema = two tables (DDL in tidb-pool.ts / pg-pool.ts ensureSchema), the SQL normal form of core's per-run
+ * record (InMemory `{ scope, byOrdinal }` / File "first line names the scope, one line per ordinal"):
+ *   - `workflow_journal_owner (run_id) PK` — the run's ONE owning scope, the `incarnation` token minted by the claim
+ *     that wrote the record, and `appended_at_ms` (the owner's last append; the GC clock of this row). Written by the
+ *     run's first append; never a second scope (S-197, below).
+ *   - `workflow_journal (run_id, incarnation, ordinal) PK` — one row per recorded call, keyed by the owner record that
+ *     wrote it. NO scope column: a run's scope lives in exactly one place, so "one run, two scopes" is not a state this
+ *     schema can hold.
+ * `ordinal` is the positional index a callKey was minted at, derived with core's {@link callKeyOrdinal} (NEVER
  * hand-parsed — a malformed key falls back to ordinal 0 there, matching the InMemory store). `result` holds
  * `JSON.stringify(entry.result)` (a TaskResult is plain serializable data). The PK makes append IDEMPOTENT per
- * (run_id, ordinal): a second append for the same ordinal OVERWRITES (last-write-wins) — a resumed run
- * re-appends its replayed prefix verbatim, so this is the exact InMemory `byOrdinal.set(ordinal, …)` semantics,
- * not a duplicate row.
+ * (run_id, ordinal) under the run's owner record (a run has one at a time): a second append for the same ordinal
+ * OVERWRITES (last-write-wins) — a resumed run re-appends its replayed prefix verbatim, so this is the exact InMemory
+ * `byOrdinal.set(ordinal, …)` semantics, not a duplicate row.
+ *
+ * 🔴 **The scope wall — ONE predicate, both faces** (S-197; core `workflowJournalStoreContract` "scope wall" case;
+ * core's InMemory / File stores refuse the same way): a run's journal belongs to the scope of its first append. Every
+ * face answers through the owner row and the same pair `workflow_journal_owner.run_id = ? AND scope = ?`:
+ *   - `append` writes its row through `INSERT … SELECT … FROM workflow_journal_owner WHERE run_id = ? AND scope = ?` —
+ *     the judge sits in the WRITE's own WHERE (no read-then-write), and `affected = 0` ⇒ refuse, nothing written; the
+ *     row takes its `incarnation` from that same owner record, in that same statement;
+ *   - `load` / `loadPage` read through `JOIN workflow_journal_owner USING (run_id, incarnation)` + the same
+ *     `run_id = ? AND scope = ?`.
+ * Why the owner record's incarnation is in the row's PRIMARY KEY (one rule: **a row belongs to the owner record that
+ * wrote it — readable only through it, overwritable only by a write made through it**): a write can outlive the owner
+ * record it was judged against — `deleteByRun` / the GC sweep racing an append, an append stalled between its two
+ * statements. Keyed and joined on run_id alone, (a) a leftover row would be adopted by the next claim of that run_id by
+ * ANY scope, and (b) on PostgreSQL READ COMMITTED a stale guarded write whose SELECT still saw the old record would, via
+ * the ON CONFLICT arm (which updates a row its snapshot never saw, without re-checking the source), overwrite the NEW
+ * owner's row at the same ordinal. With the incarnation in the key, the stale write lands on a key of the dead record —
+ * a row readable by no one, removed by the sweep — and the new record's rows are untouchable by it, on every engine,
+ * without a locking clause.
+ * Before S-197 the scope sat on every row: the read faces filtered it, the write face never judged it (a cross-scope
+ * append on a NEW ordinal inserted a second scope's row into the run; on an EXISTING ordinal it overwrote the owner's
+ * result under the owner's scope), held up by "runId is unique per scope and the owner is the sole writer".
  *
  * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
- *   - `?` placeholders vs `$n`
- *   - `ON DUPLICATE KEY UPDATE … VALUES(col)` vs `ON CONFLICT (run_id, ordinal) DO UPDATE SET … EXCLUDED.col`
+ *   - `?` placeholders vs `$n` (`append`'s two statements bind ONE params array on both dialects: PG numbers its
+ *     placeholders in text order there, so no per-dialect reordering exists on that face)
+ *   - `ON DUPLICATE KEY UPDATE … VALUES(col)` vs `ON CONFLICT (run_id, incarnation, ordinal) DO UPDATE SET … EXCLUDED.col`
+ *   - the owner claim's "refresh only for the owner": MySQL protocol `IF(scope = VALUES(scope), …)` inside
+ *     `ON DUPLICATE KEY UPDATE` (no WHERE there) vs PG `ON CONFLICT (run_id) DO UPDATE … WHERE workflow_journal_owner.scope = EXCLUDED.scope`
+ *   - PG casts the guarded write's bound values (`$1::int` …): they sit in a SELECT list, where an untyped
+ *     parameter has no column to take its type from
  *   - `LENGTH(result)` (TiDB — byte length) vs `OCTET_LENGTH(result)` (PG — `LENGTH(text)` is CHARACTER count;
  *     a multi-byte UTF-8 payload would silently slip past the byte-budget cap on PG with plain `LENGTH`, so
  *     the twin uses the byte-counting function instead — codex R3, real dual-DB-suite-confirmed) in `loadPage`'s
@@ -31,8 +64,14 @@
  *     `$n` are POSITIONAL (not text-order), so its array is `[runId, scope, maxResultBytes, limit, offset]`
  *     (`$3` inside the CASE refers to the third element regardless of where `$3` sits in the text). Same
  *     placeholder-arity-fallout class the sql-driver.ts header calls out for null-safe compares.
- *   - affectedRows vs rowCount (via SqlDriver's normalized `affected`).
- *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL in pg-pool.ts (neither store creates tables).
+ *   - affectedRows vs rowCount (via SqlDriver's normalized `affected`). The guarded write reads it as the wall's
+ *     verdict: 0 ⇔ the SELECT found no owner row for (run_id, scope). A matched row always counts ≥ 1 — PG 1;
+ *     MySQL protocol 1 (insert) / 2 (update) / 1 for a duplicate left unchanged, because mysql2 connects with
+ *     CLIENT_FOUND_ROWS by default (TiDB answers 1 there too) — pinned by the identical-bytes re-append cell of
+ *     workflow-journal-store-integration.test.ts.
+ *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL in pg-pool.ts (neither store creates tables); the 7.132.x
+ *     row-level scope column is moved into the owner table by the one-time migration M24 (window in
+ *     plugins/one-time-migrations.ts).
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
@@ -54,21 +93,24 @@ export declare class SqlWorkflowJournalStore implements WorkflowJournalStore {
     constructor(db: SqlDriver, opts?: SqlWorkflowJournalStoreOptions);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
-    /** Record one agent's result. Idempotent per (run_id, ordinal): the PK upsert OVERWRITES (last-write-wins), so a
+    /** Record one agent's result. Idempotent per (run_id, ordinal) under the run's owner record: the PK upsert OVERWRITES (last-write-wins), so a
      *  resumed run re-appending its replayed prefix verbatim leaves no duplicate. callKeyOrdinal is the SOLE ordinal
      *  source (core's parser — a malformed key collapses to 0, matching InMemory). Throws on a REAL failure
-     *  (LOAD-BEARING) — an oversize entry included, on BOTH arms (S-194 / core 7.12.0 [ref]; see below). */
+     *  (LOAD-BEARING) — an oversize entry included, on BOTH arms (S-194 / core 7.12.0 [ref]; see below) — and REFUSES an
+     *  append under a scope other than the run's owner, on any ordinal and both arms, writing nothing (S-197; the scope
+     *  wall in the file header). */
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
-    /** Entries for `runId` IF its recorded scope === `scope`, ASCENDING by ordinal; otherwise EMPTY. CORE-9 audit
-     *  BLOCKER: scope in the WHERE (twin of WorkflowRunStore) — the LLM controls `resumeFromRunId`, so a cross-scope
-     *  runId resolves to an empty journal (resume safely diverges to live, never discloses another tenant's results).
-     *  Each row's `result` is the persisted JSON.stringify(TaskResult) → JSON.parse back. Throws on failure (LOAD-BEARING). */
+    /** Entries for `runId` IF its owner scope === `scope`, ASCENDING by ordinal; otherwise EMPTY. CORE-9 audit
+     *  BLOCKER: the scope wall (S-197: the owner row, the same predicate append writes through) — the LLM controls
+     *  `resumeFromRunId`, so a cross-scope runId resolves to an empty journal (resume safely diverges to live, never
+     *  discloses another tenant's results). Each row's `result` is the persisted JSON.stringify(TaskResult) → JSON.parse
+     *  back. Throws on failure (LOAD-BEARING). */
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
     /** [ref] locator 云形(core 1.353 WorkflowJournalStore.locator additive):SQL 店的 journal 坐标=
      *  [ref] HTTP 读面路由(file 店返 jsonl 路径=CC 本地形;此处返云形,core 铸 diagnostics 教句时单源引用)。 */
     locator(runId: string, _scope: string): string;
     /** codex R1-H2:分页投影读——LIMIT/OFFSET 界行数,字节门界单行字节(超限行不取 result 全文,只回字节数;
-     *  读面标 truncated)。ORDER BY ordinal 与 load 同轴。
+     *  读面标 truncated)。ORDER BY ordinal 与 load 同轴;scope 墙与 load 同一只 JOIN(S-197)。
      *  🔴 param ORDER differs by dialect (see file header): TiDB's `?`s bind in text order (maxResultBytes first,
      *  inside the CASE); PG's `$n` are positional, so its array keeps runId/scope first. Never unify — a swap
      *  silently mis-binds the OTHER dialect's placeholders. */
@@ -81,8 +123,10 @@ export declare class SqlWorkflowJournalStore implements WorkflowJournalStore {
         resultJson: string | null;
         resultBytes: number;
     }>>;
-    /** GC — purge ALL journal entries for a run (the run reaper calls this once the run is terminal + retained). Scoped
-     *  by run_id alone; idempotent (affected-row count). Mirrors the resume-anchor store's deleteBySession. */
+    /** GC — purge ALL journal entries for a run (every incarnation), then its owner row (S-197). Scoped by run_id alone;
+     *  idempotent (returns the journal rows removed). Mirrors the resume-anchor store's deleteBySession. An append racing the
+     *  two DELETEs can leave a row behind without its owner record; it is keyed by the dead incarnation — readable and
+     *  overwritable by no one (file header) — and the GC sweep removes it by age. */
     deleteByRun(runId: string): Promise<number>;
     /** [ref] / WF2([ref] core 拍板 a 形,签名逐字)—— cross-replica resume admission lease。
      *
@@ -111,7 +155,17 @@ export declare class SqlWorkflowJournalStore implements WorkflowJournalStore {
      *  per-run deleteByRun has no production caller (a run-store reap gives no per-run hook), so this bounded sweep
      *  — wired into the service reaper — is what keeps the heaviest table (TaskResult-bearing) from growing without
      *  bound. A resume of a journal older than the retention window simply re-runs live (resume is an optimization).
-     *  Idempotent; returns the rows purged. */
+     *  Idempotent; returns the journal rows purged.
+     *
+     *  S-197: the same cutoff then purges owner rows whose OWN clock (`appended_at_ms`, pushed by every append of the
+     *  owner) is older. Each DELETE's predicate reads only the row it deletes — a cross-table "owner with no rows left"
+     *  test inside the DELETE would be a non-current read on every engine here (the B-022 lesson: TiDB pins start_ts, PG
+     *  READ COMMITTED re-checks only the target row), so a concurrent append could have its owner deleted from under it.
+     *  Every row of a run was written by an append that first pushed the owner's clock (monotonically — GREATEST) to at least
+     *  that row's `created_at_ms`, so an owner past the cutoff normally has no row left after the first DELETE. The one
+     *  exception — an append whose guarded write lands after the first DELETE although its claim is older than the cutoff (a
+     *  stall longer than the retention window between its two statements) — leaves a row without its owner record: keyed by
+     *  the dead incarnation, readable by no one (file header), removed by a later sweep. */
     reapExpired(now: number, maxAgeMs: number): Promise<number>;
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */

package/dist/plugins/workflow-journal-store-sql.js

@@ -1,6 +1,7 @@
 import { callKeyOrdinal } from "@sema-agent/core";
 import { assertJournalEntryFits } from "@sema-agent/core";
 import { journalEntryOfBody, journalRowPayloadOf, readJournalRowBody } from "../orchestration/workflow-journal-entry.js";
+import { randomUUID } from "node:crypto";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, jsonColumnTextExpr } from "./sql-json-column.js";
 const DEFAULT_RESUME_CLAIM_TTL_MS = 60 * 60 * 1000;
@@ -25,12 +26,21 @@ export class SqlWorkflowJournalStore {
     async append(runId, scope, entry) {
         assertJournalEntryFits(entry);
         const serialized = journalRowPayloadOf(entry);
-        await this.db.query(this.q("INSERT INTO workflow_journal (run_id, ordinal, scope, call_key, result, created_at_ms) VALUES (?,?,?,?,?,?) " +
-            "ON DUPLICATE KEY UPDATE call_key = VALUES(call_key), result = VALUES(result)", "INSERT INTO workflow_journal (run_id, ordinal, scope, call_key, result, created_at_ms) VALUES ($1,$2,$3,$4,$5,$6) " +
-            "ON CONFLICT (run_id, ordinal) DO UPDATE SET call_key = EXCLUDED.call_key, result = EXCLUDED.result"), [runId, callKeyOrdinal(entry.callKey), scope, entry.callKey, serialized, Date.now()]);
+        const now = Date.now();
+        await this.db.query(this.q("INSERT INTO workflow_journal_owner (run_id, scope, incarnation, appended_at_ms) VALUES (?,?,?,?) " +
+            "ON DUPLICATE KEY UPDATE appended_at_ms = IF(scope = VALUES(scope), GREATEST(appended_at_ms, VALUES(appended_at_ms)), appended_at_ms)", "INSERT INTO workflow_journal_owner (run_id, scope, incarnation, appended_at_ms) VALUES ($1,$2,$3,$4) " +
+            "ON CONFLICT (run_id) DO UPDATE SET appended_at_ms = GREATEST(workflow_journal_owner.appended_at_ms, EXCLUDED.appended_at_ms) WHERE workflow_journal_owner.scope = EXCLUDED.scope"), [runId, scope, randomUUID(), now]);
+        const written = await this.db.query(this.q("INSERT INTO workflow_journal (run_id, incarnation, ordinal, call_key, result, created_at_ms) " +
+            "SELECT run_id, incarnation, ?, ?, ?, ? FROM workflow_journal_owner WHERE run_id = ? AND scope = ? " +
+            "ON DUPLICATE KEY UPDATE call_key = VALUES(call_key), result = VALUES(result)", "INSERT INTO workflow_journal (run_id, incarnation, ordinal, call_key, result, created_at_ms) " +
+            "SELECT run_id, incarnation, $1::int, $2::varchar, $3::text, $4::bigint FROM workflow_journal_owner WHERE run_id = $5 AND scope = $6 " +
+            "ON CONFLICT (run_id, incarnation, ordinal) DO UPDATE SET call_key = EXCLUDED.call_key, result = EXCLUDED.result"), [callKeyOrdinal(entry.callKey), entry.callKey, serialized, now, runId, scope]);
+        if (written.affected === 0) {
+            throw new Error(`workflow journal: runId ${runId} already recorded under a different scope — refusing the append; nothing was written`);
+        }
     }
     async load(runId, scope) {
-        const { rows } = await this.db.query(this.q(`SELECT call_key, ${jsonColumnText("tidb", "result")} FROM workflow_journal WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC`, `SELECT call_key, ${jsonColumnText("pg", "result")} FROM workflow_journal WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC`), [runId, scope]);
+        const { rows } = await this.db.query(this.q(`SELECT call_key, ${jsonColumnText("tidb", "result")} FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC`, `SELECT call_key, ${jsonColumnText("pg", "result")} FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC`), [runId, scope]);
         return rows.map((r) => {
             const callKey = String(r.call_key);
             return journalEntryOfBody(callKey, decodeJournalResult(r.result, `workflow_journal.result for run ${runId} entry ${callKey}`));
@@ -43,11 +53,12 @@ export class SqlWorkflowJournalStore {
         const params = this.db.dialect === "tidb"
             ? [opts.maxResultBytes, runId, scope, opts.limit, opts.offset]
             : [runId, scope, opts.maxResultBytes, opts.limit, opts.offset];
-        const { rows } = await this.db.query(this.q(`SELECT call_key, CASE WHEN LENGTH(result) > ? THEN NULL ELSE ${jsonColumnTextExpr("tidb", "result")} END AS result_json, LENGTH(result) AS result_bytes FROM workflow_journal WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC LIMIT ? OFFSET ?`, `SELECT call_key, CASE WHEN OCTET_LENGTH(result) > $3 THEN NULL ELSE ${jsonColumnTextExpr("pg", "result")} END AS result_json, OCTET_LENGTH(result) AS result_bytes FROM workflow_journal WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC LIMIT $4 OFFSET $5`), params);
+        const { rows } = await this.db.query(this.q(`SELECT call_key, CASE WHEN LENGTH(result) > ? THEN NULL ELSE ${jsonColumnTextExpr("tidb", "result")} END AS result_json, LENGTH(result) AS result_bytes FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC LIMIT ? OFFSET ?`, `SELECT call_key, CASE WHEN OCTET_LENGTH(result) > $3 THEN NULL ELSE ${jsonColumnTextExpr("pg", "result")} END AS result_json, OCTET_LENGTH(result) AS result_bytes FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC LIMIT $4 OFFSET $5`), params);
         return rows.map((r) => ({ callKey: String(r.call_key), resultJson: r.result_json === null ? null : String(r.result_json), resultBytes: Number(r.result_bytes) }));
     }
     async deleteByRun(runId) {
         const res = await this.db.query(this.q("DELETE FROM workflow_journal WHERE run_id = ?", "DELETE FROM workflow_journal WHERE run_id = $1"), [runId]);
+        await this.db.query(this.q("DELETE FROM workflow_journal_owner WHERE run_id = ?", "DELETE FROM workflow_journal_owner WHERE run_id = $1"), [runId]);
         return res.affected;
     }
     async resumeClaim(input) {
@@ -72,7 +83,9 @@ export class SqlWorkflowJournalStore {
         await this.db.query(this.q("DELETE FROM workflow_resume_claim WHERE source_run_id = ? AND scope = ? AND new_run_id = ?", "DELETE FROM workflow_resume_claim WHERE source_run_id = $1 AND scope = $2 AND new_run_id = $3"), [input.sourceRunId, input.scope, input.newRunId]);
     }
     async reapExpired(now, maxAgeMs) {
-        const res = await this.db.query(this.q("DELETE FROM workflow_journal WHERE created_at_ms < ?", "DELETE FROM workflow_journal WHERE created_at_ms < $1"), [now - maxAgeMs]);
+        const cutoff = now - maxAgeMs;
+        const res = await this.db.query(this.q("DELETE FROM workflow_journal WHERE created_at_ms < ?", "DELETE FROM workflow_journal WHERE created_at_ms < $1"), [cutoff]);
+        await this.db.query(this.q("DELETE FROM workflow_journal_owner WHERE appended_at_ms < ?", "DELETE FROM workflow_journal_owner WHERE appended_at_ms < $1"), [cutoff]);
         return res.affected;
     }
 }

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

@@ -56,10 +56,12 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { summarizeWorkflowRun, type WorkflowRunStore } from "@sema-agent/core";
+import { summarizeWorkflowRun, type CheckpointToken, type WorkflowRunStore } from "@sema-agent/core";
 import { type WorkflowCompletionInbox, type WorkflowCompletionInboxEntry } from "../orchestration/workflow-completion-inbox.js";
 import type { WorkflowNotifyJournalStore, WorkflowNotifyJournalEntry } from "../orchestration/workflow-notify-journal.js";
 import { type WorkflowAgentSessionIndex, type WorkflowAgentSessionRow } from "../orchestration/workflow-agent-session-index.js";
+import { type WorkflowParkDecision, type WorkflowParkDecisionStore } from "../orchestration/workflow-park-decision.js";
+import type { SqlRunStore } from "./run-store-sql.js";
 import { type SqlDriver } from "./sql-driver.js";
 type WorkflowRun = Parameters<WorkflowRunStore["put"]>[1];
 /** Row cap guard: a run blob beyond this is NOT stored on update (the prior revision stays) — TiDB's
@@ -189,23 +191,43 @@ export declare class SqlWorkflowNotifyJournalStore implements WorkflowNotifyJour
  * 收割在删 run 行的同一个方法里按同一张待删 id 表删它们的指针({@link SqlWorkflowRunStore.reap})。
  *
  * ── 方言差,保持显式 ──────────────────────────────────────────────────────────────────────────
- *   - `?` 占位 vs `$n`,且 `syncRun` 的删除腿在 PG 上要按 `params.length` 记位(与 `listByScope` 同因)。
- *   - 「删掉这条 run 里已不在 rows 里的旧行」:TiDB `session_id NOT IN (?,?,…)`(动态占位数)vs
- *     PG `session_id <> ALL($n::text[])`(数组绑定)—— 两边同一件事,语句结构不同(reap 的批删同先例)。
+ *   - `?` 占位 vs `$n`。
  *   - upsert(主键 `(session_id, run_id)`):TiDB `REPLACE INTO`(整行替换)vs PG `INSERT … ON CONFLICT (session_id, run_id) DO UPDATE`。
  *   - schema 属主同店内其余表:TiDB DDL 在 tidb-pool.ts,PG DDL 在 pg-pool.ts(店不建表)。
  *
- * 🔴 **写序**:先 upsert 再删。反过来(先删后 upsert)会在两条语句之间留出一个**指针不存在**的窗口,
- * 而这期间进来的 `/decide` 会诚实 miss ⇒ 一次本可受理的批准被退回。先 upsert 的最坏形是窗口内多一枚
- * 旧指针(判决从记录读 ⇒ 多读一条记录,不会错配)。
+ * 指针只增不删(契约「指针先于记录」):本店没有删除腿,唯一的删除是 {@link SqlWorkflowRunStore.reap} 的级联。
  */
 export declare class SqlWorkflowAgentSessionIndex implements WorkflowAgentSessionIndex {
     private readonly db;
     constructor(db: SqlDriver);
     private q;
-    syncRun(runId: string, rows: readonly WorkflowAgentSessionRow[]): Promise<void>;
+    ensurePointers(_runId: string, rows: readonly WorkflowAgentSessionRow[]): Promise<void>;
     listByAgentSession(sessionId: string): Promise<WorkflowAgentSessionRow[]>;
 }
+/**
+ * workflow 子代停驻卡的耐久决定行 —— SQL 双生(契约与律的唯一属主 =
+ * {@link import("../orchestration/workflow-park-decision.js").WorkflowParkDecisionStore} 的文件头,这里只记方言差)。
+ * 写者只有 `/decide` 的 workflow 车道(开跑之前那一笔);删除只有 run 收割的级联({@link SqlWorkflowRunStore.reap})。
+ *
+ * 构造时绑在 SQL run 店上(`claims`):写在那只 run 店的认领栅栏事务里(`SqlRunStore.whileHoldingClaim` 交出的那条事务连接 —— 栅栏攥着
+ * run 行与认领行的锁直到提交),读走那只 run 店的池(`claims.db`)—— 决定行、认领、读写同一只池,池只有这一处来源。
+ *
+ * ── 方言差,保持显式 ──────────────────────────────────────────────────────────────────────────
+ *   - `?` 占位 vs `$n`。
+ *   - 整行 upsert(主键 `token`):TiDB `INSERT … ON DUPLICATE KEY UPDATE col = VALUES(col)` vs PG `INSERT … ON CONFLICT (token) DO UPDATE SET col = EXCLUDED.col`。
+ *     无条件:序由认领栅栏定(同一宿主会话上的受理由认领串行,栅栏事务的提交序就是受理序),`accepted_at_ms` 只是记下的值。
+ *   - `outcome` 是 JSON 承载的文本列(TiDB MEDIUMTEXT / PG TEXT,与 `workflow_run.run` 同形:两方言同一条 `JSON.stringify` 绑定),
+ *     读腿按文本投影、恰好解一次({@link jsonColumnText} / {@link decodeJsonColumn})。
+ *   - schema 属主同店内其余表:TiDB DDL 在 tidb-pool.ts,PG DDL 在 pg-pool.ts(店不建表)。
+ */
+export declare class SqlWorkflowParkDecisionStore implements WorkflowParkDecisionStore {
+    readonly claims: SqlRunStore;
+    constructor(claims: SqlRunStore);
+    private q;
+    record(d: WorkflowParkDecision): Promise<boolean>;
+    get(token: CheckpointToken): Promise<WorkflowParkDecision | null>;
+    listByHostSession(hostSessionId: string): Promise<WorkflowParkDecision[]>;
+}
 /** MySQL-protocol (TiDB) bindings — historical class names preserved; `onWarn` is an ADDITIVE optional 2nd
  *  ctor arg (existing 1-arg call sites are unaffected — see {@link SqlWorkflowRunStore}'s C5 trace channel). */
 export declare class TiDBWorkflowRunStore extends SqlWorkflowRunStore {

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

@@ -2,6 +2,7 @@ import { redactErrorMessage, redactHead } from "../observability/run-terminal.js
 import { summarizeWorkflowRun, isTerminalWorkflowStatus, WorkflowRunStoreError } from "@sema-agent/core";
 import { foldKeyFamily, MAX_PENDING_PER_SESSION, PURGE_FENCE_MS, SERVED_FENCE_MS, } from "../orchestration/workflow-completion-inbox.js";
 import {} from "../orchestration/workflow-agent-session-index.js";
+import { readWorkflowParkOutcome } from "../orchestration/workflow-park-decision.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { createObjectColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
 import { isDupKeyError } from "./sql-errors.js";
@@ -161,6 +162,7 @@ export class SqlWorkflowRunStore {
             return 0;
         const res = await this.db.query(this.q(`DELETE FROM workflow_run WHERE scope = ? AND id IN (${doomed.map(() => "?").join(",")})`, "DELETE FROM workflow_run WHERE scope = $1 AND id = ANY($2::text[])"), this.db.dialect === "tidb" ? [scope, ...doomed] : [scope, doomed]);
         await this.db.query(this.q(`DELETE FROM workflow_agent_session WHERE scope = ? AND run_id IN (${doomed.map(() => "?").join(",")})`, "DELETE FROM workflow_agent_session WHERE scope = $1 AND run_id = ANY($2::text[])"), this.db.dialect === "tidb" ? [scope, ...doomed] : [scope, doomed]);
+        await this.db.query(this.q(`DELETE FROM workflow_park_decision WHERE run_id IN (${doomed.map(() => "?").join(",")})`, "DELETE FROM workflow_park_decision WHERE run_id = ANY($1::text[])"), this.db.dialect === "tidb" ? [...doomed] : [doomed]);
         return res.affected;
     }
 }
@@ -309,25 +311,64 @@ export class SqlWorkflowAgentSessionIndex {
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    async syncRun(runId, rows) {
+    async ensurePointers(_runId, rows) {
         for (const r of rows) {
             await this.db.query(this.q("REPLACE INTO workflow_agent_session (session_id, run_id, agent_key, scope) VALUES (?,?,?,?)", `INSERT INTO workflow_agent_session (session_id, run_id, agent_key, scope) VALUES ($1,$2,$3,$4)
              ON CONFLICT (session_id, run_id) DO UPDATE SET agent_key = EXCLUDED.agent_key, scope = EXCLUDED.scope`), [r.sessionId, r.runId, r.agentKey, r.scope]);
         }
-        const keep = rows.map((r) => r.sessionId);
-        if (this.db.dialect === "tidb") {
-            const holes = keep.map(() => "?").join(",");
-            await this.db.query(`DELETE FROM workflow_agent_session WHERE run_id = ?${keep.length > 0 ? ` AND session_id NOT IN (${holes})` : ""}`, [runId, ...keep]);
-        }
-        else {
-            await this.db.query(`DELETE FROM workflow_agent_session WHERE run_id = $1${keep.length > 0 ? " AND session_id <> ALL($2::text[])" : ""}`, keep.length > 0 ? [runId, keep] : [runId]);
-        }
     }
     async listByAgentSession(sessionId) {
         const { rows } = await this.db.query(this.q("SELECT session_id, run_id, agent_key, scope FROM workflow_agent_session WHERE session_id = ? ORDER BY run_id", "SELECT session_id, run_id, agent_key, scope FROM workflow_agent_session WHERE session_id = $1 ORDER BY run_id"), [sessionId]);
         return rows.map((r) => ({ sessionId: String(r.session_id), runId: String(r.run_id), agentKey: String(r.agent_key), scope: String(r.scope) }));
     }
 }
+function readParkDecisionOutcomeColumn(v, where) {
+    try {
+        return decodeJsonColumn(v, readWorkflowParkOutcome, `workflow_park_decision.outcome ${where}`);
+    }
+    catch (e) {
+        throw foldJsonColumn(e, (m) => `SqlWorkflowParkDecisionStore: ${m} — refusing rather than hand the engine a decision nobody can read`);
+    }
+}
+export class SqlWorkflowParkDecisionStore {
+    claims;
+    constructor(claims) {
+        this.claims = claims;
+    }
+    q(tidb, pg) {
+        return this.claims.db.dialect === "tidb" ? tidb : pg;
+    }
+    async record(d) {
+        const fenced = await this.claims.whileHoldingClaim(d.hostSessionId, d.deliveredTaskId, async (tx) => {
+            await tx.query(this.q(`INSERT INTO workflow_park_decision (token, run_id, host_session_id, outcome, fingerprint, delivered_task_id, accepted_at_ms) VALUES (?,?,?,?,?,?,?)
+             ON DUPLICATE KEY UPDATE ${PARK_DECISION_REPLACED_COLUMNS.map((c) => `${c} = VALUES(${c})`).join(", ")}`, `INSERT INTO workflow_park_decision (token, run_id, host_session_id, outcome, fingerprint, delivered_task_id, accepted_at_ms) VALUES ($1,$2,$3,$4,$5,$6,$7)
+             ON CONFLICT (token) DO UPDATE SET ${PARK_DECISION_REPLACED_COLUMNS.map((c) => `${c} = EXCLUDED.${c}`).join(", ")}`), [d.token, d.runId, d.hostSessionId, JSON.stringify(d.outcome), d.fingerprint, d.deliveredTaskId, d.acceptedAtMs]);
+        });
+        return fenced.held;
+    }
+    async get(token) {
+        const { rows } = await this.claims.db.query(this.q(`SELECT token, run_id, host_session_id, ${jsonColumnText("tidb", "outcome")}, fingerprint, delivered_task_id, accepted_at_ms FROM workflow_park_decision WHERE token = ?`, `SELECT token, run_id, host_session_id, ${jsonColumnText("pg", "outcome")}, fingerprint, delivered_task_id, accepted_at_ms FROM workflow_park_decision WHERE token = $1`), [token]);
+        const r = rows[0];
+        return r ? rowToParkDecision(r) : null;
+    }
+    async listByHostSession(hostSessionId) {
+        const { rows } = await this.claims.db.query(this.q(`SELECT token, run_id, host_session_id, ${jsonColumnText("tidb", "outcome")}, fingerprint, delivered_task_id, accepted_at_ms FROM workflow_park_decision WHERE host_session_id = ?`, `SELECT token, run_id, host_session_id, ${jsonColumnText("pg", "outcome")}, fingerprint, delivered_task_id, accepted_at_ms FROM workflow_park_decision WHERE host_session_id = $1`), [hostSessionId]);
+        return rows.map(rowToParkDecision);
+    }
+}
+const PARK_DECISION_REPLACED_COLUMNS = ["run_id", "host_session_id", "outcome", "fingerprint", "delivered_task_id", "accepted_at_ms"];
+function rowToParkDecision(r) {
+    const token = String(r.token);
+    return {
+        token,
+        runId: String(r.run_id),
+        hostSessionId: String(r.host_session_id),
+        outcome: readParkDecisionOutcomeColumn(r.outcome, `for run ${String(r.run_id)}`),
+        fingerprint: String(r.fingerprint),
+        deliveredTaskId: String(r.delivered_task_id),
+        acceptedAtMs: Number(r.accepted_at_ms),
+    };
+}
 export class TiDBWorkflowRunStore extends SqlWorkflowRunStore {
     constructor(pool, onWarn) {
         super(mysqlDriver(pool), onWarn);

package/dist/posture-source.d.ts

@@ -1,5 +1,5 @@
 /**
- * S-167 → S-178 —— **一个部署级旋钮的值是谁定的**,四词闭集 + 一句运维指路。
+ * S-167 → S-178 → S-1492 —— **一个部署级旋钮的值是谁定的**,五词闭集 + 一句运维指路。
  *
  * ## 为什么是一个共享件而不是每键一份
  *
@@ -10,7 +10,10 @@
  * ——四词表抄第二遍的那天,两份表会在加词时分家,而「这个值是谁定的」在运维面上是个是非题,不能有两个答案。
  *
  * ## 优先序(与 `config.ts` 的 `postureOn` 同形)
- * `env 显式` > `center 发布` > `posture 派生` > `引擎/服务端默认`。
+ * `env 显式` > `center 发布` > `车道声明` > `posture 派生` > `引擎/服务端默认`。
+ * `lane`(S-1492,[ref])= **执行车道的契约行替运维声明了这个旋钮的缺省**(目前只有 `READ_FACE`:隔离型车道的读面缺省 `open`,声明在 `execution-lane-caps.ts`)。
+ * 它是出处,不是表态:运维从没写过这个键,所以与 `posture` 一样不算「有人要求过」({@link isExplicitPosture});比 `posture` 优先,因为车道声明比整机 posture 更具体
+ * (同一台单机上 `e2b` 沙箱里的读面缺省 `open`,理由是沙箱边界而不是「一个可信主人」)。
  *
  * ## 定界
  * 本模块只说**来源**。值本身、以及**两条键专属臂**的句子——「这台机器凭什么派生出这个值」
@@ -24,9 +27,9 @@
  * `read-face` 重启片也不再为它签理由)——运维照那句话去滚动重启一片 fleet,重启的是一个已经生效的变更。
  * 生效时机是**键**的事实,不是四词表的属性,所以它跟 `postureMeaning` 一样归键。
  */
-/** 旋钮取值来源的闭集词表(顺序 = 优先序)。 */
-export declare const POSTURE_SOURCE_WORDS: readonly ["env", "center", "posture", "engine-default"];
-/** 一个旋钮的取值来源(闭集四词)。加词 ⇒ {@link postureSourceNote} 的穷举 switch 编译红。 */
+/** 旋钮取值来源的闭集词表(顺序 = 优先序;五词,S-1492 起多 `lane`)。 */
+export declare const POSTURE_SOURCE_WORDS: readonly ["env", "center", "lane", "posture", "engine-default"];
+/** 一个旋钮的取值来源(闭集五词)。加词 ⇒ {@link postureSourceNote} 的穷举 switch 编译红。 */
 export type PostureSource = (typeof POSTURE_SOURCE_WORDS)[number];
 /** 一个旋钮报出「我是谁定的」所需要的三件事。 */
 export interface PostureKnobFacts {
@@ -43,15 +46,20 @@ export interface PostureKnobFacts {
      * 它们)—— 一句共享的硬编码必然对其中一类说谎。
      */
     readonly centerMeaning: string;
+    /**
+     * `lane` 那一臂**专属**的一句话(S-1492):执行车道的契约行为什么替这个旋钮声明了缺省、这一声明的风险是什么、怎么钉回。只在 `source === "lane"` 时被读到。
+     * 与 `centerMeaning` 同理由归键:没有 lane 腿的旋钮(今天除 `READ_FACE` 外都是)写一句「本键没有 lane 腿」,比一句会骗人的通用话诚实。
+     */
+    readonly laneMeaning: string;
     /**
      * `posture` 那一臂**专属**的一句话:这台机器为什么派生出了这个值,以及怎么把它钉回去。
      * 只在 `source === "posture"` 时被读到 —— 别的臂的句子是通用的(见 {@link postureSourceNote})。
      */
     readonly postureMeaning: string;
 }
-/** 运维指路句 —— **穷举 switch,无缺省臂**:四词闭集加一个成员这里就编译红。
- *  两条**通用**臂(`env` / `engine-default`)的句子在这里写死并点名旋钮;两条**键专属**臂
- *  (`center` / `posture`)原样取键给的那句话(理由见 {@link PostureKnobFacts} 的两个字段注)。 */
+/** 运维指路句 —— **穷举 switch,无缺省臂**:五词闭集加一个成员这里就编译红。
+ *  两条**通用**臂(`env` / `engine-default`)的句子在这里写死并点名旋钮;三条**键专属**臂
+ *  (`center` / `lane` / `posture`)原样取键给的那句话(理由见 {@link PostureKnobFacts} 的三个字段注)。 */
 export declare function postureSourceNote(facts: PostureKnobFacts): string;
 /**
  * 这个值是**运维显式表态**的吗?
@@ -62,8 +70,8 @@ export declare function postureSourceNote(facts: PostureKnobFacts): string;
  * **结构上没有 durable 门**的腿在每次 boot 打一条补偿 warn,而它其实正处在「零门意图的既定姿势」里。
  * 这与 S-167 头注①记的是**同一形**病(用一个会被 posture 铸出来的量当「有人表态过」的代理)。
  *
- * ⇒ 判据落到**来源**上,穷举 switch(四词闭集加员即编译红):`env`(这台机器的运维写下的)与 `center`
- * (组织发布的)是表态;`posture`(姿态派生)与 `engine-default`(内建缺省)都**不是**「有人要求过」。
+ * ⇒ 判据落到**来源**上,穷举 switch(五词闭集加员即编译红):`env`(这台机器的运维写下的)与 `center`
+ * (组织发布的)是表态;`lane`(车道契约行声明的缺省)、`posture`(姿态派生)与 `engine-default`(内建缺省)都**不是**「有人要求过」。
  */
 export declare function isExplicitPosture(source: PostureSource): boolean;
 /** operator 诊断面的一行读数:值 + 来源 + 指路句。三个 S-178 旋钮与 S-167 的 readFace 同形。 */

package/dist/posture-source.js

@@ -1,10 +1,12 @@
-export const POSTURE_SOURCE_WORDS = ["env", "center", "posture", "engine-default"];
+export const POSTURE_SOURCE_WORDS = ["env", "center", "lane", "posture", "engine-default"];
 export function postureSourceNote(facts) {
     switch (facts.source) {
         case "env":
             return `pinned by this machine's ${facts.knob} env var (deployment sovereignty — it wins over any published value for this key)`;
         case "center":
             return facts.centerMeaning;
+        case "lane":
+            return facts.laneMeaning;
         case "posture":
             return facts.postureMeaning;
         case "engine-default":
@@ -16,6 +18,7 @@ export function isExplicitPosture(source) {
         case "env":
         case "center":
             return true;
+        case "lane":
         case "posture":
         case "engine-default":
             return false;

package/dist/project-identity.d.ts

@@ -1,4 +1,5 @@
-import type { MemoryProjectKey, MemoryProjectKeyAbsentReason } from "@sema-agent/core";
+import { type MemoryProjectKey, type MemoryProjectKeyAbsentReason } from "@sema-agent/core";
+import { type ProjectLayerIdentity } from "./project-layer-key.js";
 /** core 的项目身份声明席(`TaskSpec.memory.projectKey`)—— core 包根导出的型,原样转出(本仓调用方从这里取)。 */
 export type { MemoryProjectKey };
 /** 本仓会说的缺席词。`not_git` 刻意排除:裁 D 起非 git 目录按目录键控,不是缺席(core 闭集仍收它,本仓不铸)。 */
@@ -16,12 +17,50 @@ export type ProjectIdentity = {
  * 一次向上走,规则三条按优先序:最近的 `.git`(① ② ③)> 链上最近的裸仓布局(④ bare)> 非 git 按目录键控(④)。
  */
 export declare function resolveProjectIdentity(taskRoot: string): ProjectIdentity;
-/** 本仓**唯一**的 `repo:` 键铸点([ref] ①:`repo:` + sha256 hex 前 24;`root` 为 realpath 字符串,不加尾斜杠、不折大小写)。 */
+/**
+ * 退役 `repo:` 键的**唯一**铸点([ref] ①:`repo:` + sha256 hex 前 24;`root` 为 realpath 字符串,不加尾斜杠、不折大小写)。
+ * S-640 起它只是一次性迁移的来源(`memory-project-layer.ts` 把这一层的条目折进新键;窗见 `plugins/one-time-migrations.ts` 登记表)。
+ */
 export declare function mintRepoScopeKey(projectRoot: string): string;
+/** 这把键是不是本仓铸的项目键族(现行 `userrepo:` 或退役的 `repo:`)—— 运维不许把它们点名成全局层 / 同步层。 */
+export declare function isServerMintedProjectKey(key: string): boolean;
+/**
+ * 起服判据:这个全局层(或同步层)能不能拥有项目层 —— 不是本仓铸的族,且属主段编码得出来(core 段编码 ≤ 64)。不能 ⇒ 抛一句点名出路的配置错。
+ * 调用方:`config.ts` 记忆域(单用户 + 记忆引擎开着时问 `MEMORY_SCOPE`;开同步时问同步层)。
+ */
+export declare function assertProjectLayerOwnable(scope: string, envName: string): void;
+/**
+ * 远端 URL 归一(`r` 档的输入)—— 同一个仓的不同写法收成同一串,两个仓**不许**并成一串,凭据不进串:
+ *  · scp 形 `[user@]host:path`(主机至少两个字符 —— 单字母是 Windows 盘符)与 scheme 形 `scheme://[userinfo@]host[:port]/path` ⇒ `host[:port]/path`
+ *    (去 userinfo;主机小写;端口是该 scheme 的缺省值才去掉;路径大小写保留:不同托管对大小写的读法不同,折了会把两个仓合成一个);
+ *  · 本地路径远端(`file://`、绝对 / 相对路径)⇒ `undefined`:它不是跨设备身份(相对路径还取决于 checkout 在哪),调用方落本 checkout 的 `p` 档;
+ *  · 路径去首尾 `/`、去尾 `.git`、连续 `/` 收成一个;主机为空 ⇒ `undefined`。
+ */
+export declare function normalizeGitRemoteUrl(url: string): string | undefined;
+/**
+ * 任务根 → 项目层身份(S-640):当前档(`r` 优先,没有 origin 退 `p`)+ 本 checkout 的低档(`r` 档时 = 它的 `p` 档)。
+ * 缺席形与 {@link resolveProjectIdentity} 同;git 配置在而读不了 ⇒ `unreadable`。
+ */
+export declare function projectLayerIdentityOf(taskRoot: string): {
+    readonly root: string;
+    readonly identity: ProjectLayerIdentity;
+    readonly lowerTiers: readonly ProjectLayerIdentity[];
+} | {
+    readonly absent: ProjectIdentityAbsentReason;
+};
+/** 一个任务的项目层:core 声明席 + 本 checkout 要折进来的低档 / 退役层(按序,`memory-project-layer.ts` 折)。 */
+export interface ProjectLayerOfTask {
+    readonly key: MemoryProjectKey;
+    readonly foldFrom: readonly string[];
+}
 /**
- * 任务根 → core 声明席 `TaskSpec.memory.projectKey`。
- * `taskRoot === undefined` = 调用方**此刻不知道**任务根在本机哪里(根在沙箱/设备盘上;或 host 车道会话没登记 cwd、
- * 手落在 factory 现铸的临时目录)⇒ `unreadable` —— 「我看不到」,不是「这里没有项目」。
+ * 任务根 → 项目层(S-640:`userrepo:<属主段>/<档>.<摘要>`,属主 = `owner`,调用方由 `projectLayerOwnerOf(全局层)` 求得)。
+ * `foldFrom` = 同一 checkout 能推出的旧层:退役 `repo:<同一路径哈希>`(一次性迁移,窗见 `plugins/one-time-migrations.ts` 登记表 M25)
+ * + 当前档是 `r` 时它的 `p` 档(常设律)。
+ * `taskRoot === undefined` = 调用方**此刻不知道**任务根在本机哪里(根在沙箱/设备盘上;或 host 车道会话没登记 cwd、手落在 factory 现铸的
+ * 临时目录)⇒ `unreadable` —— 「我看不到」,不是「这里没有项目」。
  */
-export declare function projectKeyForTaskRoot(taskRoot: string | undefined): MemoryProjectKey;
+export declare function projectLayerForTaskRoot(taskRoot: string | undefined, owner: string): ProjectLayerOfTask;
+/** {@link projectLayerForTaskRoot} 的声明席投影(core `TaskSpec.memory.projectKey`)。 */
+export declare function projectKeyForTaskRoot(taskRoot: string | undefined, owner: string): MemoryProjectKey;
 //# sourceMappingURL=project-identity.d.ts.map