@sema-agent/server 7.93.0 → 7.93.2

package/USAGE.md

@@ -376,10 +376,32 @@ MODEL_CASCADE_LADDER=deepseek-flash,deepseek-pro   # 目录里的模型名,cheap
   三动作:`store.dir_in_use`=另一个活进程持有该目录 → 停掉它(或换数据根/迁 SQL 后端);
   `store.dir_claiming`=另一进程正在接管崩溃者留下的锁 → **瞬态,稍候重试**(接管方要么完成要么
   自己也被收割);`store.lock_unreadable`=锁文件坏形(无 owner 可解析/嵌套接管残留)→ 人工处置,
-  message 会点名要删的文件,**不要盲删数据根下其它东西**。server 刻意不 catch 这族错(fail-fast:
+  message 会点名要删的文件,**不要盲删数据根下其它东西**。server 刻意不把这族错**吞掉**(fail-fast:
   两进程共用 file 数据目录是禁止形,静默容忍比拒启更坏)。
+  ⚠️ 自 7.93.1 起 `store.dir_in_use` **这一码**多一道有界等待(见下面 `STORE_LOCK_WAIT_MS` 那条):
+  拒启形与文案一格不变,只是拒之前会先在窗内反复重取;另两码(`dir_claiming` / `lock_unreadable`)
+  与非锁类失败**一秒都不等**,原样抛。
   `DB_BACKEND=memory` 并非全无盘:workflow 相关账本仍挂数据根下——多个 memory 形引擎**不要共用**
   数据根/HOME(1.309 起并发 boot 不再拒启,但账本内容级共享仍不受支持)。
+- **`STORE_LOCK_WAIT_MS`(缺省 `60000`,单位 ms)—— 撞上活持锁人时等一会儿再拒**:
+  `DB_BACKEND=local` 的数据根锁被**还活着**的持有者占着时(最常见的成因:壳自己 spawn 引擎,用户关掉壳
+  又立刻重开,旧引擎正在 `DRAIN_GRACE_MS` 的优雅排空 + 停机收尾里,锁要到收尾链尾部的 `backend.close()`
+  才归还),新实例在这个窗内**反复重取**数据根:拿到就照常起动(启动日志一行
+  `store_dir_lock_wait{ownerPid,dir,waitMs}`,**只一行**),到窗仍拿不到才拒启 —— 拒句是原来那一句,
+  额外写明 `waited Nms`(运维据此区分「当场拒」与「等满了才拒」)。等待发生在 `listen` **之前**,语义是
+  「启动慢了 N 秒」而不是「一边服务一边等」。
+  🔴 **方向是多等,不是放行**:窗只决定「拒之前等多久」,任何情形下都不会让第二个写者进同一个数据根。
+  代价 = 两个真独立部署误指同一目录时,那句「被 pid N 占着」要等满窗才出现(编排面的 liveness 探针
+  initialDelay 请按这个窗放宽)。要立刻响 ⇒ `STORE_LOCK_WAIT_MS=0`(逐字回到 7.93.0 的当场拒)。
+  上界不设(愿意等多久是部署自己的事);负值夹到 0 并在启动日志点名。只有 file 后端读它。
+  🔴 **两条取数据根的路是同一条腿、同一只旋钮**:HTTP 服务的 local 臂与 `run-local`(一次性 CLI)共用
+  同一只等待腿 —— **不为前台形留第二套语义**。前台形要「立刻告诉我谁占着」就设 `STORE_LOCK_WAIT_MS=0`,
+  那是文档化的通道,而不是两条路各有一套默认。
+  ⚠️ **裸 boot(没有显式 `DB_BACKEND`)那一形的时序也跟着变**:它的锁冲突走的不是拒启而是既有的
+  「退回内存并 warn」降级臂(`store_db_unreachable_fallback_memory`),所以第二只实例此前**当场**降级、
+  现在要**等满窗**才降级 —— 方向仍是好的(窗内拿到就用上真数据根,而不是静默丢掉持久面),但它是一次
+  真实的启动时长变化。显式 `DB_BACKEND=local` 不走降级臂(拒启),`0` 关掉两形的等待。
+  三问成文见 `docs/DEPLOY-PREREQS.md`。
 - **`RUN_STORE_STRICT_HYDRATE=on|off`(缺省 `off`)—— file 后端 run 账本的 fail-closed 启动门**:
   `DB_BACKEND=local` 的 run 账本在 boot 时把 `<数据根>/runs/` 列一遍重建内存索引。那次 `readdir` 失败
   (权限、挂载丢失、路径被换走)时**缺省行为是照常起动**,只留一行 `file_run_store_hydrate_unreadable`

package/dist/bench/s1/live-deps.js

@@ -342,6 +342,8 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
         "--enable=receive-pack",
         remoteDir,
     ], { stdio: "ignore" });
