@sema-agent/server 7.146.0 → 7.147.0

package/dist/runtime-caps-resolver.d.ts

@@ -66,6 +66,11 @@
  * 人的授予、搭上一个人的在飞请求、带上一个人的 etag 去换 304。在飞期间换了人,答复由传输层丢弃
  * (`http-client.ts` `requestPrincipalView`),按这一次取数失败走下面的 fail-closed 臂(降级项落在发起那一箱)。
  *
+ * 🔐 场景面同一条故障律、另一种拒法:同一次硬失败把场景那一面记成 `"unavailable"`(读数第三态,见 `capabilities/scenarios.ts`
+ * `ScenarioRulingRead`),场景门据它拒这条 run(503 `state.scenario_assignment_unavailable`)—— 场景面没有「拒掉放大位、照跑」的中间形:
+ * 受限主体的指派与白名单此刻不可知,落部署缺省或照放点名都可能比他的指派更宽。治理两键形不对同记 `"unavailable"`(经 `onError` 一行)。
+ * 缺席(无 principal / 中心不发两键)仍是 `undefined`;没接中心的部署根本没有本客户端。
+ *
  * The resolver maps center's `EntitlementRuntimeCaps` → the SUBSET core enforces ({@link RuntimeCaps}): center
  * also carries `allowUltracode` (a shell/UX reasoning-tier cap the engine has no primitive for), which we DROP —
  * this seam feeds the ENGINE, and `allowUltracode` is enforced at the service settings-resolution layer, not here.
@@ -77,7 +82,7 @@ import type { RuntimeCaps } from "@sema-agent/core";
 import type { EntitlementRuntimeCaps } from "@sema-agent/settings-schema";
 import { fetchPrincipalCaps, type ExecutionRuling } from "./web-admin-client/facade.js";
 import type { CenterEndpoint } from "./web-admin-client/center-request.js";
-import type { ScenarioRuling } from "./capabilities/scenarios.js";
+import type { ScenarioRulingRead } from "./capabilities/scenarios.js";
 import type { ServiceConfig } from "./config-types.js";
 import { type Logger } from "./observability/logger.js";
 /** test-only: reset the once-per-process trace so each test observes a fresh "first hit". */
@@ -181,17 +186,18 @@ export interface PrincipalEntitlementsClient {
      * 都重抓,denyTtl 的界对提交腿失效)。让它升格的是一次真提交自己吃到的硬失败,不是那次读。
      */
     peekRuntimeCaps: (principal: string | undefined) => Promise<RuntimeCaps | undefined>;
-    /** The resolved per-principal scenario ruling for resolveSpec's gateScenarioRequest —
-     *  FAIL-OPEN on error / older center without scenario keys / no principal (undefined = no governance, legacy passthrough).
-     *  Scenario switching is not a privilege-amplifying face; a center blip must not pin users to `default`. */
-    scenarioRuling: (principal: string | undefined) => Promise<ScenarioRuling | undefined>;
+    /** The resolved per-principal scenario ruling for resolveSpec's gateScenarioRequest — a three-state read
+     *  ({@link ScenarioRulingRead}): the ruling; `undefined` = absent (no principal ⇒ no center call; older center without
+     *  the scenario keys) = no governance; `"unavailable"` = the center could not answer (hard fetch failure — same error entry
+     *  as the caps face's fail-closed deny — or malformed ruling keys) ⇒ the gate refuses the run. */
+    scenarioRuling: (principal: string | undefined) => Promise<ScenarioRulingRead>;
     /**
      * {@link PrincipalEntitlementsClient.scenarioRuling} 的**只读**孪生(同 {@link PrincipalEntitlementsClient.peekRuntimeCaps} 的界):同一只缓存 / 同一条抓取 /
-     * 同一份 fail-open 判决(`undefined` = 无治理),唯一的差别是 center 硬失败时本腿铸的 fail-closed 降级项**只对读面自己算数**,提交腿不认、照常重抓。
+     * 同一份三态读数(故障 ⇒ `"unavailable"`,读面与提交腿同拒),唯一的差别是 center 硬失败时本腿铸的降级项**只对读面自己算数**,提交腿不认、照常重抓。
      * 读面(`GET /v1/capabilities/mcp?scenario=` 的场景门)问中心裁定时必须走这一只 —— 经 `scenarioRuling` 问,center 抖动的那一拍会替这个主体的**真提交**
      * 留下 `{allowWorkflows:false, allowFork:false, autoMode:false}` 的短窗 deny(读面成了别人被拒的原因,与 `peekRuntimeCaps` 的病灶同一类)。
      */
-    peekScenarioRuling: (principal: string | undefined) => Promise<ScenarioRuling | undefined>;
+    peekScenarioRuling: (principal: string | undefined) => Promise<ScenarioRulingRead>;
     /** (stage7 P5) The resolved per-principal execution-lane ruling for resolveSpec's
      *  gateExecutionLane. FAIL-OPEN + audit on error (this phase is "honest-but-bypassable";
      *  tightening to fail-closed is a future, separate decision) / older center without the execution key / no principal. */
