@sema-agent/server 7.150.0 → 7.152.0

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

@@ -60,9 +60,9 @@ import { summarizeWorkflowRun, type CheckpointToken, type WorkflowRunStore } fro
 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 HolderFenceVerdict, type RecordFenced, type WorkflowParkDecision, type WorkflowParkDecisionStore } from "../orchestration/workflow-park-decision.js";
 import type { SqlRunStore } from "./run-store-sql.js";
-import { type SqlDialect, type SqlDriver, type SqlExec } from "./sql-driver.js";
+import { type SqlDialect, type SqlDriver, type SqlExec, type SqlTxConn } 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
  *  ~6 MiB txn-entry limit would otherwise throw the (best-effort) progress write into the workflow loop.
@@ -126,6 +126,14 @@ export declare class SqlWorkflowRunStore implements WorkflowRunStore {
     private q;
     put(id: string, run: WorkflowRun): Promise<void>;
     get(id: string): Promise<WorkflowRun | null>;
+    /**
+     * **记录栅栏(SQL 形)**:一个事务 —— 锁读这条 run 的记录行且它读作 `running`(`workflow_run … FOR UPDATE`,行体经本店唯一列读者 {@link readRunColumn} 解、
+     * `rev` 列覆盖),读到 ⇒ `fn` 在**同一个事务连接**上跑(收锁住的那份记录);没读到(终态 / 不在)⇒ `fn` 不调、答 `{ running: false }`。提交即放锁;`fn` 抛或提交失败 ⇒ 整只抛。
+     * 引擎的记录写是同一行的 CAS `UPDATE`({@link update}),notify 门的收养翻转同一条 ⇒ 与本段在这一行锁上串行:本段先拿锁 ⇒ 段里落的写先于终态提交;
+     * 终态先提交 ⇒ 本段读不到 `running`。决定行的写就落在这里(契约属主 = `orchestration/workflow-park-decision.ts` 文件头)。
+     * 取锁序 = `workflow_run` → `workflow_park_decision`(段里只碰这两张表;认领栅栏那一形先锁 `task_run` / `task_active` 再碰 `workflow_park_decision`,两序不成环)。
+     */
+    whileRunning<T>(id: string, fn: (tx: SqlTxConn, run: WorkflowRun) => Promise<T>): Promise<RecordFenced<T>>;
     update(id: string, scope: string, run: WorkflowRun, expect?: {
         rev: number;
     }): Promise<boolean>;
@@ -212,24 +220,34 @@ export declare class SqlWorkflowAgentSessionIndex implements WorkflowAgentSessio
 /**
  * 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`)—— 决定行、认领、读写同一只池,池只有这一处来源。
+ * 写在两只栅栏之一的事务里:记录栅栏(`records`:{@link SqlWorkflowRunStore.whileRunning} 交出的那条事务连接 —— 栅栏攥着 `workflow_run` 行锁直到提交)
+ * 或认领栅栏(`claims`:`SqlRunStore.whileHoldingClaim` 交出的那条事务连接 —— 攥着 run 行与认领行的锁直到提交);读走 run 店的池(`claims.db`)。
+ * 两只栅栏、决定行、读写同一只池(后端交出的三只店同出一只池)。删除只有 run 收割的级联({@link SqlWorkflowRunStore.reap})。
  *
  * ── 方言差,保持显式 ──────────────────────────────────────────────────────────────────────────
  *   - `?` 占位 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` 只是记下的值。
+ *   - 认领栅栏下的整行 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` 只是记下的值。
+ *   - 记录栅栏下的「没有才插」(先受理者立):TiDB `INSERT … ON DUPLICATE KEY UPDATE token = token` vs PG `INSERT … ON CONFLICT (token) DO NOTHING`;
+ *     之后**锁定读**行上的指纹(`SELECT … FOR UPDATE`)判立没立 —— TiDB 悲观事务里的普通读走事务起点的快照,一只等锁等过对方提交的事务用普通读会读不到
+ *     对方刚落的行;锁定读读最新提交。PG READ COMMITTED 每句新快照,锁定读同样成立。收场转交的条件读同此(认领栅栏里锁定读指纹再写)。
  *   - `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);
+    readonly records: SqlWorkflowRunStore;
+    constructor(claims: SqlRunStore, records: SqlWorkflowRunStore);
     private q;
-    record(d: WorkflowParkDecision): Promise<boolean>;
+    /** 事务里锁定读这张卡行上的指纹(没有行 ⇒ `undefined`)。 */
+    private lockedFingerprint;
+    record(d: WorkflowParkDecision, condition?: {
+        readonly expect: string;
+    }): Promise<boolean>;
+    recordForRunningHolder(d: WorkflowParkDecision, request: {
+        readonly restated: boolean;
+    }): Promise<HolderFenceVerdict>;
     get(token: CheckpointToken): Promise<WorkflowParkDecision | null>;
     listByHostSession(hostSessionId: string): Promise<WorkflowParkDecision[]>;
 }

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