+    let daemonSpawnError;
+    daemon.on("error", (e) => { daemonSpawnError = e.message; });
     const waitForPort = async () => {
         for (let i = 0; i < 30; i++) {
             const up = await new Promise((resolve) => {
@@ -387,6 +389,7 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
     let res;
     try {
         if (!(await waitForPort())) {
+            console.error(`[s1] git daemon did not come up on 127.0.0.1:${port}${daemonSpawnError ? ` — spawn failed: ${daemonSpawnError}` : ""}`);
             return { ok: false, reports: [], infraFailed: true };
         }
         const seedDir = mkdtempSync(join(tmpdir(), "s1-team-seed-"));

package/dist/boot/fatal-exit.d.ts

@@ -1,3 +1,24 @@
 /** `err` 的 fatal 日志文本:`String(err)` 过形状律一次。纯函数,零副作用。 */
 export declare function buildFatalErrorText(err: unknown): string;
+/**
+ * 进程级 fatal 出口的**唯一一只腿**:同一只 {@link buildFatalErrorText} 产物写两个面,然后按崩溃码退。
+ *
+ * ── 病(S-555,test [ref] P2)────────────────────────────────────────────────────────────────────
+ * 出口过去只有那条 JSON 行。而拒启文案是**多行**的 —— S-547 的列集对账会生成
+ * `ALTER TABLE <表> ADD COLUMN <列定义>;`,它存在的全部理由就是「运维直接粘进 psql」;塞进 JSON 字符串后
+ * 整段变成一串 `\n` 转义,**粘不走**。dist 里也没有 pretty / `isTTY` 分支去把它摊开(有也不该有:出口的
+ * 可读性不该取决于终端是谁)。
+ *
+ * ── 修 ─────────────────────────────────────────────────────────────────────────────────────────
+ * **同一只产物**再原样多行写一份到 stderr。刻意不做的三件:不铸第二份文案(两份措辞必然分叉)、不加
+ * pretty 旋钮(一个只有出错时才走的出口不该有配置面)、JSON 行**照旧**(机读面零回退,scraper 不动)。
+ * 两个面都在 stderr,次序=先机器行后人读段。**这个次序还承重**:`createLogger()` 的构造会装上 stdio 的
+ * EPIPE 无害化监听(见 `observability/logger.ts` 那段注 —— 宿主把 stderr 接管道又先退时,下一次写会发一个
+ * 异步 `'error'`,无监听即致命),所以那条裸 `process.stderr.write` **必须**排在它之后;同步抛由下面的
+ * `try/finally` 兜住。
+ *
+ * 全仓两个 fatal 出口(`main.ts` 的 `main().catch` 与 `run-local.ts` 的同名尾巴)都经这里 —— 后者此前
+ * 连形状律都没过(裸 `String(err)`),两处各写一遍正是「同类不同命」的土壤。
+ */
+export declare function fatalExit(err: unknown): never;
 //# sourceMappingURL=fatal-exit.d.ts.map

package/dist/boot/fatal-exit.js

@@ -1,5 +1,16 @@
 import { redactSecrets } from "../trace/redact.js";
+import { createLogger } from "../observability/logger.js";
 export function buildFatalErrorText(err) {
     return redactSecrets(String(err));
 }
+export function fatalExit(err) {
+    const text = buildFatalErrorText(err);
+    try {
+        createLogger().error("fatal", { err: text });
+        process.stderr.write(text + "\n");
+    }
+    finally {
+        process.exit(1);
+    }
+}
 //# sourceMappingURL=fatal-exit.js.map

package/dist/boot/shutdown.js

@@ -2,6 +2,7 @@ import { Runner, defaultTaskRegistry } from "@sema-agent/core";
 import { writeCrashLast, clearCrashLast, readCrashLast } from "./crash-last.js";
 import { createSighupIdleHandler } from "../sighup-idle.js";
 import { createParentWatch } from "../parent-watch.js";
+import { reapHostForegroundChildren } from "../plugins/host-platform.js";
 import { createEngineLeaseTracker } from "./engine-lease.js";
 import { writeExitLast, readExitLast, clearExitLast } from "./exit-last.js";
 import { isScriptRealmRejection, describeRejectionReason } from "../orchestration/hardened-vm-runner.js";
@@ -30,8 +31,29 @@ export function installShutdownHandlers(ctx) {
         if (dataRoot)
             writeCrashLast(dataRoot, { version, inflight: drainState.inflight?.(), err });
     };
+    const reapOwnChildProcesses = () => {
+        try {
+            const reaped = defaultTaskRegistry.reapAllSessionBackground();
+            if (reaped > 0)
+                logger.info("shutdown_background_reaped", { reaped });
+        }
+        catch (err) {
+            logger.warn("shutdown_background_reap_failed", { err: String(err) });
+        }
+        try {
+            const fg = reapHostForegroundChildren();
+            if (fg.signalled > 0 || fg.alreadyDead > 0)
+                logger.info("shutdown_foreground_reaped", { signalled: fg.signalled, alreadyDead: fg.alreadyDead });
+            if (fg.failed.length > 0)
+                logger.warn("shutdown_foreground_reap_incomplete", { groups: fg.failed });
+        }
+        catch (err) {
+            logger.warn("shutdown_foreground_reap_failed", { err: String(err) });
+        }
+    };
     const onUncaughtException = (err) => {
         try {
+            reapOwnChildProcesses();
             writeLastWords(err);
             console.error(err);
         }
@@ -50,6 +72,7 @@ export function installShutdownHandlers(ctx) {
             return;
         }
         try {
+            reapOwnChildProcesses();
             writeLastWords(err);
             console.error(err);
         }
@@ -92,14 +115,7 @@ export function installShutdownHandlers(ctx) {
         subRunner.sessions.dispose();
         void lspManager?.dispose?.();
         void workflowNotifyJournal?.close?.();
-        try {
-            const reaped = defaultTaskRegistry.reapAllSessionBackground();
-            if (reaped > 0)
-                logger.info("shutdown_background_reaped", { reaped });
-        }
-        catch (err) {
-            logger.warn("shutdown_background_reap_failed", { err: String(err) });
-        }
+        reapOwnChildProcesses();
         void fleetClient?.stop();
         server.close(() => {
             void retentionTeardown.then(() => (backend ? backend.close() : Promise.resolve())).finally(() => process.exit(0));

package/dist/config-catalog.js

@@ -423,6 +423,7 @@ export const CONFIG_CATALOG = [
     r("SSH_PORT", "orchestration", "number", "ssh 端口", { derivedDefaultNote: "缺席 ⇒ 22" }),
     r("SSH_PRIVATE_KEY", "orchestration", "secret", "ssh 私钥(adapter 持有,绝不进 workspace)", { danger: SEC }),
     r("SSH_USER", "orchestration", "string", "ssh 用户(必需件)"),
+    r("STORE_LOCK_WAIT_MS", "store", "number", "local 数据根 LOCK 撞上活持锁人时的有界等待窗(ms;0=当场拒;到窗仍拿不到 ⇒ 原码拒启,永不放行第二个写者)", { staticDefault: "60000", danger: DATA, configKey: "storeLockWaitMs" }),
     r("STORE_PROBE_INTERVAL_MS", "store", "number", "/health 活体 store 后台探针间隔(ms;0=显式关;仅 SQL 后端挂环)", { staticDefault: "15000", configKey: "storeProbeIntervalMs" }),
     r("STREAM_APPROVAL_ADHOC_GRACE_MS", "approval", "number", "流内审批 adhoc 腿窗后宽限(ms;须 window+grace < orphanTtl,破坏形拒启)", { staticDefault: "60000" }),
     r("STREAM_APPROVAL_ADMIT_MAX_PER_OWNER", "approval", "number", "流内审批 per-owner 未决帽", { staticDefault: "256" }),

package/dist/config-types.d.ts

@@ -502,6 +502,12 @@ export interface ServiceConfigFlat {
     /** B1 /health 活体 store 探测:后台缓存探针间隔 ms(STORE_PROBE_INTERVAL_MS;0=显式关,负/非数 boot
      *  响亮拒)。只对 SQL 后端接线;探针原语=backend.dbNowMs()(S10 时钟探针的真 DB 往返,零新 SQL 面)。 */
     storeProbeIntervalMs: number;
+    /** S-553 —— `DB_BACKEND=local` 数据根 `LOCK` 撞上**活**持锁人时的**有界等待窗** ms
+     *  (`STORE_LOCK_WAIT_MS`;缺省 60_000,地板 0 = 7.93.0 的当场拒,**不设上界**)。
+     *  病 = 壳自 spawn 引擎的单机形:旧引擎排空期间一直抱着锁,新引擎当场 fatal ⇒ 用户「刚关掉就再也起不来」。
+     *  失败方向一格不动:到窗仍拿不到 ⇒ 原码 fatal(文案多一句等了多久),**永不**放行第二个写者。
+     *  只有 file 后端读它;判据与偏离说明见 `plugins/store-lock-wait.ts` 顶注。 */
+    storeLockWaitMs: number;
     /** Long-term memory ([ref] S1, clay 2026-07-08): the injection-first file-based memory ENGINE
      *  (core `RunnerDeps.memoryBackend` + `MemoryEngine`) is the ONLY memory plane — the legacy MemoryStore
      *  path (MEMORY_BACKEND/EMBEDDING_* SQL/file note stores) was dropped without migration. Default ON;
@@ -1858,7 +1864,7 @@ export interface ServiceConfigFlat {
     configLocalDir?: string;
 }
 /** 组:store(持久化)—— DB 引擎三态、session 后端、SQL coords、快照 BLOB / SendUserFile 对象存储。 */
-export type ServiceStoreConfig = Pick<ServiceConfigFlat, "sessionBackend" | "sessionCacheTtlSec" | "storeProbeIntervalMs" | "dbBackend" | "dbBackendExplicit" | "localDataRoot" | "runStoreStrictHydrate" | "tidb" | "pg" | "dbQueryTimeoutMs" | "snapshotBlobStore" | "snapshotBlobSqlMaxBytes" | "snapshotBlobAllowSql" | "fileHistory" | "sendUserFile">;
+export type ServiceStoreConfig = Pick<ServiceConfigFlat, "sessionBackend" | "sessionCacheTtlSec" | "storeProbeIntervalMs" | "storeLockWaitMs" | "dbBackend" | "dbBackendExplicit" | "localDataRoot" | "runStoreStrictHydrate" | "tidb" | "pg" | "dbQueryTimeoutMs" | "snapshotBlobStore" | "snapshotBlobSqlMaxBytes" | "snapshotBlobAllowSql" | "fileHistory" | "sendUserFile">;
 /** 组:modelPlane(模型面)—— 网关坐标、Anthropic 路线、韧性旋钮、主/廉价 model entry、role 表、降级梯。 */
 export type ServiceModelPlaneConfig = Pick<ServiceConfigFlat, "gatewayBaseUrl" | "gatewayApiKey" | "gatewayFallbackUrls" | "gatewayMaxRetries" | "anthropic" | "resilience" | "model" | "envModel" | "models" | "modelApiKeyEnv" | "modelApiKeys" | "modelQuotaWeights" | "tiers" | "projects" | "roles" | "atModelAllowlist" | "cascadeLadder" | "degrade">;
 /** 组:approval(审批 / HITL 门)。`directDoorActive` 无 env 解析腿(装配层三域合取的产物),但语义上

package/dist/config.js

@@ -725,6 +725,7 @@ function parseStoreDomain(ctx) {
         sessionBackend,
         sessionCacheTtlSec: numEnv("SESSION_CACHE_TTL_SEC", "300"),
         storeProbeIntervalMs: numEnvBounded("STORE_PROBE_INTERVAL_MS", "15000", 0, 3_600_000),
+        storeLockWaitMs: clampEnvWithWarn("STORE_LOCK_WAIT_MS", "60000", 0),
         dbBackend,
         dbBackendExplicit: dbBackendSet,
         localDataRoot,
@@ -2030,7 +2031,7 @@ function parseA2aServeSkills(raw) {
     });
 }
 const STORE_GROUP_KEYS = [
-    "sessionBackend", "sessionCacheTtlSec", "storeProbeIntervalMs", "dbBackend", "dbBackendExplicit", "localDataRoot",
+    "sessionBackend", "sessionCacheTtlSec", "storeProbeIntervalMs", "storeLockWaitMs", "dbBackend", "dbBackendExplicit", "localDataRoot",
     "runStoreStrictHydrate",
     "tidb", "pg", "dbQueryTimeoutMs", "snapshotBlobStore", "snapshotBlobSqlMaxBytes", "snapshotBlobAllowSql", "fileHistory", "sendUserFile",
 ];

package/dist/main.js

@@ -1,5 +1,4 @@
-import { createLogger } from "./observability/logger.js";
-import { buildFatalErrorText } from "./boot/fatal-exit.js";
+import { fatalExit } from "./boot/fatal-exit.js";
 import { runStage01 } from "./boot/stage-01-config.js";
 import { runStage02 } from "./boot/stage-02-registry-pull.js";
 import { runStage03 } from "./boot/stage-03-store-backend.js";
@@ -23,7 +22,6 @@ async function main() {
     await runStage10(s09);
 }
 void main().catch((err) => {
-    createLogger().error("fatal", { err: buildFatalErrorText(err) });
-    process.exit(1);
+    fatalExit(err);
 });
 //# sourceMappingURL=main.js.map

package/dist/plugins/host-platform.d.ts

@@ -48,6 +48,45 @@ export declare function killTreeSoft(pid: number): void;
 /** Graceful tree kill where the CALLER has no escalation timer of its own (currently unused by the host lane —
  *  exported for parity with core's surface; the bg driver keeps its own HOST_BG_KILL_GRACE_MS ladder). */
 export { killProcessTree };
+/** 登记回执 = 注销的唯一凭据(纯数据;身份即凭据,见簿注)。 */
+export interface ForegroundChildTicket {
+    /** 组领袖 pid = pgid(POSIX `detached:true` 的直接后果)。 */
+    readonly pid: number;
+}
+/** 登记一只自起的前台子进程,返回注销用的回执。 */
+export declare function trackHostForegroundChild(pid: number): ForegroundChildTicket;
+/** 注销(`exit` / settle / 领养移交)。按回执身份删 ⇒ 幂等,且**绝不**碰同号的其它登记。 */
+export declare function untrackHostForegroundChild(ticket: ForegroundChildTicket): void;
+/** 一次前台收割的读数。三格分开是**刻意**的:`alreadyDead` 是想要的结果(不是失败),`failed` 是**真的**
+ *  没收上来 —— 两者混成一个数就等于把后者静默掉([ref]:这条腿上不许有安静的兜底)。 */
+export interface ForegroundReapReading {
+    /** 真发出了杀伤信号的组数。 */
+    readonly signalled: number;
+    /** `ESRCH` —— 组已经不在了。信号的语义就是「让它死」,它已经死了 ⇒ 记数,不报警。 */
+    readonly alreadyDead: number;
+    /** 其余拒因,逐条 `pid:code`。本模块没有 logger,所以**交回调用方响亮记下**(它有)。 */
+    readonly failed: readonly string[];
+}
+/**
+ * 收割簿上全部前台子进程组。返回**发出**信号的读数,不是确认死亡数 —— 确认要等,而本函数的调用点之一
+ * 是 uncaught 出口。
+ *
+ * **同步形、一次到位、不等宽限**:两个调用点(`hardShutdown` / uncaught 双钩)都紧挨着 `process.exit`,
+ * `await` 一个宽限梯就是把收割赌在一个永远等不到的续段上。上界 = 簿上条数 × 一次 `kill(-pid)` syscall
+ * (簿条数被 host lane 的在飞 turn 数界住),没有定时器、没有 promise。
+ *
+ * 🔴 **为什么是 `killTreeHard` 而不是 SIGTERM**(codex 对抗复审 [high],亲跑复现后改):软鞍的语义是
+ * 「给它一个收尾窗,到点我再升级」,而这两个调用点之后**没有任何人在场**去升级 —— 一个
+ * `trap '' TERM` 的组收到 SIGTERM 后 `kill` 不抛(实测 `signalled:1, failed:[]`、随后仍然在跑),于是
+ * 「已收割」的读数是**假的**,孤儿照旧永久存活;win32 的软鞍对普通 console tree 更是明确杀不掉任何东西
+ * (见 {@link killTreeSoft} 注)。且本仓对**前台 exec** 的既有杀伤姿势(abort / timeout / 流被放弃)
+ * 一律就是 `killTreeHard` —— 收割用**同一只**,不新造一种只能兑现一半的姿势(规则集更小,不是更大)。
+ * 代价如实写:一条行为良好的命令在这里拿不到收尾窗;它换来的是「引擎死了,它起的命令一定也死」这句话
+ * 真的成立。后台腿的宽限梯不受影响(那条腿有自己的属主,且不在本簿里)。
+ */
+export declare function reapHostForegroundChildren(): ForegroundReapReading;
+/** 测试面:簿上现存条数(产品面没有消费者 —— 收割腿只读它自己那只 Set)。 */
+export declare function liveHostForegroundChildCountForTest(): number;
 /**
  * win32 env-key case collapse (design D1). Windows env keys are case-insensitive; Node hands the
  * object to CreateProcess as-is, so a case-sensitive merge that produced BOTH `Path` (inherited) and `PATH`

package/dist/plugins/host-platform.js

@@ -54,6 +54,38 @@ export function killTreeSoft(pid) {
     process.kill(-pid, "SIGTERM");
 }
 export { killProcessTree };
+const liveHostForegroundGroups = new Set();
+export function trackHostForegroundChild(pid) {
+    const ticket = { pid };
+    liveHostForegroundGroups.add(ticket);
+    return ticket;
+}
+export function untrackHostForegroundChild(ticket) {
+    liveHostForegroundGroups.delete(ticket);
+}
+export function reapHostForegroundChildren() {
+    let signalled = 0;
+    let alreadyDead = 0;
+    const failed = [];
+    for (const { pid } of liveHostForegroundGroups) {
+        try {
+            killTreeHard(pid);
+            signalled++;
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === "ESRCH")
+                alreadyDead++;
+            else
+                failed.push(`${pid}:${code ?? String(err)}`);
+        }
+    }
+    liveHostForegroundGroups.clear();
+    return { signalled, alreadyDead, failed };
+}
+export function liveHostForegroundChildCountForTest() {
+    return liveHostForegroundGroups.size;
+}
 export function collapseWin32EnvKeys(env) {
     if (!IS_WIN32)
         return env;

package/dist/plugins/remote-env-host.js

@@ -7,7 +7,7 @@ import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdi
 import { StringDecoder } from "node:string_decoder";
 import { armPipeDestroyGrace, numEnvOr, SYMLINK_CHAIN_MAX_HOPS } from "./remote-shell.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
-import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, collapseWin32EnvKeys } from "./host-platform.js";
+import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, collapseWin32EnvKeys, trackHostForegroundChild, untrackHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, ExecutionError, RemoteExecutionError, scrubSecretEnv, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
 import { recordSecretEnvScrub } from "../observability/secret-env-scrub.js";
@@ -241,9 +241,9 @@ export class RemoteHostExecutionEnv {
                         throw new BackgroundShellError("spawn_failed", e instanceof Error ? e.message : String(e), e);
                     }
                     const pid = child.pid;
+                    child.on("error", () => ctx.onTerminal(true));
                     if (pid != null) {
                         child.on("close", (code, signal) => ctx.onTerminal(false, code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0)));
-                        child.on("error", () => ctx.onTerminal(true));
                         child.unref();
                     }
                     await outFh.close().catch(() => { });
@@ -403,10 +403,15 @@ export class RemoteHostExecutionEnv {
                 env: this.mergeEnv(options?.env),
                 ...spawnGroupOptions(),
             });
+            const ticket = child.pid != null ? trackHostForegroundChild(child.pid) : undefined;
+            if (ticket)
+                child.once("exit", () => untrackHostForegroundChild(ticket));
             const finish = (r) => {
                 if (settled)
                     return;
                 settled = true;
+                if (ticket)
+                    untrackHostForegroundChild(ticket);
                 clearTimeout(timer);
                 options?.abortSignal?.removeEventListener("abort", onAbort);
                 removeDetachListener?.();
@@ -455,6 +460,8 @@ export class RemoteHostExecutionEnv {
                 if (forceSettleTimer)
                     clearTimeout(forceSettleTimer);
                 options?.abortSignal?.removeEventListener("abort", onAbort);
+                if (ticket)
+                    untrackHostForegroundChild(ticket);
                 settled = true;
                 resolve(ok({ stdout: seedOut, stderr: seedErr, exitCode: 0, detached: { shellId } }));
             };
@@ -521,6 +528,7 @@ export class RemoteHostExecutionEnv {
             const errBuf = new RollingTailBuffer();
             let settled = false;
             let handedOver = false;
+            let ticket;
             let pump;
             let drainTimer;
             const cursor = { out: 0, err: 0 };
@@ -613,6 +621,8 @@ export class RemoteHostExecutionEnv {
                     clearInterval(pump);
                     pump = undefined;
                 }
+                if (ticket)
+                    untrackHostForegroundChild(ticket);
                 if (drainTimer) {
                     clearTimeout(drainTimer);
                     drainTimer = undefined;
@@ -665,6 +675,8 @@ export class RemoteHostExecutionEnv {
                 cleanupSpool();
                 throw e;
             }
+            if (child.pid != null)
+                ticket = trackHostForegroundChild(child.pid);
             closeSpoolFds();
             child.on("error", (e) => {
                 finish({ ok: false, error: new ExecutionError("spawn_error", `host spawn failed: ${e.message}`) });
@@ -753,6 +765,8 @@ export class RemoteHostExecutionEnv {
                 settleFromTermination(code, signal);
             });
             child.on("exit", (code, signal) => {
+                if (ticket)
+                    untrackHostForegroundChild(ticket);
                 exited = true;
                 drainTimer = setTimeout(() => settleFromTermination(code, signal), EXIT_SETTLE_DRAIN_MS);
                 drainTimer.unref?.();
@@ -797,6 +811,9 @@ export class RemoteHostExecutionEnv {
         const signalReady = () => { const w = wake; wake = undefined; w?.(); };
         const sh = hostShell();
         const child = spawn(sh.shell, [...sh.args, command], { cwd, env: this.mergeEnv(options?.env), ...spawnGroupOptions() });
+        const ticket = child.pid != null ? trackHostForegroundChild(child.pid) : undefined;
+        if (ticket)
+            child.once("exit", () => untrackHostForegroundChild(ticket));
         let pipeDestroyTimer;
         const kill = () => {
             try {
@@ -831,6 +848,8 @@ export class RemoteHostExecutionEnv {
         child.on("close", (code, signal) => {
             if (pipeDestroyTimer)
                 clearTimeout(pipeDestroyTimer);
+            if (ticket)
+                untrackHostForegroundChild(ticket);
             if (finished)
                 return;
             exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 0) : 1);
@@ -906,6 +925,8 @@ export class RemoteHostExecutionEnv {
             if (wallTimer)
                 clearTimeout(wallTimer);
             options?.signal?.removeEventListener("abort", onAbort);
+            if (ticket)
+                untrackHostForegroundChild(ticket);
         }
     }
     async absolutePath(p) {

package/dist/plugins/store-backend.js

@@ -8,6 +8,7 @@ import { FileOutcomeSink } from "./file-outcome-sink.js";
 import { TiDBWorkflowRunStore, TiDBWorkflowCompletionInbox, TiDBWorkflowNotifyJournalStore, TiDBWorkflowAgentSessionIndex, PgWorkflowRunStore, PgWorkflowCompletionInbox, PgWorkflowNotifyJournalStore, PgWorkflowAgentSessionIndex } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
+import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
 import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
 import { LocalSessionStore } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
@@ -215,7 +216,7 @@ class LocalBackend {
         this.onWarn = onWarn;
         this.onError = onError;
         try {
-            this.fileBackend = new FileStorageBackend({
+            this.fileBackend = acquireLocalBackendWithWait(() => new FileStorageBackend({
                 root,
                 ...(config.fileHistory !== undefined ? { fileHistory: config.fileHistory } : {}),
                 onCorruptRead: (info) => this.onWarn?.("file_store_corrupt_read", {
@@ -228,7 +229,7 @@ class LocalBackend {
                         "layer (deployment policy / hooks / shell gate still applied); session repo = a listing silently omitted " +
                         "rows; file-history = a rewind boundary or scope read as missing. Inspect the named path before deciding.",
                 }),
-            });
+            }), config.storeLockWaitMs, (fields) => this.onWarn?.("store_dir_lock_wait", { ...fields }));
         }
         catch (e) {
             if (e instanceof AdoptionError)

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

@@ -0,0 +1,23 @@
+/** 轮询节拍。250ms:比人感知门槛粗、比最短真等待窗(壳重启窗 1-3s)细一个数量级。 */
+export declare const STORE_LOCK_POLL_MS = 250;
+/** 进入等待腿时的**一次性**披露(不刷屏:结构上只在第一次撞锁时调一次,不是靠一个 flag 挡)。 */
+export type StoreLockWaitSink = (fields: {
+    readonly ownerPid: number;
+    readonly dir: string;
+    readonly waitMs: number;
+}) => void;
+/** 时钟两面。`sleep` 是**同步**的(理由见顶注);两面都是形参,判据不靠真时间。 */
+export interface StoreLockWaitClock {
+    now(): number;
+    sleep(ms: number): void;
+}
+/**
+ * 取数据根(= 跑一次 `construct()`);撞上活持锁人且窗为正 ⇒ 在窗内反复重取,到窗仍取不到 ⇒ 原码 fatal。
+ *
+ * @param construct 取数据根的那一次构造(本仓唯一调用点:`store-backend.ts` 的 local 臂,它在那里构造 `FileStorageBackend`)。
+ *                  **必须**可重入:core 先取锁后建店,取不到时零副作用(顶注已亲读核实)。
+ * @param waitMs    `STORE_LOCK_WAIT_MS`。`> 0` 才等;`0` / 非数 ⇒ 7.93.0 的当场拒逐字同形。
+ * @param onWait    进入等待腿的一次性披露口。
+ */
+export declare function acquireLocalBackendWithWait<T>(construct: () => T, waitMs: number, onWait: StoreLockWaitSink, clock?: StoreLockWaitClock): T;
+//# sourceMappingURL=store-lock-wait.d.ts.map

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

@@ -0,0 +1,39 @@
+import { dirname } from "node:path";
+import { FileStoreLockError } from "@sema-agent/core";
+export const STORE_LOCK_POLL_MS = 250;
+const REAL_CLOCK = {
+    now: () => performance.now(),
+    sleep: (ms) => void Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms),
+};
+function liveOwnerPidOf(err) {
+    if (!(err instanceof FileStoreLockError))
+        return undefined;
+    if (err.code !== "store.dir_in_use")
+        return undefined;
+    return err.ownerPid;
+}
+export function acquireLocalBackendWithWait(construct, waitMs, onWait, clock = REAL_CLOCK) {
+    let startedAt;
+    for (;;) {
+        try {
+            return construct();
+        }
+        catch (err) {
+            const ownerPid = liveOwnerPidOf(err);
+            if (ownerPid === undefined || !(waitMs > 0))
+                throw err;
+            const lockErr = err;
+            if (startedAt === undefined) {
+                startedAt = clock.now();
+                onWait({ ownerPid, dir: dirname(lockErr.lockPath), waitMs });
+            }
+            const waitedMs = clock.now() - startedAt;
+            if (waitedMs >= waitMs) {
+                throw new FileStoreLockError(lockErr.code, `${lockErr.message} — waited ${Math.round(waitedMs)}ms for it to release the directory ` +
+                    `(STORE_LOCK_WAIT_MS=${waitMs}); it is still holding it`, lockErr.lockPath, lockErr.ownerPid);
+            }
+            clock.sleep(Math.min(STORE_LOCK_POLL_MS, waitMs - waitedMs));
+        }
+    }
+}
+//# sourceMappingURL=store-lock-wait.js.map

package/dist/run-local.js

@@ -17,6 +17,7 @@ import { taskWallClockSec } from "./task-workflow.js";
 import { applyCatalogToSource } from "./capabilities/center-prompts.js";
 import { validatePromptsDomain, CORE_ENGINE_VERSION } from "./prompts-domain-validate.js";
 import { buildUnpricedCeilingNotice, loadConfig, logConfigDiagnostics, parseNumOrFailNonNegative } from "./config.js";
+import { acquireLocalBackendWithWait } from "./plugins/store-lock-wait.js";
 import { createConfigProvider } from "./config-provider.js";
 import { applyEffective, applyCenterReadFace, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./config-center/facade.js";
 import { hostExecutionEnvFactory } from "./plugins/remote-env-host.js";
@@ -41,6 +42,7 @@ import { createOrgMemoryAdmissionWiring } from "./boot/org-memory.js";
 import { createPermissionDeniedMeter } from "./observability/tool-trace.js";
 import { createKeyResolver } from "./key-resolver.js";
 import { createLogger } from "./observability/logger.js";
+import { fatalExit } from "./boot/fatal-exit.js";
 import { createMetrics } from "./observability/metrics.js";
 import { installSecretEnvScrubRecorder } from "./observability/secret-env-scrub.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
@@ -253,7 +255,7 @@ export async function runLocal(argv, deps = {}) {
     const pricing = buildPricing(config.models);
     let fileBackend;
     try {
-        fileBackend = new FileStorageBackend({
+        fileBackend = acquireLocalBackendWithWait(() => new FileStorageBackend({
             root,
             ...(config.fileHistory !== undefined ? { fileHistory: config.fileHistory } : {}),
             onCorruptRead: (info) => logger.warn("file_store_corrupt_read", {
@@ -266,7 +268,7 @@ export async function runLocal(argv, deps = {}) {
                     "layer (deployment policy / hooks / shell gate still applied); session repo = a listing silently omitted " +
                     "rows; file-snapshot = a snapshot or scope read as missing. Inspect the named path before deciding.",
             }),
-        });
+        }), config.storeLockWaitMs, (fields) => logger.warn("store_dir_lock_wait", { ...fields }));
     }
     catch (e) {
         printErr(`cannot open local data dir ${root}: ${e instanceof Error ? e.message : String(e)}`);
@@ -574,9 +576,6 @@ function isMainModule() {
     }
 }
 if (isMainModule()) {
-    void main().catch((err) => {
-        createLogger().error("fatal", { err: String(err) });
-        process.exit(1);
-    });
+    void main().catch((err) => fatalExit(err));
 }
 //# sourceMappingURL=run-local.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.93.0",
+  "version": "7.93.2",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -74,7 +74,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "11.2.0",
+    "@sema-agent/sdk": "11.2.1",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",