@@ -215,7 +221,8 @@ export declare function gateExecutionLane(ruling: ExecutionRuling | undefined, o
  * `(principal) => Promise<RuntimeCaps | undefined>`; `scenarioRuling` rides the SAME fetch/cache/in-flight
  * (zero extra center RTT — center attaches the ruling to the caps body). Wire ONLY when a center is
  * configured (and not in dry-run) — absent ⇒ core sees `undefined` ⇒ NO per-principal restriction, and the
- * scenario gate sees `undefined` ⇒ legacy body-or-default chain.
+ * scenario gate sees `undefined` (absent) ⇒ request-name-or-deployment-default chain. Present ⇒ a center that cannot answer
+ * reads `"unavailable"` on the scenario face (the gate refuses), never `undefined`.
  */
 export declare function createPrincipalEntitlementsClient(opts: EntitlementsResolverOpts): PrincipalEntitlementsClient;
 /** Back-compat face for core's seam-only consumers: the caps half of {@link createPrincipalEntitlementsClient}. */

package/dist/runtime-caps-resolver.js

@@ -91,6 +91,13 @@ export function createPrincipalEntitlementsClient(opts) {
     const fetchCaps = opts.fetchCaps ?? fetchPrincipalCaps;
     const now = opts.now ?? (() => Date.now());
     const onError = opts.onError ?? ((err, principal) => defaultLogger.warn("runtime_caps_resolve_failed", { principal, err: String(err) }));
+    const audit = (err, principal) => {
+        try {
+            onError(err, principal);
+        }
+        catch {
+        }
+    };
     const binNow = createIdentityBins(opts.center.credential, (credential) => ({
         center: { baseUrl: opts.center.baseUrl, credential },
         cache: new Map(),
@@ -136,14 +143,14 @@ export function createPrincipalEntitlementsClient(opts) {
                     return entry;
                 }
                 if (r.executionDrift) {
-                    try {
-                        onError(new Error(`execution ruling wire drift: ${r.executionDrift}`), principal);
-                    }
-                    catch { }
+                    audit(new Error(`execution ruling wire drift: ${r.executionDrift}`), principal);
+                }
+                if (r.scenarioDrift) {
+                    audit(new Error(`scenario ruling wire drift: ${r.scenarioDrift}`), principal);
                 }
                 const entry = {
                     caps: toCoreRuntimeCaps(r.runtimeCaps),
-                    ...(r.scenario ? { scenario: r.scenario } : {}),
+                    ...(r.scenarioDrift ? { scenario: "unavailable" } : r.scenario ? { scenario: r.scenario } : {}),
                     ...(r.execution ? { execution: r.execution } : {}),
                     ...(r.etag ? { etag: r.etag } : {}),
                     expiresAt: now() + ttlMs,
@@ -159,14 +166,11 @@ export function createPrincipalEntitlementsClient(opts) {
                 catch {
                     e = new Error("center fetch failed with an unstringifiable rejection reason");
                 }
-                const entry = { caps: { allowWorkflows: false, allowFork: false, autoMode: false, autoModeDenySource: "org", bypassPermissions: false }, expiresAt: now() + denyTtlMs };
+                const entry = { caps: { allowWorkflows: false, allowFork: false, autoMode: false, autoModeDenySource: "org", bypassPermissions: false }, scenario: "unavailable", expiresAt: now() + denyTtlMs };
                 if (!recordDeny)
                     readMintedDeny.add(entry);
                 putCache(bin.cache, principal, entry);
-                try {
-                    onError(e, principal);
-                }
-                catch { }
+                audit(e, principal);
                 return entry;
             }
             finally {

package/dist/sealed-key-layout.d.ts

@@ -1,13 +1,12 @@
 /**
- * 钥匙保管目录的布局常量 —— 引擎建目录、写钥匙文件、建停驻行封签子目录时用的**唯一**值(`src/sealed-key.ts` 读它们)。
+ * 钥匙保管目录的布局常量 —— 引擎建目录、建停驻行封签子目录时用的**唯一**值(`src/sealed-key.ts` 读它们)。
+ * 钥匙文件的权限位不在这里:它就是本服务文件的那一个值 `plugins/owner-only-file-mode.ts` 的 `OWNER_ONLY_FILE_MODE`(部署事实同读它)。
  *
  * 单独成一只零依赖的叶子模块:随包部署事实 `deploy/facts/sealed-key.json`(`src/deploy-facts.ts` 投影、`scripts/gen-deploy-lanes.ts` 生成)
  * 读的是同一份值,生成器不必为了三个常量把整只保管模块(libsodium / 中心上报)装载进来。
  */
 /** 保管目录的权限位:每次建店都 `mkdir` + `chmod` 成它(目录预先存在时 `mkdir` 的 mode 不生效,所以另 `chmod` 一次)。 */
 export declare const SEALED_KEY_DIR_MODE = 448;
-/** 钥匙文件 `<publicKeyId>.json` 的权限位(`writeFile` 的 mode 受 umask 掩,所以另 `chmod` 一次)。 */
-export declare const SEALED_KEY_FILE_MODE = 384;
 /**
  * 停驻行凭据封签那一域的保管子目录名(在模型钥匙保管目录之下:`<保管目录>/checkpoint-ctx-keys/`)。**一个域一对钥匙**:模型钥匙(`ModelEntry.sealedApiKey`,
  * 浏览器对着 caps 公钥裸封)与停驻行封签各用自己目录里的钥匙对 —— 一边的开箱口在另一边的密文上恒「不持有那把钥匙」,不是靠哪一侧多判一句信封。

package/dist/sealed-key-layout.js

@@ -1,4 +1,3 @@
 export const SEALED_KEY_DIR_MODE = 0o700;
-export const SEALED_KEY_FILE_MODE = 0o600;
 export const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
 //# sourceMappingURL=sealed-key-layout.js.map

package/dist/sealed-key.js

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
-import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { ensureDir } from "@sema-agent/core";
 import _sodium from "libsodium-wrappers";
-import { CHECKPOINT_CTX_KEY_SUBDIR, SEALED_KEY_DIR_MODE, SEALED_KEY_FILE_MODE } from "./sealed-key-layout.js";
+import { CHECKPOINT_CTX_KEY_SUBDIR, SEALED_KEY_DIR_MODE } from "./sealed-key-layout.js";
+import { OWNER_ONLY_FILE_MODE } from "./plugins/owner-only-file-mode.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
 import { createCenterCredentialSource } from "./center-credential.js";
 import { centerFetch } from "./web-admin-client/center-request.js";
@@ -62,7 +64,7 @@ export function judgeSealedKeyPublicKey(publicKeyB64) {
 export async function ensureSealedKeyStore(dir, logger) {
     await _sodium.ready;
     const sodium = _sodium;
-    await mkdir(dir, { recursive: true, mode: SEALED_KEY_DIR_MODE });
+    ensureDir(dir);
     await chmod(dir, SEALED_KEY_DIR_MODE);
     const keys = new Map();
     for (const name of (await readdir(dir)).filter((n) => n.endsWith(".json")).sort()) {
@@ -100,8 +102,8 @@ export async function ensureSealedKeyStore(dir, logger) {
             createdAt: new Date().toISOString(),
         };
         const path = join(dir, `${record.publicKeyId}.json`);
-        await writeFile(path, JSON.stringify(record, null, 2) + "\n", { mode: SEALED_KEY_FILE_MODE });
-        await chmod(path, SEALED_KEY_FILE_MODE);
+        await writeFile(path, JSON.stringify(record, null, 2) + "\n", { mode: OWNER_ONLY_FILE_MODE });
+        await chmod(path, OWNER_ONLY_FILE_MODE);
         keys.set(record.publicKeyId, { publicKey: kp.publicKey, privateKey: kp.privateKey, publicKeyB64, createdAt: record.createdAt });
         logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair in this directory — the private key exists only here: keep the directory across restarts and identical on every replica that has to open what it sealed, and back it up as a private key" });
     }

package/dist/security.d.ts

@@ -25,7 +25,7 @@ export interface SessionListItem {
      *  ⇒ 在跑 latest 键诚实缺席)。
      *  读法一致:缺席 = 「此行无已知 engine runId」,禁读成其它含义。⚠️ 与 `lastRunId`(= latest run 的 **task_id**)
      *  是两条身份轴,命名对齐 core `SessionStoreSummary.lastTaskRunId`。wire:additive 键零投影透传
-     *  (sessions-list.ts);sema-sdk spec `SessionSummary` 闭集候 SDK 半场开键([ref]/.82 班车)。 */
+     *  (sessions-list.ts);sema-sdk spec `SessionSummary` 已声明此键(对账门 `test/sdk-live-parity.test.ts`)。 */
     lastTaskRunId?: string;
     /** The session's title — the user's (`PATCH /v1/sessions/:id`) or, until the user sets one, the auto-titler's
      *  (null = untitled / lister face has no session_meta). One column, two writers, one order: `session-row.ts`. */
@@ -193,7 +193,8 @@ export declare function sameSessionOwner(deployment: DeploymentShapeInput<"princ
 /**
  * 本仓会话店的面 = core `SessionStore` + 本仓的行面(登记 / 列表 / 换装 / 同步……)。
  * 🔴 **按 id 读一行只有一只**:core 的 `headOf(id)`(`{ owner, incarnation, leafId }`,同一行一次读;core 7.55.0 [ref] S2)。
- * 属主 = `headOf(id)?.owner`、住客 = 头的 `incarnation`(比较用 core `compareOccupants`,拿令牌去写用 `sessionFaceOfHead`)、叶子 = 头的 `leafId`
+ * 属主 = `headOf(id)?.owner`、住客 = 头的 `incarnation`(两头比较用 core `compareOccupants`:没有行 ⇒ `unknown`,两侧都有令牌且相等或都无令牌 ⇒ `same`,
+ * 一侧有一侧无 ⇒ `different`;拿令牌去写用 `sessionFaceOfHead`,它对无令牌的头响亮拒)、叶子 = 头的 `leafId`
  * —— 此前本面另有五只按 id 读(`ownerOf` / `incarnationOf` / `sessionFaceOf` / `getHead` / `getLeafId`),全部退役;规则在 `src/session-incarnation.ts` 头注,
  * 「店有没有这只读」只判 `headReadOf` 一处。
  */
@@ -288,7 +289,8 @@ export type OwnerAwareSessionStore = SessionStore & {
     importEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
     /** 2c session-sync (§7/§8) — IDEMPOTENT replace: atomically purge any existing conversation log for `sessionId`
      *  then import `entries` verbatim under `owner`. Unlike importEntries (plain INSERT, fresh-only) this is safe to
-     *  re-run / apply over an existing session (fast-forward, retry). owner-guarded delete (defense-in-depth). */
+     *  re-run / apply over an existing session (fast-forward, retry). Owner-guarded (defense-in-depth): the importer's own row is
+     *  rewritten in place — its incarnation and the deployment cells kept on it (title, pin, instruction baseline, workspace, placement) stay. */
     replaceEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
     /** 2c session-sync P1d-β (PUSH streaming) — begin a STAGED import into `realSessionId` under a shadow id
      *  `${realSessionId}#stg-${token}` (the route mints the uuidv7 `token`). Returns a {@link StagingHandle} the NDJSON

package/dist/sema-config-dir.js

@@ -1,6 +1,6 @@
-import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { ensureDir } from "@sema-agent/core";
 export function declaredSemaConfigDir(env = process.env) {
     const raw = env.SEMA_CONFIG_DIR;
     if (raw === undefined)
@@ -20,7 +20,7 @@ export function provisionSemaConfigDir(config, logger) {
     if (dir === undefined)
         return;
     try {
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        ensureDir(dir);
     }
     catch (e) {
         logger.warn("sema_config_dir_unprovisioned", {

package/dist/server-secret-env.d.ts

@@ -119,6 +119,8 @@ export interface HostSubprocessEnvRequest {
  * 九条宿主腿都只经它(直接或经 {@link gitSubprocessEnv}):host shell(三个继承词原样交给 `policy`)、project-memory / center-plugins / leader 三条 git 腿、
  * 本地语言服务器、bake-runner 的每一只子进程组、local-docker 与 adb 两条 CLI 腿(`"all"`)、settings hooks 的命令腿(十二名严格名单 + 有效环境层作授予)。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
  * 它们的现场在 `SECRET_ENV_SCRUB_SITES` 里登记了 `remedy`,披露行因此是 warn + 放行名单 + 出路句);其余现场传 `[]`。
+ * 「扣了哪些名字」一腿一个读者:host shell 腿由引擎读 `withheldEnv` 说(`inherit_env.names_withheld`,现场登记 `told:"engine-notice"` ⇒ 本函数对它只计数、不写披露行);
+ * 其余各条腿(含 host 适配器类里不交给引擎的 git worktree 基环境,`HostEnvConfig.gitBase`)引擎没有读者,披露行是唯一的读法(`told:"log"`)。
  * 返回 `NodeJS.ProcessEnv` 形(值可能是 `undefined` 的键本来就不会进子进程);调用方显式要交的键(`LC_ALL`、`cfg.env` …)叠在它之上。
  * 调用时机 = 每次要交 env 时现算一次(`process.env` 在本仓是 boot 期输入,各次同值;计数因此是「每组合一次」)。
  * 引擎对坏策略 / 点到自有凭据名的白名单在这里**抛**(spawn 时的拒是不变量;构造时的拒由各构造点自己先问 `inheritEnvPolicyProblem`)。

package/dist/service-version.d.ts

@@ -1,5 +1,6 @@
 /** Service version for GET /v1/capabilities — read from the package.json shipped next to src/ in the
- *  image (Dockerfile COPYs it), once per process. Best-effort: an unreadable file reports "unknown", never crashes boot. */
+ *  image (Dockerfile COPYs it), once per process. Best-effort: an unreadable file — or a `version` that is not a string — reports "unknown", never crashes boot.
+ *  (Whether "unknown" may serve is each reader's own judgment: the local data root's engine high-water refuses a build whose version is not a release version.) */
 declare function serviceVersion(): string;
 export { serviceVersion };
 //# sourceMappingURL=service-version.d.ts.map

package/dist/service-version.js

@@ -6,8 +6,8 @@ function serviceVersion() {
 }
 function readServiceVersion() {
     try {
-        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-        return pkg.version ?? "unknown";
+        const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))?.version;
+        return typeof version === "string" ? version : "unknown";
     }
     catch {
         return "unknown";

package/dist/session-error-wire.d.ts

@@ -21,7 +21,7 @@
  *    (悬空父而回放没丢记录 / 自指 / 成环 / 叶子缺席 / 分叉走链 —— 7.137.0–7.143.0 那一形是 `invalid_session`,见下一词)。不是 4xx:调用方没做错
  *    任何事;不是 503:重试改不了判(修复在运维手里)—— 与会话规则店的 `corrupt` 同一档同一理由。码不另铸(core 的词
  *    原样上 wire,契约既有立场:不为上游码铸孪生码)。三种会话后端同词:文件店由 core 铸,两只 SQL 店由
- *    `plugins/session-event-payload.ts` 铸(坏的 `session_event.payload` 行)。
+ *    `stores-sql/session-event-payload.ts` 铸(坏的 `session_event.payload` 行)。
  *  · `invalid_session` —— `import` 面 **422 `invalid_entries`**(修前 session-sync 的那一行,码位 / 状态逐字不变);`open` 面**留白**:core 7.62.0
  *    ([ref] / [ref])起它只是导入门的词,打开已存日志从不抛它 —— 走不成一棵树的已存日志是 `corrupt_session`(上一词);回放丢了记录的悬空父不再失败,
  *    run 从断点续上并在流上说 `session.lineage_rerooted`。7.137.0–7.143.0 本表在 open 面给过它一格 500 `invalid_session`(那时 core 用它说已存日志的结构坏),

package/dist/session-incarnation.d.ts

@@ -28,11 +28,14 @@
  *    内容读不出时,头照答行上的属主与住客,叶子那一格带着读它时撞上的那只故障({@link UnreadableLeaf}),**谁读叶子谁收到它**。
  *    于是只判归属的读者(授权门、各路由的属主门、删除的围栏、住客读)对坏内容与好内容同答,内容的故障只让门放行之后读内容的那一位看见;
  *    行本身读不出(local:边档里还没有这只会话的那一格、要从存档推出它在不在,而存档读不出)⇒ 头读整只拒(读故障,不是答案)。
- *  · **两头是不是同一位住客:core 的 `compareOccupants`**(三答 `same` / `different` / `unknown`;任一侧没有行或没有令牌 ⇒ `unknown`,
- *    `unknown` 永不当 `same`)。本仓自写的比较(`sameSessionOccupant`)退役:同一个问题只有引擎那一只判官。
+ *  · **两头是不是同一位住客:core 的 `compareOccupants`**(三答 `same` / `different` / `unknown`;core 7.65.0 起:任一侧没有行 ⇒ `unknown`;
+ *    两侧都有行时按引擎的一种读法比两格 —— 都有令牌且相等,或都没有令牌(缺席 / `""` / 非串)⇒ `same`,一侧有一侧没有 ⇒ `different`;
+ *    `unknown` 永不当 `same`,没有令牌也永不当通配)。本仓自写的比较(`sameSessionOccupant`)退役:同一个问题只有引擎那一只判官。
+ *    「这只头有没有令牌」不从 `compareOccupants` 推,读头本身(`head.incarnation`)。
  *  · **一位活住客必须有令牌 —— 读到空化身 ⇒ 响亮拒**({@link SessionIncarnationMissingError}):本仓比 core 多的那一条律,只住在一处 ——
  *    把头投成 {@link SessionFace}(属主 + 一只令牌)的 {@link sessionFaceOfHead}(批量来源读与换装回读用同一只 {@link sessionFaceFromRow})。
- *    要拿令牌去**写**(带化身条件的 UPDATE、认领、空间分区键)或要响亮区分「行坏了」的读者经它;只**比较**两头的读者用 `compareOccupants`。
+ *    要拿令牌去**写**(带化身条件的 UPDATE、认领、空间分区键)或要响亮区分「行坏了」的读者经它;只**比较**两头的读者用 `compareOccupants`
+ *    (它对两只无令牌的头答 `same` —— 拒无令牌行从来不是它的答案,是这一只的)。
  *    空值只可能来自没铸化身的写腿、人为改库,或跳过了 7.104.0–7.135.x(那几版的起服迁移给存量行铸令牌,窗关后已删码)直接升上来的库 ——
  *    把它当「通配」就是让任何人都能和这一行比成同一位住客。
  *  · **不上 wire、不进模型上下文、不进日志正文**:日志里要点名时只打 {@link incarnationLogPrefix}(前 8 位)。值本身不出进程;唯一出进程的形是
@@ -131,10 +134,10 @@ export interface CarriedRowCells {
     readonly forkKey: string | null;
 }
 /**
- * session-sync **换装**(整段换装 / 暂存提交)时行格的去留 —— 三只店共用的一句判据:换装只换内容,换的是**同一行**
+ * session-sync **换装**(整段换装 / 暂存提交)时行格的去留 —— local 店的判据(SQL 两店的换装就地改写同一行,化身与旁表行原地不动,同一结局、无需沿用判):换装只换内容,换的是**同一行**
  * ⇒ 行在且那一格里有一只令牌(唯一解码 {@link incarnationFromCell} 的 `absent` 读法)⇒ 化身与 fork 键(`fork_key` / local `forkKey`:建这一行的那次 fork
  * 请求的键,只由 fork 创建点写、此后每个写携带)**一起沿用**(属主重戳与否不改这一判:同一行 = 同一位住客);行不在(这是一次新建)或还是空的存量形 ⇒
- * 铸一只新化身、没有 fork 键。属主不在这里判:每只店在自己的属主门上判过被换的那一行(SQL 孪生的 replace 只交「属主门删得到的那一行」),读不中的换装一个字节不写。
+ * 铸一只新化身、没有 fork 键。属主不在这里判:店在自己的属主门上判过被换的那一行,读不中的换装一个字节不写。
  */
 export declare function carriedRowCells(sessionId: string, prior: {
     incarnation?: unknown;

package/dist/session-resident-background.d.ts

@@ -1,57 +1,110 @@
 /**
- * `/health.inflight` 计法表第四类 —— **会话驻留的后台 shell / monitor**。
+ * `/health.inflight` 计法表里**会话驻留的后台行**两类 —— 后台子代理(`backgroundAgents`,进阻断集)与后台 shell / monitor(`sessionResident`,只进总数)。
  *
  * ## 病
- * 引擎在飞数原先只数 HTTP 腿与 leader 腿。模型在会话里起的后台 shell / monitor(`run_in_background`)活过起它的那一条腿 —— 腿一收,它在这份数里是 0:
- * 读 `/health` 判「这台引擎是否空闲」的外部判官看不见它们,只好另拼一条谓词 —— 同一个事实两个读法。
- *
- * ## 两个事实(本文件只产总数里的第三项 `sessionResident`)
- * `/health.inflight`(总数,{@link inflightTotal})= 引擎此刻托管着多少活 = `http + leader + sessionResident`,可观测事实;
- * `drainState.blockingInflight`(阻断集,{@link blockingInflightOf})= 还有没有必须等完的活 = `http + leader`,排空 / 孤儿窗 / 附着租约自退 / SIGHUP 空闲窗判停读它。
- * 本文件产出的 `sessionResident` **只进总数、不进阻断集**:驻留 shell 不是一条腿,等它没有意义;一只不退出的 shell(`while true`)若阻断,崩溃孤儿引擎就永生。
- * 窗到 / 排空完成,退出边界的后台收割收掉它们,retain 行按 retain 既有语义活过受控退。
- *
- * ## 读法(本文件是唯一属主)
- * 行集 = core `TaskRegistry.liveTasks(access)` 的投影:`type ∈ {background_bash, monitor}` ∧ `status === "running"` ∧ `sessionScoped` ∧ 非 retain
- * ({@link isSessionResidentShellRow})。
+ * 引擎在飞数原先只数 HTTP 腿与 leader 腿。模型在会话里起的后台活 —— `run_in_background` 的 shell / monitor、core `backgroundScope:"session"` 下的
+ * 后台子代理(Agent / Fork)—— 活过起它的那一条腿:腿一收,三张登记簿里都没有它,而引擎还托管着它。读 `/health` 判「这台引擎是否空闲」的外部判官看不见它们,
+ * 只好另拼一条谓词(同一个事实两个读法);附着租约 / 排空 / SIGHUP 空闲窗对还在烧模型的后台子代理同样看不见,把它随引擎的受控退中断。
+ *
+ * ## 两个事实(本文件产分项里的两项;两个和只在 `fleet/drain-entry.ts` 各写一次)
+ * `/health.inflight`(总数,{@link inflightTotal})= 引擎此刻托管着多少活 = `http + leader + backgroundAgents + sessionResident`,可观测事实;
+ * `drainState.blockingInflight`(阻断集,{@link blockingInflightOf})= 还有没有必须等完的活 = `http + leader + backgroundAgents`,排空 / 孤儿窗 / 附着租约自退 / SIGHUP 空闲窗判停读它。
+ * 两个和读**同一只**分项函数(`http/server.ts` 的 `inflightBreakdown`),本文件的读数在一次走查里同时交出两项 —— 判停与 `/health` 不是两份算法。
+ *  · `backgroundAgents` **进阻断集**:后台子代理是一条在干活的模型腿,干完自己收尾(在审批 / 问答卡上等人时行仍是 `running`、照计;窗满转成耐久停驻后不再计);
+ *    不等它 = 受控退把一条还在干活的子代理中断(账本行落终态,模型工作丢)。与驻留 shell 的分界不是「有没有墙钟上限」—— core [ref] 已退役会话级子代理的
+ *    30 min 缺省墙钟,两类都没有 —— 而是「会不会自己结束」:模型腿干完即止,`while true` 的 shell 永不。
+ *    上界 = 停滞收割窗 `BG_AGENT_STALL_MS`(下面「停滞收割」一节):任务表行一直是 `running`、却不再有工具活动的子代理 —— 挂死的,或已收尾、但 core 在把行转终态之前
+ *    await 的那一次委派行写 / 工作树收尾挂住了的(core `agents/subagent.js` 子代收尾链:`await rowSettled` 先于 `settleBackgroundAgent`)—— 静默满窗即被收,不再无界地撑着判停窗。
+ *  · `sessionResident` **只进总数**:驻留 shell 不是一条腿,等它没有意义;一只不退出的 shell(`while true`)若阻断,崩溃孤儿引擎就永生、排空每次等满窗。
+ *    窗到 / 排空完成,退出边界的后台收割收掉它们,retain 行按 retain 既有语义活过受控退。
+ *
+ * ## 读法(本文件是唯一属主;行判一处写:{@link sessionResidentTermOf})
+ * 行集 = core `TaskRegistry.liveTasks(access)` 的投影,按行类型与状态分到两项之一或不计:
+ *
+ *  | 行(`sessionScoped` 为真)                         | 状态 `pending` / `running` | `parked`          | 终态 |
+ *  |---------------------------------------------------|----------------------------|-------------------|------|
+ *  | `background_agent`(后台子代理)                   | `backgroundAgents`         | 不计(耐久停驻) | 不计 |
+ *  | `background_bash` / `monitor`,非 retain          | `sessionResident`          | 不计              | 不计 |
+ *  | `background_bash` / `monitor`,retain             | 不计(交付的活服务,活过受控退)                 |||
+ *  | `workflow`                                        | 不计(见下)                                     |||
+ *
+ *  · **`sessionScoped` 为假的行不计**:挂在 run 腿上的后台行随腿登记在 `http` 项里,数它是第二次(腿一收,core 的拆腿收割把它们一起结掉)。
+ *  · **`parked` 不计**:与停驻的 run 同一条律 —— 停驻是耐久的(引擎退了不丢,下次起来仍可赎回),不占执行座;算它,一张没人答的审批就让引擎永远退不掉。
+ *  · **`workflow` 行不计**(计法表成文的一行,不是遗漏):任务表对一条 workflow 只投 `running`,一条腿停在审批门上等人时也还是 `running` ——
+ *    这只读法分不出「在干活」与「在等人」。进阻断集 ⇒ 一张没人答的审批让崩溃孤儿引擎永生(与驻留 shell 同一病);只进总数 ⇒ 多一类只报不阻断的项、
+ *    判据与停驻律对不上。停驻位(core `runParkedOf`)要由任务表投出来才能按停驻律分(请托 core);到货前 workflow 照旧不进在飞,与 7.146.x 同。
+ *  · **状态是闭集**(`SemaTaskStatus` 穷举):core 加一个词 ⇒ 这里编译红,不会被静默读成「不计」。
+ *  · **一行只数一次**:各会话的可见集可以相交(core `canAccess` 对后台子代理还认 `rootSessionId` —— 子会话与根会话都在围栏表时,两次读都看得见同一行)⇒ 整趟走查按 `task_id` 去重。
  *  · **选座 `liveTasks`,不读 `list()`**:`list()` 是显示投影,硬帽 500 行(core 注:resolution must NEVER ride the display-capped list());
- *    进程级的在飞总数是外部判官判「引擎是否空闲」的依据,不能骑显示帽 —— 超过 500 行时 `list()` 会静默少数,方向恰是「以为空闲」。`liveTasks` 无显示帽。
- *  · **retain 行不计**:显式 retain 的行是「交付的活服务」,按 core 契约活过引擎的受控退(退出边界对它 `retained_skipped`),
- *    不是「引擎托管着、会随它收掉」的活 —— 报它,判官会把一个本就该活过引擎的服务读成引擎的负载。
- *  · **只数 shell 与 monitor**:后台 agent / workflow 行属计法表的别的类,不在这一类里。
- *  · **非会话驻留行不数**:挂在 run 腿上的后台行(`sessionScoped` 为假)随腿登记在 HTTP 腿项里,数它是第二次。
+ *    超过 500 行时 `list()` 会静默少数,方向恰是「以为空闲」。`liveTasks` 无显示帽。
  *
  * ## 枚举源
- * core 的 `canAccess` 要求访问元组带 `scope`(缺 scope 一律拒),`list` / `liveTasks` 因此只读「调用方可达行」,没有进程总数的读口(core 不立新 getter)。
- * 进程级的数要由本仓自己枚举「本进程有哪些会话」:枚举源 = **围栏表**(`boot/execution-env.ts` 的 `SessionScopedRegistries.sessionOwners`):
+ * core 的 `canAccess` 要求访问元组带 `scope`(缺 scope 一律拒),`list` / `liveTasks` 因此只读「调用方可达行」,没有进程总数的读口。
+ * 进程级的数由本仓自己枚举「本进程有哪些会话」:枚举源 = **围栏表**(`boot/execution-env.ts` 的 `SessionScopedRegistries.sessionOwners`):
  * 每次提交经 resolve-spec 写一笔(会话 id → 属主),删会话的 E21 级联清一笔,LRU 有界。scope 轴 = {@link sessionChildrenScope}(会话属主 `?? "default"`,
- * 删除门 / 换绑门 / 结清口 / 会话后台读面同一个取法,不另取)。
+ * 删除门 / 换绑门 / 结清口 / 会话后台读面同一个取法,不另取)。会话驻留的后台子代理 `owner` = 会话 id([ref] 纪律),同一只访问元组够得着。
+ * 〔待 core:一只进程级、不按访问元组收窄的计数读口(`countRunningBackgroundShells` 的子代理孪生)到货后,子代理一项改读它 —— 下面三条边界随之消失。〕
  *
  * ## 读到的边界(成文,不静默)
- *  · 围栏表是 LRU(上界 4096 会话):被挤出表的会话,它的驻留行在这里不可见 —— 回到改前的读数(不是新的错),不会多数;
+ *  · 围栏表是 LRU(上界 4096 会话):被挤出表的会话,它的会话驻留行在这里不可见 —— 回到 7.146.x 前的读数(不是新的错),不会多数;
  *  · 不经 resolve-spec 的内部车道(服务为自己起的 run)不写围栏表,它们起的会话驻留行同样不可见;
  *  · 删会话的级联在 `dropSessionScoped` 之后、后台收割之前失败(会话行因此没删)时,围栏表已先清:该会话还在跑的驻留行在下一次提交重新围栏之前不可见
- *    (同样回到改前的读数;修法是把 `dropSession` 的「清秘密」与「忘身份」拆开,属围栏表的属主,不在本读法里);
+ *    (修法是把 `dropSession` 的「清秘密」与「忘身份」拆开,属围栏表的属主,不在本读法里);
  *  · 每次读是 O(围栏表会话数 × 注册表行数)(`liveTasks` 逐会话走一遍注册表);表的上界 4096、注册表行数小,量级是毫秒。
+ *    这一读在判停路径上(排空 1 s 拍 / 租约拍 / SIGHUP 拍)每拍付一次 —— 后台子代理进阻断集的代价,与 `/health` 同一份。
+ *
+ * ## 停滞收割:先收尸,再数活(本文件是收割的唯一调用点)
+ * 引擎把会话驻留后台子代理的反僵尸义务交给调用方:`TaskRegistry.reapStaleSessionBackgroundAgents(staleMs)` 把**最后一次工具活动**距今超过 `staleMs` 的
+ * `running` 行收成 `killed`(归因 `system`,措辞与耐久 stale-running 清扫同一句)并中止它的 run;停驻行、随腿的行、终态行它不碰。
+ * {@link countSessionResidentBackground} 每读一次先调它一次、再走任务表 —— 所以计法表里「在跑的后台子代理」= 引擎任务表此刻说 `running` 的行,
+ * 而任务表在被数之前已经按停滞窗结清过一遍。本服务不另判「这一行其实不活」(行说 running、本服务说不活 = 一个事实两种读法):不活的行由引擎收成终态,本文件只数。
+ *  · **拍**:不另起计时器。读口的读者就是拍 —— 排空 1 s 拍、附着租约拍、SIGHUP 空闲窗 1 s 拍、`/health`、崩溃遗言;每一处判停读数之前都先收过一次。
+ *    没有任何读者的进程里没有判据要读这一项,僵尸行只停在任务表的显示面上。
+ *  · **窗**:`BG_AGENT_STALL_MS`,缺省 = 下限 = 派生值(`config.ts` 的 `backgroundAgentStallFloorMs`:等人的四个窗取大 + 引擎单命令上限)。
+ *    子代在审批卡 / 问答卡上等人时行是 `running`、没有工具活动 —— 窗不盖住等人的窗,就会把一只等你回来批的子代当僵尸收掉。
+ *  · **收割失败**(引擎抛)⇒ 读口照数任务表(没收掉的行照算在跑:宁可等,与收割接线之前同读)并经 `stall.report` 报出;读口不抛。
  *
  * ## 读不出 ⇒ 非空闲(响亮,不替成 0)
- * 本函数在 `/health` 应答和崩溃遗言(uncaught 处理器里读总数)里被调,**不许抛**(崩溃遗言里一次抛会吞掉遗言本身)。判停路径(排空 / 租约 / SIGHUP)读阻断集,
- * 不求值本函数。某个会话的 `liveTasks` 读失败 ⇒ 该会话按 **1 只在跑**计(读不出 ⇒ 非空闲:判官宁可当有活)并经 `onUnreadable` 报出 ——
- * 调用方必须给报口(装配层一会话一行 `session_resident_background_unreadable`),不存在静默的 0。
+ * 本函数在判停路径(排空首读在期限计时器装上之前)、`/health` 应答与崩溃遗言里被调,**不许抛**(判停首读一抛 ⇒ 期限计时器装不上 ⇒ 永不硬停;
+ * 崩溃遗言里一抛会吞掉遗言本身)。某个会话的读失败(含行判遇到闭集外的值)⇒ 该会话按 **1 只在跑的后台子代理**计 —— 落在阻断项里,判停也看得见
+ * (读不出 ⇒ 非空闲:宁可当有活)—— 并经 `onUnreadable` 报出;调用方必须给报口(装配层一会话一行 `session_resident_background_unreadable`),不存在静默的 0。
  */
 import { type TaskListRow, type TaskRegistry } from "@sema-agent/core";
+import type { InflightBreakdown } from "./fleet/drain-entry.js";
 /** 枚举源的形:会话 id → 会话属主(`null` = 匿名)。`Map` 满足它。 */
 export type SessionOwners = Iterable<readonly [sessionId: string, owner: string | null]>;
-/** 这一类里的行判:唯一写处(计数与单测同读)。 */
-export declare function isSessionResidentShellRow(row: TaskListRow): boolean;
+/** 本文件交出的两项(键名属主 = {@link InflightBreakdown})。 */
+export type SessionResidentCounts = Pick<InflightBreakdown, "backgroundAgents" | "sessionResident">;
+/** 一行落在哪一项。 */
+export type SessionResidentTerm = keyof SessionResidentCounts;
+/**
+ * 行判:唯一写处(计数与单测同读)。`undefined` = 这一行不进在飞(理由见文件头的表)。闭集外的行类型 / 状态 ⇒ **抛**(由 {@link countSessionResidentBackground}
+ * 按「读不出」收:该会话计 1、报出)—— 不静默读成「不计」。
+ */
+export declare function sessionResidentTermOf(row: TaskListRow): SessionResidentTerm | undefined;
 /** 一个会话的驻留行读失败的报口(由调用方给出:装配层记运维行)。 */
 export type UnreadableSessionReport = (sessionId: string, err: unknown) => void;
+/** 一次停滞收割的结局:收掉了 `count` 行(> 0 才报)/ 收割本身抛了。闭集,装配层按 `kind` 穷举。 */
+export type StallReapOutcome = {
+    readonly kind: "reaped";
+    readonly count: number;
+} | {
+    readonly kind: "failed";
+    readonly err: unknown;
+};
+/** 停滞收割的策略:窗(ms,`BG_AGENT_STALL_MS`)与报口。读口必给 —— 没有「不收割」的读法。 */
+export interface StallReapPolicy {
+    readonly stallMs: number;
+    readonly report: (outcome: StallReapOutcome) => void;
+}
 /**
- * 本进程里会话驻留的、仍在跑的后台 shell / monitor 行数。`registry` 缺省 = 进程级单例;参数只供测试换桩(只用到 `liveTasks`)。
- * `onUnreadable` 必给:读失败的会话按 1 计并经它报出(文件头「读不出 ⇒ 非空闲」)。读法与边界见文件头。
+ * 本进程里会话驻留的、仍在跑的后台行,按项计数(一次走查交出两项)。**先收尸再数活**:走查之前按 `stall` 收一次停滞的后台子代理(文件头「停滞收割」)。
+ * `registry` 缺省 = 进程级单例;参数只供测试换桩(只用到 `reapStaleSessionBackgroundAgents` 与 `liveTasks`)。
+ * `onUnreadable` 必给:读失败的会话按 1 只在跑的后台子代理计并经它报出(文件头「读不出 ⇒ 非空闲」)。读法与边界见文件头。
  */
 export declare function countSessionResidentBackground(sessions: SessionOwners, opts: {
-    readonly registry?: Pick<TaskRegistry, "liveTasks">;
+    readonly registry?: Pick<TaskRegistry, "reapStaleSessionBackgroundAgents" | "liveTasks">;
     readonly onUnreadable: UnreadableSessionReport;
-}): number;
+    readonly stall: StallReapPolicy;
+}): SessionResidentCounts;
 //# sourceMappingURL=session-resident-background.d.ts.map

package/dist/session-resident-background.js

@@ -1,20 +1,88 @@
 import { defaultTaskRegistry } from "@sema-agent/core";
 import { sessionChildrenScope } from "./session-children-retire.js";
-export function isSessionResidentShellRow(row) {
-    return (row.type === "background_bash" || row.type === "monitor") && row.status === "running" && row.sessionScoped && row.retained !== true;
+function liveStatus(status) {
+    switch (status) {
+        case "pending":
+        case "running":
+            return true;
+        case "parked":
+        case "completed":
+        case "failed":
+        case "killed":
+        case "cancelled":
+            return false;
+        default: {
+            const unhandled = status;
+            throw new Error(`session-resident background: unknown task status ${String(unhandled)}`);
+        }
+    }
+}
+export function sessionResidentTermOf(row) {
+    if (!row.sessionScoped)
+        return undefined;
+    switch (row.type) {
+        case "background_agent":
+            return liveStatus(row.status) ? "backgroundAgents" : undefined;
+        case "background_bash":
+        case "monitor":
+            return liveStatus(row.status) && row.retained !== true ? "sessionResident" : undefined;
+        case "workflow":
+            return undefined;
+        default: {
+            const unhandled = row.type;
+            throw new Error(`session-resident background: unknown task type ${String(unhandled)}`);
+        }
+    }
 }
 export function countSessionResidentBackground(sessions, opts) {
     const registry = opts.registry ?? defaultTaskRegistry;
-    let n = 0;
+    reapStalled(registry, opts.stall);
+    let backgroundAgents = 0;
+    let sessionResident = 0;
+    const counted = new Set();
     for (const [sessionId, owner] of sessions) {
         try {
-            n += registry.liveTasks({ owner: sessionId, sessionId, scope: sessionChildrenScope(owner) }).filter(isSessionResidentShellRow).length;
+            const fresh = [];
+            for (const row of registry.liveTasks({ owner: sessionId, sessionId, scope: sessionChildrenScope(owner) })) {
+                const term = sessionResidentTermOf(row);
+                if (term !== undefined && !counted.has(row.task_id))
+                    fresh.push([row.task_id, term]);
+            }
+            for (const [taskId, term] of fresh) {
+                if (counted.has(taskId))
+                    continue;
+                counted.add(taskId);
+                if (term === "backgroundAgents")
+                    backgroundAgents += 1;
+                else
+                    sessionResident += 1;
+            }
         }
         catch (err) {
-            n += 1;
-            opts.onUnreadable(sessionId, err);
+            backgroundAgents += 1;
+            reportSafely(["session_resident_background_unreadable_report_threw", sessionId], () => opts.onUnreadable(sessionId, err));
         }
     }
-    return n;
+    return { backgroundAgents, sessionResident };
+}
+function reapStalled(registry, stall) {
+    let count;
+    try {
+        count = registry.reapStaleSessionBackgroundAgents(stall.stallMs);
+    }
+    catch (err) {
+        reportSafely(["background_agent_stall_report_threw"], () => stall.report({ kind: "failed", err }));
+        return;
+    }
+    if (count > 0)
+        reportSafely(["background_agent_stall_report_threw"], () => stall.report({ kind: "reaped", count }));
+}
+function reportSafely(fallbackLine, report) {
+    try {
+        report();
+    }
+    catch (reportErr) {
+        console.error(...fallbackLine, reportErr);
+    }
 }
 //# sourceMappingURL=session-resident-background.js.map

package/dist/session-row.d.ts

@@ -30,7 +30,7 @@ export interface SessionRowTagInput {
  */
 export declare function sessionRowTagOf(row: SessionRowTagInput): string;
 /**
- * 列表行上的 `rowTag` 键(present-iff 这一行可被条件写 = 店有行写口 ∧ 行上有化身):三只店的列表行映射都经它,化身那一格由调用方经
+ * 列表行上的 `rowTag` 键(present-iff 这一行可被条件写 = 店有行写口 ∧ 行上有化身):local 店与 SQL 合成店(两方言一只)的列表行映射都经它,化身那一格由调用方经
  * `incarnationFromCell(…, "absent")` 解码好交进来(`undefined` = 行上没有令牌 ⇒ 键缺席,不铸)。
  */
 export declare function sessionRowTagKey(row: {

package/dist/session-sync-kernel.d.ts

@@ -115,7 +115,7 @@ export declare const STAGED_LOG_BATCH = 500;
 /**
  * The ROW contract a staged entry must meet before it is batched — what the stores need to persist it, not a session-tree invariant
  * (those are core's): the SQL stores' `session_event` columns `entry_id` / `parent_id` are `VARCHAR(64)` and `type` is `VARCHAR(32) NOT NULL`
- * (`plugins/tidb-pool.ts` and `plugins/pg-session-storage.ts`, the DDL both staged appends write into; both dialects count characters, not
+ * (`plugins/tidb-pool.ts` and `stores-sql/pg-session-storage.ts`, the DDL both staged appends write into; both dialects count characters, not
  * UTF-16 units). An entry outside it used to reach the staging write and fail there as a store fault (5xx) — a client's bad data read as an
  * infrastructure failure. The local store holds the same contract (one gate for all stores: a log that cannot sync to SQL is refused at the door).
  */

package/dist/session-workspace.d.ts

@@ -6,7 +6,7 @@
  *  · **判官只有引擎一只**:每条腿起点一帧 `workspace_changed`(`cwd` / `root` / `entered?` / `project?` / `remote`),之后每变一帧;
  *    这条腿属于哪个项目由引擎对检出的 `.sema/project` 记号判一次(带了 `TaskSpec.projectId` 就必须等于记号,
  *    否则整腿拒 `config.project_identity_mismatch`;没有记号时声明就是身份)。本仓**不判**项目、不读记号。
- *  · **会话行只存一格**:`workspace` = 该会话上一条腿**自己的**最后一帧(SQL `session_meta.workspace`;local 店
+ *  · **会话行只存一格**:`workspace` = 该会话上一条腿**自己的**最后一帧(SQL `session_ext.workspace`;local 店
  *    `session-workspaces.json` 那一格)。成员由 {@link SESSION_WORKSPACE_DISPOSITIONS} 一张表定(引擎给帧加成员 ⇒ 表 tsc 红,
  *    门在 `trace/core-keyset-guard.ts` ⑰ 读同一张表)。**唯一写者** = 腿的记录座 {@link createSessionWorkspaceRecorder}
  *    (持流的四条腿逐帧喂同一只;委派子代转上来的帧 —— 带 `parentToolCallId` / `sourceTaskId` / `bgAgentId` —— 不是这条腿的位置,不认)。
@@ -27,7 +27,8 @@
  *    `TaskSpec.memory.projectKey`,按 git 仓库(origin 远端 / 本机路径)键控,与 `.sema/project` 记号无关;引擎 7.58.0 自己也写明
  *    「只声明的身份不改记忆的键」。两者是否该合成一个身份,是另一张设计票。
  *  · 多租户记忆分区(`proj:<租户>/<projectId>`)与登记簿种子读的是**这次提交**的 `projectId`(按提交挑盘,修前即如此),不读行。
- *  · 行上的 `root` / `cwd` / `entered` / `remote` 今天只存不读(会话面读它们归 wire 半场那一车);fork 出的新会话从「没有记录」起。
+ *  · 行上的项目还有一位读者:会话视图 `GET /v1/sessions/:id` 体顶层的 `projectId`(唯一读口 {@link readSessionProjectId},与视图的 `agent` 同一次视图读)。
+ *    `root` / `cwd` / `entered` / `remote` 今天只存不读;fork 出的新会话从「没有记录」起(项目声明按引擎契约每腿都带,fork 的首腿由调用方带上)。
  *  · **只回结果的腿(verify / cascade,含续跑的 verify 臂)不记行**:引擎在组合入口里自己排空内层腿的流,宿主手里没有流,而引擎给组合入口开的
  *    帧座(`onStatusEvent` / `onWiringManifest`)没有这一帧 ⇒ 这条腿的位置与项目到不了行,行停在更早一条腿的那一帧(没有记号的检出里,
  *    下一条不带 `projectId` 的提交续声明的是那一帧声明过的项目)。本仓不替引擎铸「这条腿站在哪里」;要引擎为组合入口开这一帧的座。
@@ -111,6 +112,14 @@ export interface SessionWorkspaceRecorder {
  * 这条腿的关键路径上,池饿死时这条腿本来就停;上界归部署(`DB_QUERY_TIMEOUT_MS`、MySQL 池的排队上界)。local 后端的写不经池。
  */
 export declare function createSessionWorkspaceRecorder(store: SessionWorkspaceStore | undefined, witness: DelegationRootWitness | undefined): SessionWorkspaceRecorder;
+/**
+ * 会话视图的 `projectId` —— **唯一读口**:行上最后一帧的 `project.id`(引擎对这只会话最后一条自己的腿的项目判决,记号判的与声明的同读;
+ * 「哪一种」不上 wire)。店没有这一面 / 没有记录 / 那一帧没有项目 ⇒ `undefined`(调用方不铸键)。两种读不出分两臂,与续声明那一读(`legProjectIdOf`)同读:
+ *  · 店读抛(库连接 / 超时)⇒ 原样上抛 —— 视图读响亮失败(与 `agent` 同律:缺键读作「这台 server 没有说」,不把一次故障说成这句话);
+ *  · 存下的那一格读不懂(被带外改坏)⇒ 店的同一只解码读作没有记录并计一次(F 类 `server.session-workspace.record-degraded`,`op=read`)⇒ 键缺席;
+ *    这只会话的下一条记帧的腿整格重写。
+ */
+export declare function readSessionProjectId(store: SessionWorkspaceStore | undefined, sessionId: string): Promise<string | undefined>;
 /**
  * **这条腿交给引擎的 `TaskSpec.projectId`**(唯一铸点;见文件头第三句)。`submitted` = 这次提交自己带的、已过形状门且折成小写的值
  * (新提交:鉴权口的 `resolvedProjectId`;续跑:持久化体的同一个键)。它在场就不读行。行读失败(库抖)原样上抛 —— 读不到「这只会话的项目」