@@ -2,10 +2,12 @@ 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 { holderFenceAdmits, 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";
+import { storeBoundaryFault } from "../terminal.js";
+import { sealStoreClass } from "./store-boundary.js";
 export const MAX_RUN_BLOB_BYTES = 4 * 1024 * 1024;
 const SLIM_HEADER_MAX = 200;
 const onWarnType = (msg, meta) => void [msg, meta];
@@ -81,6 +83,37 @@ export class SqlWorkflowRunStore {
         run.rev = Number(r.rev);
         return run;
     }
+    async whileRunning(id, fn) {
+        const conn = await this.db.connect();
+        try {
+            await conn.begin();
+            try {
+                const { rows } = await conn.query(this.q(`SELECT ${jsonColumnText("mysql", "run")}, rev FROM workflow_run WHERE id = ? AND status = 'running' FOR UPDATE`, `SELECT ${jsonColumnText("pg", "run")}, rev FROM workflow_run WHERE id = $1 AND status = 'running' FOR UPDATE`), [id]);
+                const r = rows[0];
+                let fenced = { running: false };
+                if (r !== undefined) {
+                    const run = readRunColumn(r.run, id);
+                    run.rev = Number(r.rev);
+                    fenced = { running: true, value: await fn(conn, run) };
+                }
+                await conn.commit();
+                return fenced;
+            }
+            catch (err) {
+                try {
+                    await conn.rollback();
+                }
+                catch (rollbackErr) {
+                    const rollbackFault = storeBoundaryFault(rollbackErr, "sql-workflow-run-store.whileRunning");
+                    throw new Error(`workflow record fence on ${id}: the segment failed and its rollback failed too (${rollbackFault instanceof Error ? rollbackFault.message : String(rollbackFault)})`, { cause: err });
+                }
+                throw err;
+            }
+        }
+        finally {
+            conn.release();
+        }
+    }
     async update(id, scope, run, expect) {
         run = withRedactedError(run);
         let blob = JSON.stringify({ ...run, id, scope });
@@ -166,6 +199,7 @@ export class SqlWorkflowRunStore {
         return res.affected;
     }
 }
+sealStoreClass(SqlWorkflowRunStore, "sql-workflow-run-store", { put: "exit", get: "exit", update: "exit", whileRunning: "exit", listByScope: "exit", reapAllScopes: "exit", reap: "exit" });
 const KIND_SERVED = "served";
 const KIND_PURGE = "purge";
 export async function writeInboxPurgeFenceOn(exec, dialect, sessionId, purgedOwner, now) {
@@ -264,6 +298,7 @@ export class SqlWorkflowCompletionInbox {
         await this.db.query(this.q("DELETE FROM workflow_completion_inbox WHERE session_id = ? AND run_id <> ? AND REGEXP_REPLACE(run_id, '#[0-9]+$', '') = ?", "DELETE FROM workflow_completion_inbox WHERE session_id = $1 AND run_id <> $2 AND regexp_replace(run_id, '#[0-9]+$', '') = $3"), [sessionId, runId, runId]);
     }
 }
+sealStoreClass(SqlWorkflowCompletionInbox, "sql-workflow-completion-inbox", { enqueue: "exit", pending: "exit", ack: "exit", purge: "exit", markTerminalServed: "exit" });
 export class SqlWorkflowNotifyJournalStore {
     db;
     constructor(db) {
@@ -309,6 +344,7 @@ export class SqlWorkflowNotifyJournalStore {
         };
     }
 }
+sealStoreClass(SqlWorkflowNotifyJournalStore, "sql-workflow-notify-journal-store", { record: "exit", ack: "exit", listPending: "exit", reapAcked: "exit", get: "exit" });
 export class SqlWorkflowAgentSessionIndex {
     db;
     constructor(db) {
@@ -328,6 +364,7 @@ export class SqlWorkflowAgentSessionIndex {
         return rows.map((r) => ({ sessionId: String(r.session_id), runId: String(r.run_id), agentKey: String(r.agent_key), scope: String(r.scope) }));
     }
 }
+sealStoreClass(SqlWorkflowAgentSessionIndex, "sql-workflow-agent-session-index", { ensurePointers: "exit", listByAgentSession: "exit" });
 function readParkDecisionOutcomeColumn(v, where) {
     try {
         return decodeJsonColumn(v, readWorkflowParkOutcome, `workflow_park_decision.outcome ${where}`);
@@ -338,19 +375,41 @@ function readParkDecisionOutcomeColumn(v, where) {
 }
 export class SqlWorkflowParkDecisionStore {
     claims;
-    constructor(claims) {
+    records;
+    constructor(claims, records) {
         this.claims = claims;
+        this.records = records;
     }
     q(mysql, pg) {
         return this.claims.db.dialect === "mysql" ? mysql : pg;
     }
-    async record(d) {
+    async lockedFingerprint(tx, token) {
+        const { rows } = await tx.query(this.q("SELECT fingerprint FROM workflow_park_decision WHERE token = ? FOR UPDATE", "SELECT fingerprint FROM workflow_park_decision WHERE token = $1 FOR UPDATE"), [token]);
+        const r = rows[0];
+        return r === undefined ? undefined : String(r.fingerprint);
+    }
+    async record(d, condition) {
         const fenced = await this.claims.whileHoldingClaim(d.hostSessionId, d.deliveredTaskId, async (tx) => {
+            if (condition !== undefined && (await this.lockedFingerprint(tx, d.token)) !== condition.expect)
+                return false;
             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 true;
+        });
+        return fenced.held && fenced.value;
+    }
+    async recordForRunningHolder(d, request) {
+        const fenced = await this.records.whileRunning(d.runId, async (tx, run) => {
+            const admits = holderFenceAdmits(run, d, request.restated);
+            if (admits !== "land")
+                return admits;
+            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 token = token`, `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 NOTHING`), [d.token, d.runId, d.hostSessionId, JSON.stringify(d.outcome), d.fingerprint, d.deliveredTaskId, d.acceptedAtMs]);
+            return (await this.lockedFingerprint(tx, d.token)) === d.fingerprint ? "stands" : "other_decision";
         });
-        return fenced.held;
+        return fenced.running ? fenced.value : "not_running";
     }
     async get(token) {
         const { rows } = await this.claims.db.query(this.q(`SELECT token, run_id, host_session_id, ${jsonColumnText("mysql", "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]);
@@ -362,6 +421,7 @@ export class SqlWorkflowParkDecisionStore {
         return rows.map(rowToParkDecision);
     }
 }
+sealStoreClass(SqlWorkflowParkDecisionStore, "sql-workflow-park-decision-store", { record: "exit", recordForRunningHolder: "exit", get: "exit", listByHostSession: "exit" });
 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);

package/dist/plugins/workspace-custody.d.ts

@@ -8,13 +8,14 @@
  *    (停驻腿的环境引擎还拿着,续跑腿拿到的就是它);那一只正在收场 ⇒ 等它的收场落定再铸,它欠着的账交给新的这只;没有 ⇒ 铸一只入表。
  *    同一身份同一时刻只有一条腿(会话锁 + run 认领),交回同一只不会让两条腿同时用它。
  *  · **工作区的生命归持有它的环境,不归铸它的那一只**:表里每一只成员自己说它此刻持有哪只工作区;一只工作区能不能删 = 表里除问者之外还有没有成员持有它
- *    ({@link WorkspaceCustody.holder})—— 没有才删,有就把删交给最后放手的那一只。
+ *    ({@link WorkspaceCustody.holder})—— 没有才删,有就把删交给最后放手的那一只(host 车道另问一句「此刻谁在里面」,见下)。
  *
  * ## 两条车道怎么读同一张表
  *  · local-docker:工作区 = 身份派生名的那只容器;一只身份同一时刻只有一只没收场的成员(上面的交回律),容器名又由身份派生 ⇒ 不可能有第二个持有者,成员收场即删
  *    (读 {@link WorkspaceCustody.envOf};欠账 = 删除没证实的那只容器,交给同一身份的下一只)。
- *  · host:工作区 = 本服务铸的临时根;委派子代按父的工作目录落根 ⇒ 子代的环境与父的共持那只根(铸时问 {@link WorkspaceCustody.holder}「谁持有包含这一处的根」),
- *    收场放手时问同一只「还有谁持有它」—— 父收场时子代还停驻在里面 ⇒ 父不删,子代最后一条腿收场时删。
+ *  · host:工作区 = 本服务铸的临时根;委派子代按父的工作目录落根 ⇒ 子代的环境与父的共持那只根(铸时问 {@link WorkspaceCustody.holder}「谁持有包含这一处的根」,
+ *    只能多记持有者)。删只在最后一只持有者放手那一拍、同一同步段里问同一只 `holder`「还有谁持有它,或此刻还没离场、工作目录读得出地在它里面」之后发生 ——
+ *    有 ⇒ 不删(在里面的那一只当场接过删除);读不出 ⇒ 不删不交接,留给退出边界;没人才删。父收场时子代还停驻在里面 ⇒ 父不删,子代最后一条腿收场时再判。
  *
  * ## 出表
  * 成员收场落定、什么都不欠、什么都不持有({@link CustodyMember.settled})⇒ 出表;没收场的成员(停驻腿的环境)一直在表里(停驻中被店层取消 / 过期的,引擎不销毁它,它持有的工作区

package/dist/plugins/workspace-fill.d.ts

@@ -1,4 +1,5 @@
-import { RemoteExecutionError, type ExecutionEnvFactoryContext } from "@sema-agent/core";
+import { type ExecutionEnvFactoryContext } from "@sema-agent/core";
+import { type ConnectRefusal } from "./remote-env-connect-seat.js";
 import type { Logger } from "../observability/logger.js";
 import { type TaskAttachmentStore } from "./task-attachment-store.js";
 /** 车道一次固定命令的读数(适配器自己的起动身份 —— 与引擎命令同一个执行用户;从不抛)。 */
@@ -29,14 +30,10 @@ export interface WorkspaceChannel {
 }
 /** 恢复点交出的工作区从哪来:`minted` = 车道刚铸出的新工作区(没有可恢复的树 —— 含恢复点指的归档不在:`latest` 悬空、停驻快照的归档不在);`restored` = 恢复出来的(空间 `latest` / 停驻快照的树真回来了)。 */
 export type WorkspaceOrigin = "minted" | "restored";
-/** 一次填充的结局。`standing` = 这只执行环境此后每一次恢复点都会得到同一个答(适配器把它记成这只环境的拒,不再建机器)。 */
+/** 一次填充的结局。拒的那一臂是一只建连的拒:`standing` = 这只执行环境此后每一次恢复点都会得到同一个答(适配器的建连座记住它,不再建机器)。 */
 export type FillOutcome = {
     readonly ok: true;
-} | {
-    readonly ok: false;
-    readonly error: RemoteExecutionError;
-    readonly standing: boolean;
-};
+} | ConnectRefusal;
 /** 恢复点的填充座(按 run 由工厂装配交给适配器;适配器只在恢复点调它、只说工作区从哪来,不判内容)。 */
 export interface WorkspaceFill {
     /** 往恢复点即将交出的工作区(根 = `root`,适配器的工作根;来处 = `origin`)里放内容。 */

package/dist/plugins/workspace-fill.js

@@ -1,12 +1,13 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { RemoteExecutionError } from "@sema-agent/core";
+import { connectRefusal } from "./remote-env-connect-seat.js";
 import { readProjectBundle } from "../project-bundle.js";
 import { attachmentBytesOf, attachmentPlacementsOf, seedOfSession } from "./task-attachment-store.js";
 import { shellQuote } from "./remote-shell.js";
 const FILLED = { ok: true };
 function refused(message, standing = false) {
-    return { ok: false, error: new RemoteExecutionError("connect_failed", message), standing };
+    return standing ? connectRefusal("workspace_fill_refused", message) : { ok: false, error: new RemoteExecutionError("connect_failed", message), standing: false };
 }
 function errText(e) {
     return e instanceof Error ? e.message : String(e);

package/dist/plugins/write-behind-counter.js

@@ -1,4 +1,5 @@
 import { alignedWindow, retryAfterSecUntil } from "../observability/cost-quota.js";
+import { sealStoreClass } from "./store-boundary.js";
 const SEP = "\u0000";
 export const DEFAULT_COUNTER_QUERY_TIMEOUT_MS = 30_000;
 export class SqlWriteBehindCounter {
@@ -173,6 +174,10 @@ export class SqlWriteBehindCounter {
         this.windowMs = windowMs;
     }
 }
+sealStoreClass(SqlWriteBehindCounter, "sql-write-behind-counter", {
+    window: "exit", bucket: "exit", usedIn: "exit", used: "exit", addLocal: "exit", retryAfterSec: "exit", flush: "exit", refresh: "exit", reap: "exit",
+    startRefresh: "exit", stop: "exit", refreshRunning: "exit", setWindowMs: "exit",
+});
 export class WriteBehindCounter extends SqlWriteBehindCounter {
     constructor(pool, t, windowMs, now, onDegraded, queryTimeoutMs) {
         super("mysql", pool, t, windowMs, now, onDegraded, queryTimeoutMs);

package/dist/project-context.d.ts

@@ -37,8 +37,6 @@ export interface ProjectContextDecision {
     readonly context: ProjectContext | undefined;
     readonly withheldPathItems: number;
 }
-/** 一只登记对这位观者可见吗(读面与继承同调的唯一判):全舰队视域看全部;否则只看 `registeredBy` 恰是自己的。看不见与不存在同答。 */
-export declare function projectVisible(registration: Pick<ProjectRegistration, "registeredBy">, viewer: ListFilter): boolean;
 /**
  * 项目简报的唯一铸点(纯串;各段缺席不出,全缺席 ⇒ 无简报)。只读 {@link PROJECT_BRIEF_FIELDS};路径两段只在 `pathsHonored` 时出,且只列名字 ——
  * `file` 条目未附上,段名写明「相关时去读」。首行点名来源与项目 id(不带 `displayName`:身份字段不进提示)。

package/dist/project-context.js

@@ -1,11 +1,9 @@
 import { PROJECT_ID_REGEX } from "@sema-agent/core";
 import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
+import { visibleProjectOf } from "./project-registry.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS } from "./task-settings.js";
 export const PROJECT_BRIEF_FIELDS = ["goal", "notes", "contextItems"];
 export const PROJECT_CONTENT_ATTESTATION_FIELD = "contentAttestedAt";
-export function projectVisible(registration, viewer) {
-    return viewer.fleetWide || registration.registeredBy === viewer.gateOwner;
-}
 export function buildProjectBrief(projectId, registration, pathsHonored) {
     const sections = [];
     if (registration.goal !== undefined && registration.goal.length > 0)
@@ -29,11 +27,9 @@ export function buildProjectBrief(projectId, registration, pathsHonored) {
     return [`# Project context (from this deployment's project registry; project ${projectId})`, ...sections].join("\n\n");
 }
 export function projectContextOf(input) {
-    const { projectId, registry, viewer } = input;
-    if (projectId === undefined || registry === undefined || viewer === undefined)
-        return { context: undefined, withheldPathItems: 0 };
-    const registration = Object.hasOwn(registry, projectId) ? registry[projectId] : undefined;
-    if (registration === undefined || !projectVisible(registration, viewer))
+    const { projectId } = input;
+    const registration = visibleProjectOf(input.registry, projectId, input.viewer);
+    if (projectId === undefined || registration === undefined)
         return { context: undefined, withheldPathItems: 0 };
     if (registration[PROJECT_CONTENT_ATTESTATION_FIELD] === undefined)
         return { context: undefined, withheldPathItems: 0 };

package/dist/project-registry.d.ts

@@ -0,0 +1,46 @@
+import type { ProjectRegistration } from "@sema-agent/settings-schema";
+import type { ListFilter } from "./owner-faces.js";
+/** 一张登记簿(键 = 小写规范 UUID;值至少带可见性的属主键)。缺席 = 本部署没有登记簿(`capability-facts.ts` `projectRegistry` 答 no)。 */
+export type ProjectRegistryTable<R> = Readonly<Record<string, R>> | undefined;
+/**
+ * 谓词读的观者事实(列表面视域 {@link ListFilter} 里与登记可见性有关的两格)。`gateOwner` 只拿来与登记的 `registeredBy`(settings-schema 的纯串)逐字节比,
+ * 所以这里收纯串:新提交腿交来的是读面推导出的主体(品牌串,天然是串),续跑腿交来的是冻结时落成字节的那一串(不重铸品牌 —— 它不进任何属主门,只比这一格)。
+ */
+export interface ProjectViewer {
+    readonly fleetWide: ListFilter["fleetWide"];
+    readonly gateOwner: string | null;
+}
+/** 一只登记对这位观者可见吗(唯一判):全舰队视域看全部;否则只看 `registeredBy` 恰是自己的(无身份的观者 `gateOwner = null` 恒看不见)。 */
+export declare function projectVisibleTo(viewer: ProjectViewer, registration: Pick<ProjectRegistration, "registeredBy">): boolean;
+/** 这位观者看得见的那只登记(唯一取法):未登记 / 看不见 / 没有观者 / 本部署没有登记簿 ⇒ 同答 `undefined`。按 id 只认自有键。 */
+export declare function visibleProjectOf<R extends Pick<ProjectRegistration, "registeredBy">>(registry: ProjectRegistryTable<R>, projectId: string | undefined, viewer: ProjectViewer | undefined): R | undefined;
+/** 一条 run 的登记簿默认读层种子:种子项目(这次提交带的、提交者看得见的那只)+ 判出它的那一位观者。随 run 冻结(续跑重建输入 `CheckpointCtx.memorySeed`)。 */
+export interface MemorySeed {
+    readonly projectId: string;
+    readonly viewer: ProjectViewer;
+}
+/**
+ * 新提交腿的种子判(一条 run 一次):这次**提交**没带项目 ⇒ `undefined`(没什么可判);带了而对提交者可见 ⇒ 种子;带了而判不出(未登记 / 看不见 / 没有观者 / 没有登记簿)
+ * ⇒ `null`(判过,无 —— 冻结下来,续跑腿据它与「停驻在种子判出现之前」分开)。
+ */
+export declare function memorySeedOf(registry: ProjectRegistryTable<Pick<ProjectRegistration, "registeredBy">>, submittedProjectId: string | undefined, viewer: ProjectViewer | undefined): MemorySeed | null | undefined;
+/** 种子的词(两腿同调):种子的那一位观者此刻仍看得见的那只登记声明的 `defaultScopes`;没有种子 / 判过无 / 登记已不在 / 不再对他可见 ⇒ 缺席。 */
+export declare function memorySeedScopesOf(registry: ProjectRegistryTable<Pick<ProjectRegistration, "registeredBy" | "defaultScopes">>, seed: MemorySeed | null | undefined): string[] | undefined;
+/** 续跑重建输入里冻结的种子的读数:缺席(提交没带项目 / 本格出现之前写下的行)· 判过无(`null`)· 读得出 · 形不对。 */
+export type FrozenMemorySeedReading = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "none";
+} | {
+    readonly kind: "ok";
+    readonly seed: MemorySeed;
+} | {
+    readonly kind: "malformed";
+};
+/**
+ * 冻结的种子的**唯一读法**(读者 = `http/resume-ctx-read.ts` 的续跑上下文读口,开封之后、任何续跑消费者之前)。服务端写下的形是闭集({@link memorySeedOf} 铸、经部署事实落盘):
+ * `null`(判过,无)或 `{ projectId, viewer: { fleetWide, gateOwner } }` —— `projectId` = 规范小写 UUID;`fleetWide` 布尔;`gateOwner` = 非空串(冻结时落成字节的主体,原样)或 `null`;
+ * 观者至少看得见点什么(`fleetWide` 或 `gateOwner` 在场 —— 看不见的提交不冻结种子)。别的形 ⇒ `malformed`(读口答坏体:续跑不按它挑种子)。
+ */
+export declare function frozenMemorySeedOf(stored: unknown): FrozenMemorySeedReading;
+//# sourceMappingURL=project-registry.d.ts.map

package/dist/project-registry.js

@@ -0,0 +1,44 @@
+import { PROJECT_ID_REGEX } from "@sema-agent/core";
+export function projectVisibleTo(viewer, registration) {
+    return viewer.fleetWide || registration.registeredBy === viewer.gateOwner;
+}
+export function visibleProjectOf(registry, projectId, viewer) {
+    if (registry === undefined || projectId === undefined || viewer === undefined || !Object.hasOwn(registry, projectId))
+        return undefined;
+    const registration = registry[projectId];
+    return registration !== undefined && projectVisibleTo(viewer, registration) ? registration : undefined;
+}
+export function memorySeedOf(registry, submittedProjectId, viewer) {
+    if (submittedProjectId === undefined)
+        return undefined;
+    if (viewer === undefined || visibleProjectOf(registry, submittedProjectId, viewer) === undefined)
+        return null;
+    return { projectId: submittedProjectId, viewer: { fleetWide: viewer.fleetWide, gateOwner: viewer.gateOwner } };
+}
+export function memorySeedScopesOf(registry, seed) {
+    return visibleProjectOf(registry, seed?.projectId, seed?.viewer)?.defaultScopes;
+}
+export function frozenMemorySeedOf(stored) {
+    if (stored === undefined)
+        return { kind: "absent" };
+    if (stored === null)
+        return { kind: "none" };
+    const own = (o, k) => (Object.hasOwn(o, k) ? o[k] : undefined);
+    const closedObject = (v, keys) => typeof v === "object" && v !== null && !Array.isArray(v) && Object.keys(v).every((k) => keys.includes(k));
+    if (!closedObject(stored, ["projectId", "viewer"]))
+        return { kind: "malformed" };
+    const projectId = own(stored, "projectId");
+    const viewer = own(stored, "viewer");
+    if (typeof projectId !== "string" || !PROJECT_ID_REGEX.test(projectId) || projectId !== projectId.toLowerCase())
+        return { kind: "malformed" };
+    if (!closedObject(viewer, ["fleetWide", "gateOwner"]))
+        return { kind: "malformed" };
+    const fleetWide = own(viewer, "fleetWide");
+    const gateOwner = own(viewer, "gateOwner");
+    if (typeof fleetWide !== "boolean" || (gateOwner !== null && (typeof gateOwner !== "string" || gateOwner.length === 0)))
+        return { kind: "malformed" };
+    if (!fleetWide && gateOwner === null)
+        return { kind: "malformed" };
+    return { kind: "ok", seed: { projectId, viewer: { fleetWide, gateOwner } } };
+}
+//# sourceMappingURL=project-registry.js.map

package/dist/question.d.ts

@@ -7,7 +7,8 @@ export interface QuestionFrame {
     type: "question" | "question_complete";
     questionId: string;
     /** "question" only: the model's structured questions, secret-redacted. UNTRUSTED-for-display (shell renders; never
-     *  re-feeds a model). Absent on an over-cap payload (the ask then reports unavailable — no frame is emitted at all). */
+     *  re-feeds a model). Always the WHOLE questions — no size cap (the question IS the decision; the same bytes already ride
+     *  `tool_start.args` uncapped). An unserializable payload emits no frame at all (the ask then reports unavailable). */
     questions?: AskQuestion[];
     /** "question_complete" only: whether the human answered (`answered`) or the ask closed without an answer
      *  (`unanswered` — window elapsed / abort / leg-exit sweep). Cosmetic dialog-dismiss. */

package/dist/question.js

@@ -1,11 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7 } from "@sema-agent/core";
-import { redactDeep } from "./trace/redact.js";
+import { humanFacingArgs } from "./human-facing-args.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { refusalBody } from "./http/refusal-body.js";
 import { keyAdmits, ownerCellOf, recoveredSubject } from "./owner-faces.js";
 import { createHitlOpenRace } from "./hitl-delivery.js";
-const MAX_QUESTIONS_BYTES = 16384;
 export const DEFAULT_QUESTION_THROTTLE = {
     maxConcurrentPerRun: 2,
     maxTotalPerRun: 20,
@@ -48,16 +47,9 @@ export function parseQuestionResponse(body) {
     }
     return { ok: true, value: { answers: out } };
 }
-function boundQuestions(questions) {
-    const redacted = redactDeep(questions);
-    try {
-        if (JSON.stringify(redacted).length > MAX_QUESTIONS_BYTES)
-            return undefined;
-    }
-    catch {
-        return undefined;
-    }
-    return redacted;
+function presentableQuestions(questions) {
+    const shown = humanFacingArgs(questions, "question");
+    return shown.kind === "whole" ? shown.value : undefined;
 }
 export class QuestionCoordinator {
     als = new AsyncLocalStorage();
@@ -90,7 +82,7 @@ export class QuestionCoordinator {
         const rc = this.countersFor(ctx.taskId);
         if (rc.inflight >= this.throttle.maxConcurrentPerRun || rc.total >= this.throttle.maxTotalPerRun)
             return UNAVAILABLE;
-        const questions = boundQuestions(req.questions);
+        const questions = presentableQuestions(req.questions);
         if (!questions)
             return UNAVAILABLE;
         const id = uuidv7();

package/dist/request-form.d.ts

@@ -16,7 +16,7 @@
 import type { IncomingMessage } from "node:http";
 import { type TaskHostPostureScope, type TaskWriteFaceInput } from "./hosted-posture.js";
 import { type ToolListSide } from "./rule-entry-list.js";
-import { type Scenario } from "./owner-brands.js";
+import { type Scenario, type Subject } from "./owner-brands.js";
 import type { PermissionMode } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import type { TaskRequestBody } from "./http/wire-types.js";
@@ -25,6 +25,11 @@ import type { TaskRequestBody } from "./http/wire-types.js";
  * (只在提交腿:读面没有体)。没带头 ⇒ 体原样(缺席 ⇒ 门走指派链)。
  */
 export declare function scenarioRequestedBy(headerScenario: Scenario | undefined, bodyScenario: unknown): unknown;
+/**
+ * {@link scenarioRequestedBy} 的主体形:场景头读**验过的主体**带的那一格(分派层判过在册,判决已记忆化),显式点名 = 体 `scenario`(提交受理门)或读面的 `?scenario=`。
+ * 受理门与读面(`GET /v1/capabilities/scenario` · `GET /v1/capabilities/mcp` · 两张会话面板)同调这一只 —— 同一只请求形在读面上点到的场景与提交时逐字同。
+ */
+export declare function scenarioRequestedBySubject(subject: Subject | undefined, named: unknown): unknown;
 /**
  * `inheritEnv:"all"` 的车道与射程两判(值形判在 `request-value-closure.ts` 的 `inheritEnvFieldIssue`,先于本函数):只有 host 车道消费这一位 ⇒ 别的车道 400 + 机读位
  * `reason: lane_not_host`;射程读写容纳面那一只谓词(`hosted-posture.ts` 腿④)⇒ 托管 422 `request.host_posture_refused`。`"scrub"` 是缺省,任何车道受理。

package/dist/request-form.js

@@ -16,6 +16,9 @@ export function scenarioRequestedBy(headerScenario, bodyScenario) {
     }
     return headerScenario;
 }
+export function scenarioRequestedBySubject(subject, named) {
+    return scenarioRequestedBy(subject === undefined ? undefined : partsOf(subject).scenario, named);
+}
 export function assertInheritEnvServed(body, config) {
     if (body.inheritEnv !== "all")
         return;
@@ -61,7 +64,7 @@ export function assertRequestFormBeforeMint(body, req, config) {
     assertToolListsReadable(body);
     assertRequestA2aEntries(snapshotRequestA2a(body.a2aPeers, { reread: false }));
     assertRequestImages(body.images);
-    scenarioRequestedBy(subject === undefined ? undefined : partsOf(subject).scenario, body.scenario);
+    scenarioRequestedBySubject(subject, body.scenario);
     assertAttachmentIdsShape(body.attachmentIds);
     assertWriteFaceAdmitted(effectivePermissionMode(body, parseTaskSettings(body.settings).settings), config);
     const ruleTables = ruleTablesRefusalWithoutTaskRoot(body, config);

package/dist/request-key-closure.js

@@ -29,7 +29,7 @@ const TASK_BODY_DECLARED_KEYS = [
     "outputSchema", "permissionMode", "projectId", "projectMemory", "promptLean", "reasoningEffort", "requireExistingSession",
     "resilience", "restoreFiles", "resumeAt", "resumeAtMode", "retainBackgroundProcesses", "retainSubagentSessions",
     "rewindFilesTo", "sandboxImageProfile", "scenario", "scratchpadDir", "selfOrchestration",
-    "sessionId", "settings", "skills", "suggestNextPrompts", "systemPrompt", "taskId", "toolMaterializeStrategy",
+    "sessionId", "sessionKind", "settings", "skills", "suggestNextPrompts", "systemPrompt", "taskId", "toolMaterializeStrategy",
     "userAttachments", "userInvokedSkills", "verify", "verifyRounds",
 ];
 const TASK_BODY_SCENARIO_KEYS = ["repo"];

package/dist/request-value-closure.d.ts

@@ -148,5 +148,9 @@ export interface InheritEnvFieldIssue {
  * 句子对两种坏值形是同一句(点名两词与「名单不是请求值」);`reason` 区分它们。
  */
 export declare function inheritEnvFieldIssue(raw: unknown): InheritEnvFieldIssue | null;
+/** 词表外的拒句(wire 可见、字节冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。 */
+export declare const SESSION_KIND_VALUE_MESSAGE: string;
+/** `sessionKind` 在场且不在闭集里 ⇒ 拒句;缺席或合法 ⇒ `null`(只在 fresh 受理门调)。 */
+export declare function sessionKindFieldIssue(raw: unknown): string | null;
 export {};
 //# sourceMappingURL=request-value-closure.d.ts.map

package/dist/request-value-closure.js

@@ -1,3 +1,4 @@
+import { SESSION_KINDS, isSessionKind } from "./session-kind.js";
 export const MEMORY_CAPTURE_SPELLING_MESSAGE = "memoryCapture must be the string 'off' when present (the session-level memory-capture opt-out declaration; absent = capture as usual — there is no 'on' spelling)";
 export const MEMORY_OFF_SPELLING_MESSAGE = "memory must be the string 'off' when present (the request-level declaration that this run mounts no memory face at all; absent = memory as usual — there is no 'on' spelling; to keep memory mounted but stop this session's content from entering long-term memory, send memoryCapture: 'off' instead)";
 export const FILE_HISTORY_OFF_SPELLING_MESSAGE = "fileHistory must be the string 'disabled' when present (the request-level declaration that this run records no file history — no backup of an edited file, and no file restore in the same request; absent = the deployment's setting — there is no 'enabled' spelling)";
@@ -49,4 +50,13 @@ export function inheritEnvFieldIssue(raw) {
         return null;
     return { message: INHERIT_ENV_VALUE_MESSAGE, facts: inheritEnvFacts(typeof value === "string" ? "unknown_word" : "not_a_string") };
 }
+export const SESSION_KIND_VALUE_MESSAGE = `sessionKind must be one of ${SESSION_KINDS.map((w) => JSON.stringify(w)).join(" | ")} when present ` +
+    `("sidechain" = the session this submission creates is a client-placed sub-conversation: it is not listed by GET /v1/sessions unless asked for with ?sessionKind=sidechain, ` +
+    `and it is deleted after BG_AGENT_RETENTION_MS of inactivity; absent = a top-level conversation) — the kind is written once, when the session is created`;
+export function sessionKindFieldIssue(raw) {
+    if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const value = raw.sessionKind;
+    return value === undefined || isSessionKind(value) ? null : SESSION_KIND_VALUE_MESSAGE;
+}
 //# sourceMappingURL=request-value-closure.js.map

package/dist/rule-issue-reading.d.ts

@@ -51,7 +51,7 @@ export type PersonFacingRuleIssue = {
  * 码与句逐字是 core 的;`libraryOption` 不进句子、也不进出口(出口只有 `code` / `guidance`)。
  */
 export declare function deploymentRuleRefusal(issue: PermissionRuleIssue): {
-    readonly code: string;
+    readonly code: PermissionRuleIssue["code"];
     readonly guidance: string;
 };
 export {};

package/dist/rules-consent.d.ts

@@ -467,7 +467,7 @@ export type CardRulePersisted = {
      * 导出成一只纯函数 —— 在本层照抄一个更严的校验器会把 `Bash(adb *)` 这条**成因形**当场误拒。」
      *
      * 现况:那只纯函数到货了,于是**文本能独立判定的那一半**({@link precheckEditedRuleText} 的语法门
-     * + 覆盖门)搬到了**裁决之前**——`POST /v1/tool-approvals/:id/respond` 在结算之前就 400,卡**还在**
+     * + 覆盖门)搬到了**裁决之前**—— 决断口 `POST /v1/tasks/:taskId/asks/:askId/decision` 在结算之前就 400,卡**还在**
      * (与 `persistRule.rule` 的形/上限 400 同一姿势,那条 400 早就是这个形)。所以壳今天可以渲
      * 「改一下再来」,而且真能来。
      *

package/dist/run-acceptance.d.ts

@@ -76,12 +76,13 @@ export interface RunAcceptance {
     observe(ev: {
         type: string;
     }): Promise<void>;
-    /** 终局落行之后:还没在流上见过受理帧、而结果里跑过 turn(只回结果的腿)⇒ 受理。只读 `stats.turns`。不抛、不等。 */
+    /** 结果到手、**放掉这条 run 的认领之前**(收场写 / 停驻提交之前):还没在流上见过受理帧、而结果里跑过 turn(只回结果的腿)⇒ 受理。只读 `stats.turns`。不抛;
+     *  交回的那一拍等标题器钉住要起名的住客(有界一读;认领在手 ⇒ 会话删不掉 ⇒ 住客就是这条 run 的)与补写落定 —— 腿 await 它再放认领。 */
     settle(result: {
         readonly stats: {
             readonly turns: number;
         };
-    }): void;
+    }): Promise<void>;
     /** 提交那一刻就知道的交付文本(腿上没有屏 ⇒ 请求原文);腿上有屏 ⇒ 缺席:各面提交时不写,交付时经 {@link onDelivered} 补。 */
     readonly objectiveAtSubmit: string | undefined;
     /**

package/dist/run-acceptance.js

@@ -35,11 +35,10 @@ export function createRunAcceptance(deps, input) {
         delivered = objective;
         if (objective === undefined)
             return Promise.resolve();
-        if (input.sessionId)
-            deps.sessionTitler?.maybeTitle(input.sessionId, objective, input.model, deliver);
+        const titled = input.sessionId ? (deps.sessionTitler?.maybeTitle(input.sessionId, objective, input.model, deliver) ?? Promise.resolve()) : Promise.resolve();
         if (!input.screened)
-            return Promise.resolve();
-        return Promise.all(fills.map(({ face, fill }) => runFill(face, fill, objective))).then(() => undefined);
+            return titled;
+        return Promise.all([titled, ...fills.map(({ face, fill }) => runFill(face, fill, objective))]).then(() => undefined);
     };
     return {
         objectiveAtSubmit: input.screened ? undefined : input.objective,
@@ -51,8 +50,7 @@ export function createRunAcceptance(deps, input) {
             return Promise.resolve();
         },
         settle(result) {
-            if (result.stats.turns > 0)
-                void accept(input.screened ? undefined : input.objective);
+            return result.stats.turns > 0 ? accept(input.screened ? undefined : input.objective) : Promise.resolve();
         },
         onDelivered(face, fill) {
             if (!input.screened)