@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/fork-routing-session-store.d.ts

@@ -1,9 +1,39 @@
+/**
+ * ForkRoutingSessionStore — the subRunner's session backing after core 1.350's fork 终修([1364]①/[1367]①).
+ *
+ * 问题形:core 的 `hostSessionFork` 在 HOST runner 的店里 fork,fork 子任务带 `requireExistingSession:true`
+ * 在 opts.runner(subRunner)上执行——subRunner 拆店时子任务查不到刚 fork 出的会话,响亮失败
+ * `resume.session_not_found`(cli 真机复现)。
+ *
+ * 但把 host durable 店**整个**给 subRunner(第一版修)被 codex 判两 high:普通子任务(council 镜头/
+ * team/子代理)会把每次运行都铸成 committed durable 会话——sweepStagingSessions 只扫**无 session_meta**
+ * 的 staging 弃置行,committed 子会话没有 reaper=无界增长;且进 owner 过滤的会话枚举(零 run 的内部
+ * 会话污染 /v1/sessions)。
+ *
+ * 此包装店按**会话的真居所**路由,两边语义都保住:
+ *  - `acquire(id, {requireExisting})`(fork 子 + retained-child resume 的形)→ **host 店优先**,miss 落
+ *    transient(retained 瞬态子的 resume 仍走私店);两边都 miss=抛 host 侧错误(fail-loud 原语义)。
+ *  - `acquire()`(无 id=普通子任务铸新会话)→ **transient**(throwaway 姿势保留:council/team 子会话
+ *    不落 durable、不进枚举、TTL 自清)。
+ *  - `acquire(id)`(带 id 不 requireExisting)→ 已有路由按路由走;未知 id 落 transient(claim-create
+ *    绝不打到 durable 店——那是 authorizer 的职权)。
+ *  - `fork(sourceId)` → 源在哪店在哪店 fork(路由未知时 host 先试,null 再 transient);新 id 记路由。
+ *  - `list`/`size`/`dispose` = transient 侧(host 店归 main runner 所有;不双列、不双清)。
+ *
+ * 路由表 LRU 上限 {@link ROUTE_MAX}:满额逐最老(refresh-on-use);被逐后下次 `acquire` 按上述规则重derive
+ * (requireExisting 的 host-first 重试仍落对店),中途 touch/noteTaskRun 缺路由=落 transient(no-op 级)。
+ */
 import type { SessionStore, AcquiredSession, SessionStoreSummary } from "@sema-agent/core";
 export declare class ForkRoutingSessionStore implements SessionStore {
     private readonly host;
     private readonly transient;
     private readonly route;
+    /** pin 时的店归属——unpin 恒回同店(LRU 逐出不拆对,见 pin/unpin)。 */
     private readonly pinnedAt;
+    /** [1593] 晋升名册(探针 Finding A 修):已 promoteToHost 的 id **永久**钉 host——路由表会被 LRU
+     *  逐出,而私店的 forget 只清 entries 缓存行、底层 repo 行不清且 sweep 扫不到(core session-store.js
+     *  亲读),逐出后 transient-first 的 requireExisting 会把陈旧快照端回给 revive。本集不逐出(上界=
+     *  parked 子代数,天然小);pick/acquire 首查。 */
     private readonly promoted;
     constructor(host: SessionStore, transient: SessionStore);
     private remember;
@@ -18,6 +48,23 @@ export declare class ForkRoutingSessionStore implements SessionStore {
     unpin(sessionId: string): void | Promise<void>;
     noteTaskRun(sessionId: string, taskId: string): void | Promise<void>;
     list(): Promise<SessionStoreSummary[]>;
+    /**
+     * [1593] 子代 park 晋升:把住在 transient(TTL)店的子会话**整树拷贝**进 host durable 店,然后
+     * 让该 id 从此路由到 host——`ensureChildSessionDurable` 的「主动晋升」半场(1.263 的只查不迁形在
+     * 拆店生产形下恒否决 park:子会话从不在 host 店,core 收 veto 即 expire checkpoint + settle failed,
+     * cli 真机 14ms~2s expired 即此)。
+     *
+     * 三步缺一不可:
+     *  1. 拷贝:transient 读整树(getEntries)+ 源 leaf → host 店 acquire(id)(durable 店的 acquire
+     *     缺行即建行)→ storage.appendEntry 逐条 verbatim(重复 id 容忍=幂等续迁:上次晋升半途崩的
+     *     残留行跳过)→ setLeafId(源 leaf)(分支树以源为准,不信 append 推进的 leaf)。
+     *  2. transient.forget(id):`requireExisting` 的 acquire 是 **transient-first**(F-7 裁定)——私店
+     *     副本不移除,revive 会续写进 1h TTL 副本,durable park 名存实亡。
+     *  3. 路由记 host(此后 touch/pin/release 全走 host;pinnedAt 若记着 transient 一并改写,
+     *     unpin 不落错店)。
+     *
+     * 已在 host(路由或真行)⇒ 幂等直返。两店都无此会话 ⇒ 抛(调用方=park veto,诚实 fail-closed)。
+     */
     promoteToHost(sessionId: string): Promise<void>;
     fork(sourceId: string, owner?: string | null): Promise<string | null>;
     get size(): number;

package/dist/plugins/fork-routing-session-store.js

@@ -3,11 +3,19 @@ export class ForkRoutingSessionStore {
     host;
     transient;
     route = new Map();
+    /** pin 时的店归属——unpin 恒回同店(LRU 逐出不拆对,见 pin/unpin)。 */
     pinnedAt = new Map();
+    /** [1593] 晋升名册(探针 Finding A 修):已 promoteToHost 的 id **永久**钉 host——路由表会被 LRU
+     *  逐出,而私店的 forget 只清 entries 缓存行、底层 repo 行不清且 sweep 扫不到(core session-store.js
+     *  亲读),逐出后 transient-first 的 requireExisting 会把陈旧快照端回给 revive。本集不逐出(上界=
+     *  parked 子代数,天然小);pick/acquire 首查。 */
     promoted = new Set();
     constructor(host, transient) {
         this.host = host;
         this.transient = transient;
+        // backlog(hasSessionFork 恒真):两 backing 都无 fork 面时,包装店的 fork 方法**摘除**——core 的
+        // fork 门(hasSessionFork(opts.runner.sessions))才能诚实报 fork.unavailable,而不是放行后折叠成
+        // 误导性的「source not found」。现三 backing 均有 fork,此臂为接入无 fork durable backend 备。
         if (host.fork === undefined && transient.fork === undefined) {
             this.fork = undefined;
         }
@@ -23,10 +31,10 @@ export class ForkRoutingSessionStore {
     }
     pick(id) {
         if (this.promoted.has(id))
-            return this.host;
+            return this.host; // [1593] 晋升名册优先(路由可被 LRU 逐出,名册不逐)
         const r = this.route.get(id);
         if (r !== undefined)
-            this.remember(id, r);
+            this.remember(id, r); // refresh recency
         return r === "host" ? this.host : this.transient;
     }
     async acquire(sessionId, opts) {
@@ -36,6 +44,8 @@ export class ForkRoutingSessionStore {
             return a;
         }
         if (this.promoted.has(sessionId)) {
+            // [1593] 晋升名册:恒走 host——绝不能让 transient-first 把 forget 后仍活在私店 repo 里的陈旧
+            // 快照端给 revive(探针 Finding A)。
             const a = await this.host.acquire(sessionId, opts);
             this.remember(sessionId, "host");
             return a;
@@ -46,6 +56,10 @@ export class ForkRoutingSessionStore {
             return a;
         }
         if (opts?.requireExisting) {
+            // PAIR-REVIEW F-7(codex 过审):**transient-first**——retained 瞬态子 resume 直达私店;fork 子恒不在
+            // transient(miss)→ fallback host 命中,语义不变。顺序反转封住 F-7 组合链:同 id 在两店并存时
+            // (child uuid 被同租户误提交到主 API 而 host 店 claim-create 出空壳),真子会话(transient)赢,
+            // 空壳不遮蔽。双 miss 抛 host 侧错误(响亮,fail-closed 到「真不存在」)。
             let transientErr;
             try {
                 const a = await this.transient.acquire(sessionId, opts);
@@ -65,6 +79,7 @@ export class ForkRoutingSessionStore {
                 throw hostErr;
             }
         }
+        // 带 id 但不要求已存在:claim-create 只允许落 transient(durable 店的 claim-create 是 authorizer 的职权)。
         const a = await this.transient.acquire(sessionId, opts);
         this.remember(sessionId, "transient");
         return a;
@@ -76,11 +91,16 @@ export class ForkRoutingSessionStore {
         return this.pick(sessionId).release(sessionId);
     }
     forget(sessionId) {
+        // PAIR-REVIEW F-8:forget=显式移除 → 路由项同步清(死 id 不再占 LRU 槽挤活路由);release 保留
+        // 路由(retained 子 resume 会再 acquire,清了只是多付一次 derive)。
         const target = this.pick(sessionId);
         this.route.delete(sessionId);
         return target.forget?.(sessionId);
     }
     pin(sessionId) {
+        // backlog 潜伏钉(pin/unpin 路由不对称):pin 时 refresh 路由近度(remember 已在 pick 内做)+把
+        // pinned id 记入独立集合——unpin 优先按 pin 时的店走,LRU 逐出不再能把 pin/unpin 拆到两家店
+        // (host 店永久 pinned 不可回收的潜伏形就此封死)。
         const r = this.route.get(sessionId);
         if (r !== undefined)
             this.pinnedAt.set(sessionId, r);
@@ -100,6 +120,23 @@ export class ForkRoutingSessionStore {
     list() {
         return this.transient.list?.() ?? Promise.resolve([]);
     }
+    /**
+     * [1593] 子代 park 晋升:把住在 transient(TTL)店的子会话**整树拷贝**进 host durable 店,然后
+     * 让该 id 从此路由到 host——`ensureChildSessionDurable` 的「主动晋升」半场(1.263 的只查不迁形在
+     * 拆店生产形下恒否决 park:子会话从不在 host 店,core 收 veto 即 expire checkpoint + settle failed,
+     * cli 真机 14ms~2s expired 即此)。
+     *
+     * 三步缺一不可:
+     *  1. 拷贝:transient 读整树(getEntries)+ 源 leaf → host 店 acquire(id)(durable 店的 acquire
+     *     缺行即建行)→ storage.appendEntry 逐条 verbatim(重复 id 容忍=幂等续迁:上次晋升半途崩的
+     *     残留行跳过)→ setLeafId(源 leaf)(分支树以源为准,不信 append 推进的 leaf)。
+     *  2. transient.forget(id):`requireExisting` 的 acquire 是 **transient-first**(F-7 裁定)——私店
+     *     副本不移除,revive 会续写进 1h TTL 副本,durable park 名存实亡。
+     *  3. 路由记 host(此后 touch/pin/release 全走 host;pinnedAt 若记着 transient 一并改写,
+     *     unpin 不落错店)。
+     *
+     * 已在 host(路由或真行)⇒ 幂等直返。两店都无此会话 ⇒ 抛(调用方=park veto,诚实 fail-closed)。
+     */
     async promoteToHost(sessionId) {
         if (this.promoted.has(sessionId))
             return;
@@ -112,17 +149,24 @@ export class ForkRoutingSessionStore {
             src = await this.transient.acquire(sessionId, { requireExisting: true });
         }
         catch {
+            // 私店无此会话:可能已在 host(直查确认=幂等),否则如实抛(host 侧错误响亮上浮)
             const probe = await this.host.acquire(sessionId, { requireExisting: true });
             await this.host.release(probe.sessionId);
             this.promoted.add(sessionId);
             this.remember(sessionId, "host");
             return;
         }
+        // ⚠️ 私店源在此**不 release**:TtlSessionStore.release 对非 pinned 会话=整删(F3 教训)——拷贝
+        // 失败时删源=毁掉仍在跑/仍可赎回的子会话。成功路径由下方 forget(纯 entries 移除,无 repo 删)收尾;
+        // 失败路径源原样留活,veto 如实上浮。
         const entries = await src.session.getEntries();
         const leaf = await src.session.getLeafId();
         const dst = await this.host.acquire(sessionId);
         try {
             const storage = dst.session.getStorage();
+            // 探针 Finding B 修:core 各 storage 的 appendEntry 对重复 id **不抛不查**(storage-base 亲读)
+            // ——靠 try/catch 实现幂等是空想,断续晋升会把同 id 双写成脏树(且脏树会被 import-validate 的
+            // 重复 id 门拒)。真幂等 = 先读 dst 现存 id 集,set-diff 后只补缺。
             const existing = new Set((await dst.session.getEntries()).map((e) => e.id));
             for (const entry of entries) {
                 if (existing.has(entry.id))
@@ -141,6 +185,10 @@ export class ForkRoutingSessionStore {
             await this.transient.forget?.(sessionId);
         }
         catch {
+            // forget 失败不阻断晋升。⚠️ forget 本就只清私店的 entries 缓存行——底层 repo 行不清、sweep 也
+            // 扫不到(探针 Finding A 取证),陈旧快照在私店**永生**;对 revive 的真防线是上面的晋升名册
+            // (promoted 集恒指 host,不随路由 LRU 逐出),forget 只是缩内存的 best-effort。transient.pinned
+            // 可能残留该 id(forget 不清 pin 集)——unpin 已随 pinnedAt 改写落 host,残留仅是空集合项。
         }
         if (this.pinnedAt.get(sessionId) === "transient")
             this.pinnedAt.set(sessionId, "host");
@@ -167,7 +215,7 @@ export class ForkRoutingSessionStore {
         return this.transient.size;
     }
     dispose() {
-        return this.transient.dispose();
+        return this.transient.dispose(); // host 店归 main runner 所有,绝不在此清
     }
 }
 //# sourceMappingURL=fork-routing-session-store.js.map

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

@@ -1,19 +1,88 @@
+/**
+ * Host-lane PLATFORM seam (DESIGN-windows-native.md, FINAL r3) — the ONE place the host exec adapter's
+ * POSIX/win32 differences live, so `remote-env-host.ts` stays a single code path with platform-gated leaves.
+ *
+ * 🔴 Iron invariant (design §4.1): the POSIX path is BYTE-IDENTICAL to the pre-Windows code — every helper is
+ * `win32 ? new : exactly-what-the-inline-code-did` (same syscall, same throw behavior). Never "improve" POSIX
+ * here; the existing full test suite is the regression net.
+ *
+ * win32 semantics (design D1-D4):
+ *  - shell   = Git Bash via core 1.224 `getShellConfig` (WSL-launcher-filtered — the `System32\bash.exe`
+ *              trap). Fail-LOUD when absent; never silently degrade to cmd (D1).
+ *  - kill    = core 1.224 `signalProcessTree` (taskkill /T, /F for hard). Soft is a no-op for console trees
+ *              (taskkill errors "can only be terminated forcefully") — the SIGTERM→grace→SIGKILL ladder is
+ *              effectively delay→hard-kill on win32; accepted, CC-identical (D2).
+ *  - spawn   = `detached:false` + `windowsHide:true` (no console window; no POSIX process group — the kill
+ *              side uses the tree, not the group) (D3).
+ *  - env     = case-insensitive key collapse before spawn (win32 env keys are case-insensitive; a `Path`+`PATH`
+ *              pair from case-sensitive Object.assign reaches CreateProcess as ONE undefined-which
+ *              entry). Canonical casing = the first-seen key (process.env's native casing wins since the
+ *              inherit base is spread first).
+ *
+ * ⚠️ The win32 branches are UNVERIFIED on a real machine until S5 (Windows CI runner) — design D5 discipline:
+ * structural tests only on mac/Linux; behavior-level bite happens on the first Windows-runner green.
+ */
 import { killProcessTree } from "@sema-agent/core";
 export declare const IS_WIN32: boolean;
 export interface HostShell {
     shell: string;
     args: string[];
 }
+/**
+ * Resolve the host shell ONCE per process (cached). POSIX resolves synchronously to `/bin/sh` — zero behavior
+ * change. win32 defers to core's `getShellConfig` (explicit `HOST_SHELL_PATH` override → Git-for-Windows
+ * install dirs → PATH `bash.exe` with the WSL-launcher filter) and THROWS a self-explaining error when no
+ * usable bash exists (design D1 fail-loud: "install Git for Windows", never a silent cmd fallback).
+ *
+ * Call sites: `shellReady()` awaits this once (all exec/bg/stream spawns are behind it), then the spawn sites
+ * read the cached value synchronously via {@link hostShell}.
+ */
 export declare function resolveHostShell(): Promise<HostShell>;
+/** Synchronous read of the resolved shell — valid only AFTER {@link resolveHostShell} settled (the spawn sites
+ *  are all behind `shellReady()`, which awaits it). POSIX never needs the async step. Throws on a mis-ordered
+ *  call (a programming bug, not an operator condition — fail loud, not /bin/sh-on-windows). */
 export declare function hostShell(): HostShell;
+/** test-only: reset the shell caches (each test can re-drive resolution). */
 export declare function resetHostShellCacheForTest(): void;
+/** Per-platform spawn options for a group-killable child (design D3).
+ *  POSIX: `detached:true` — child becomes its own process-group leader (pgid === pid) so `kill(-pid)` reaps the
+ *  whole group. BYTE-IDENTICAL to the previous inline `detached: true`.
+ *  win32: `detached:false` (a detached child opens a console; there is no killable POSIX group either way —
+ *  the kill side uses taskkill's tree) + `windowsHide:true` (no flashing console window). */
 export declare function spawnGroupOptions(): {
     detached: boolean;
     windowsHide?: boolean;
 };
+/**
+ * HARD kill of the child's whole tree (design D2). POSIX = `process.kill(-pid, "SIGKILL")` — byte-identical,
+ * INCLUDING the throw on a dead group (ESRCH): every call site already wraps in its own try/catch with its own
+ * fallback (e.g. `child.kill("SIGKILL")`), and that structure must not change.
+ * win32 = core `signalProcessTree(pid,"SIGKILL")` → `taskkill /F /T` (never throws — fire-and-forget spawn).
+ */
 export declare function killTreeHard(pid: number): void;
+/**
+ * SOFT kill (design D2 — the bg KillShell/timeout-wall first rung; the caller owns the grace→hard escalation
+ * timer, unchanged). POSIX = `process.kill(-pid, "SIGTERM")` byte-identical (throws on dead group — the caller
+ * treats that as "already dead, skip escalation"). win32 = `taskkill /T` without /F — which for a typical
+ * all-console tree ERRORS AND KILLS NOTHING: the ladder degrades to delay→hard-kill there;
+ * accepted + documented (CC-identical). It never throws, so the caller's "already dead → return" branch never
+ * fires on win32 — the escalation timer always arms, which is exactly what we want given soft is a no-op.
+ */
 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 };
+/**
+ * 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`
+ * (caller override) yields one-of-them-undefined-which in the child. Collapse case-duplicate keys LAST-WRITE-WINS
+ * in iteration order — matching what `Object.assign` semantics promised the caller (per-command overrides beat
+ * config env beats inherited base) — while keeping the FIRST-SEEN casing (the inherited base is assigned first,
+ * so `Path=…` inherited + `PATH=x` override collapses to `Path=x`: native casing, override value).
+ * POSIX: returns the input UNTOUCHED (case-sensitive env is real there — `Path` and `PATH` are distinct).
+ */
 export declare function collapseWin32EnvKeys(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The platform-free collapse algorithm (exported so the mac/Linux suite can pin the win32 behavior — design
+ *  D5: structural verification everywhere, behavioral bite on the Windows runner). */
 export declare function collapseEnvKeysCaseInsensitive(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 //# sourceMappingURL=host-platform.d.ts.map

package/dist/plugins/host-platform.js

@@ -1,12 +1,53 @@
+/**
+ * Host-lane PLATFORM seam (DESIGN-windows-native.md, FINAL r3) — the ONE place the host exec adapter's
+ * POSIX/win32 differences live, so `remote-env-host.ts` stays a single code path with platform-gated leaves.
+ *
+ * 🔴 Iron invariant (design §4.1): the POSIX path is BYTE-IDENTICAL to the pre-Windows code — every helper is
+ * `win32 ? new : exactly-what-the-inline-code-did` (same syscall, same throw behavior). Never "improve" POSIX
+ * here; the existing full test suite is the regression net.
+ *
+ * win32 semantics (design D1-D4):
+ *  - shell   = Git Bash via core 1.224 `getShellConfig` (WSL-launcher-filtered — the `System32\bash.exe`
+ *              trap). Fail-LOUD when absent; never silently degrade to cmd (D1).
+ *  - kill    = core 1.224 `signalProcessTree` (taskkill /T, /F for hard). Soft is a no-op for console trees
+ *              (taskkill errors "can only be terminated forcefully") — the SIGTERM→grace→SIGKILL ladder is
+ *              effectively delay→hard-kill on win32; accepted, CC-identical (D2).
+ *  - spawn   = `detached:false` + `windowsHide:true` (no console window; no POSIX process group — the kill
+ *              side uses the tree, not the group) (D3).
+ *  - env     = case-insensitive key collapse before spawn (win32 env keys are case-insensitive; a `Path`+`PATH`
+ *              pair from case-sensitive Object.assign reaches CreateProcess as ONE undefined-which
+ *              entry). Canonical casing = the first-seen key (process.env's native casing wins since the
+ *              inherit base is spread first).
+ *
+ * ⚠️ The win32 branches are UNVERIFIED on a real machine until S5 (Windows CI runner) — design D5 discipline:
+ * structural tests only on mac/Linux; behavior-level bite happens on the first Windows-runner green.
+ */
 import { getShellConfig, killProcessTree, signalProcessTree } from "@sema-agent/core";
 export const IS_WIN32 = process.platform === "win32";
+/** S1([1870] test AI 全归因,2026-07-27):POSIX 不再硬编码 `/bin/sh`——Debian/Ubuntu 的 /bin/sh 是
+ *  dash,TB 实测三类病:`$'a\tb'` **静默错字节**(exit 0、输出字面 5 字节)、`[[ ]]` 127、进程替换
+ *  语法错;CC 对照从不用 /bin/sh。改为与 win32 同源:core `getShellConfig()`(/bin/bash → PATH bash
+ *  → `sh` 诚实兜底,core 六版逐字节稳定被 test AI 洗清)。旧「POSIX byte-identical」铁律就此**有意**
+ *  打破——它防的是 Windows 改动误伤 POSIX,这次是带失分证据 + CC 对照的 POSIX 行为修正。
+ *  极罕的无 bash 宿主(alpine 裸机)拿 core 的 `sh` 兜底,行为=修前。 */
 const POSIX_SH_FALLBACK = { shell: "/bin/sh", args: ["-c"] };
 let cachedWinShell;
 let cachedPosixShell;
+/**
+ * Resolve the host shell ONCE per process (cached). POSIX resolves synchronously to `/bin/sh` — zero behavior
+ * change. win32 defers to core's `getShellConfig` (explicit `HOST_SHELL_PATH` override → Git-for-Windows
+ * install dirs → PATH `bash.exe` with the WSL-launcher filter) and THROWS a self-explaining error when no
+ * usable bash exists (design D1 fail-loud: "install Git for Windows", never a silent cmd fallback).
+ *
+ * Call sites: `shellReady()` awaits this once (all exec/bg/stream spawns are behind it), then the spawn sites
+ * read the cached value synchronously via {@link hostShell}.
+ */
 export async function resolveHostShell() {
     if (!IS_WIN32) {
         if (cachedPosixShell)
             return cachedPosixShell;
+        // S1:POSIX 与 win32 同源(core getShellConfig:/bin/bash → PATH bash → sh 兜底;POSIX 分支
+        // 恒 ok——sh 兜底也是 ok 形,故这里不需要 win32 的 fail-loud 臂)。HOST_SHELL_PATH 同一覆写口。
         const posixCfg = await getShellConfig(process.env.HOST_SHELL_PATH || undefined);
         cachedPosixShell = posixCfg.ok ? { shell: posixCfg.value.shell, args: posixCfg.value.args } : POSIX_SH_FALLBACK;
         return cachedPosixShell;
@@ -23,21 +64,38 @@ export async function resolveHostShell() {
     cachedWinShell = { shell: cfg.value.shell, args: cfg.value.args };
     return cachedWinShell;
 }
+/** Synchronous read of the resolved shell — valid only AFTER {@link resolveHostShell} settled (the spawn sites
+ *  are all behind `shellReady()`, which awaits it). POSIX never needs the async step. Throws on a mis-ordered
+ *  call (a programming bug, not an operator condition — fail loud, not /bin/sh-on-windows). */
 export function hostShell() {
     if (!IS_WIN32) {
+        // S1 后 POSIX 也走异步解析;未解析先到的同步读拿 sh 兜底(修前字节形)而非 throw——POSIX 的
+        // 病是 dash 语义不是缺 shell,这里降级无害且绝不把既有调用序变成崩溃。解析后即恒 bash。
         return cachedPosixShell ?? POSIX_SH_FALLBACK;
     }
     if (!cachedWinShell)
         throw new Error("host shell not resolved yet — resolveHostShell() must settle before any spawn (shellReady ordering bug)");
     return cachedWinShell;
 }
+/** test-only: reset the shell caches (each test can re-drive resolution). */
 export function resetHostShellCacheForTest() {
     cachedWinShell = undefined;
     cachedPosixShell = undefined;
 }
+/** Per-platform spawn options for a group-killable child (design D3).
+ *  POSIX: `detached:true` — child becomes its own process-group leader (pgid === pid) so `kill(-pid)` reaps the
+ *  whole group. BYTE-IDENTICAL to the previous inline `detached: true`.
+ *  win32: `detached:false` (a detached child opens a console; there is no killable POSIX group either way —
+ *  the kill side uses taskkill's tree) + `windowsHide:true` (no flashing console window). */
 export function spawnGroupOptions() {
     return IS_WIN32 ? { detached: false, windowsHide: true } : { detached: true };
 }
+/**
+ * HARD kill of the child's whole tree (design D2). POSIX = `process.kill(-pid, "SIGKILL")` — byte-identical,
+ * INCLUDING the throw on a dead group (ESRCH): every call site already wraps in its own try/catch with its own
+ * fallback (e.g. `child.kill("SIGKILL")`), and that structure must not change.
+ * win32 = core `signalProcessTree(pid,"SIGKILL")` → `taskkill /F /T` (never throws — fire-and-forget spawn).
+ */
 export function killTreeHard(pid) {
     if (IS_WIN32) {
         signalProcessTree(pid, "SIGKILL");
@@ -45,6 +103,14 @@ export function killTreeHard(pid) {
     }
     process.kill(-pid, "SIGKILL");
 }
+/**
+ * SOFT kill (design D2 — the bg KillShell/timeout-wall first rung; the caller owns the grace→hard escalation
+ * timer, unchanged). POSIX = `process.kill(-pid, "SIGTERM")` byte-identical (throws on dead group — the caller
+ * treats that as "already dead, skip escalation"). win32 = `taskkill /T` without /F — which for a typical
+ * all-console tree ERRORS AND KILLS NOTHING: the ladder degrades to delay→hard-kill there;
+ * accepted + documented (CC-identical). It never throws, so the caller's "already dead → return" branch never
+ * fires on win32 — the escalation timer always arms, which is exactly what we want given soft is a no-op.
+ */
 export function killTreeSoft(pid) {
     if (IS_WIN32) {
         signalProcessTree(pid, "SIGTERM");
@@ -52,14 +118,27 @@ export function killTreeSoft(pid) {
     }
     process.kill(-pid, "SIGTERM");
 }
+/** 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 };
+/**
+ * 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`
+ * (caller override) yields one-of-them-undefined-which in the child. Collapse case-duplicate keys LAST-WRITE-WINS
+ * in iteration order — matching what `Object.assign` semantics promised the caller (per-command overrides beat
+ * config env beats inherited base) — while keeping the FIRST-SEEN casing (the inherited base is assigned first,
+ * so `Path=…` inherited + `PATH=x` override collapses to `Path=x`: native casing, override value).
+ * POSIX: returns the input UNTOUCHED (case-sensitive env is real there — `Path` and `PATH` are distinct).
+ */
 export function collapseWin32EnvKeys(env) {
     if (!IS_WIN32)
         return env;
     return collapseEnvKeysCaseInsensitive(env);
 }
+/** The platform-free collapse algorithm (exported so the mac/Linux suite can pin the win32 behavior — design
+ *  D5: structural verification everywhere, behavioral bite on the Windows runner). */
 export function collapseEnvKeysCaseInsensitive(env) {
-    const canonical = new Map();
+    const canonical = new Map(); // lowercased key → first-seen casing
     const out = {};
     for (const [k, v] of Object.entries(env)) {
         if (v === undefined)
@@ -71,7 +150,7 @@ export function collapseEnvKeysCaseInsensitive(env) {
             out[k] = v;
         }
         else {
-            out[keep] = v;
+            out[keep] = v; // later (higher-precedence) value under the first-seen casing
         }
     }
     return out;

package/dist/plugins/image-bake-store-sql.d.ts

@@ -2,51 +2,186 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
 import { type BakeStatus, type BakeState, type BakeRecord, type BakeEvent, type CreateBakeInput, type BakeTerminal } from "./store-contracts.js";
+/** PG translation of the image_bake / image_bake_event / image_bake_lease DDL in tidb-pool.ts SCHEMA_STATEMENTS
+ *  (JSON→JSONB, TINYINT→SMALLINT, DATETIME(3)→TIMESTAMPTZ(3), inline UNIQUE/KEY→named CONSTRAINT + CREATE INDEX).
+ *  TINYINT(1) 归一(clay 批 2026-07-26):布尔列的 PG 映射统一 SMALLINT 0/1(此前本家族用 BOOLEAN)——
+ *  两方言驱动读回同为 number ⇒ 不再存在「忘了配的适配器」这个病族;写入参与 SQL 字面量一律 0/1,
+ *  读侧 `!!`/`Boolean()` 保持,store 出口 JS 类型逐字节不变(真双库套件的严格值断言为证)。
+ *  The uq_line UNIQUE is given an explicit name so a 23505 can be attributed to it via err.constraint. */
 export declare const PG_IMAGE_BAKE_SCHEMA: string[];
+/** Idempotent self-contained PG schema apply (for the integration test; central aggregation is done separately). */
 export declare function ensurePgImageBakeSchema(pool: PgPool | PoolClient, poolName?: string): Promise<void>;
+/** Dual-dialect BAKE store. See the file header for the dialect-delta ledger. */
 export declare class SqlImageBake {
     protected readonly db: SqlDriver;
+    /** The builder pool a lease serializes on (one docker daemon ⇒ one pool today). */
     protected readonly poolName: string;
-    constructor(db: SqlDriver, poolName?: string);
+    constructor(db: SqlDriver, 
+    /** The builder pool a lease serializes on (one docker daemon ⇒ one pool today). */
+    poolName?: string);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** The 12 bound values shared by both admission INSERTs (column order === INSERT_BAKE_COLS). */
     private insertParams;
+    /**
+     * Create a bake, queued. Durable submit-idempotency mirrors createRun's CAS: `idem_key` is UNIQUE, so a
+     * re-submit with the same key races to INSERT and the loser catches the dup-key, then re-reads + returns the
+     * EXISTING row (the live bake) instead of a second job. A null `idemKey` always inserts (no dedupe requested).
+     * Returns `{ created, bake }` so the handler can answer 202 either way (idempotent dup ⇒ created:false).
+     */
     createBake(input: CreateBakeInput): Promise<{
         created: boolean;
         bake: BakeRecord;
     }>;
+    /**
+     * M4 (§P2.1/§P2.7 — the 409-busy MUST): create a queued bake ATOMICALLY only when no other non-dryRun bake is
+     * in flight, so two concurrent keyless POSTs can NEVER both queue (the check-then-act in the submit handler —
+     * findActiveAny() then createBake() as two awaited round-trips — interleaves: both see null-busy, both insert).
+     * `uq_idem` only dedupes non-null idem_keys (a keyless submit is NULL = distinct), and the build lease is taken
+     * at CLAIM not submit, so neither backstops this — the admission itself must be serialized.
+     *
+     * A bare conditional INSERT (`INSERT … SELECT … WHERE NOT EXISTS(...)`) is NOT sufficient ON ITS OWN: under
+     * TiDB's default REPEATABLE READ (and PG's READ COMMITTED) two concurrent autocommit conditional inserts each
+     * evaluate NOT EXISTS against a snapshot that excludes the other's still-uncommitted row (PG takes no
+     * predicate/gap lock), so BOTH can pass and double-admit. The only backstop today is the build lease taken at
+     * CLAIM, so a double-admit degrades the 409-busy/202-attach contract rather than double-building — but the
+     * contract is the point.
+     *
+     * Fix: serialize the busy-check+insert on the per-pool admission sentinel (`image_bake_admit`) with
+     * `SELECT … FOR UPDATE` inside one transaction. The second admitter blocks on the sentinel row lock until the
+     * first commits, then sees the committed in-flight bake and inserts 0 → `created:false`, and the caller
+     * re-reads the active bake (findActiveByArgv for an idempotent attach, else findActiveAny) for the
+     * 202-attach / 409 body. A dryRun bypasses this path entirely (never takes the lease — parallel-safe) and uses
+     * plain createBake.
+     *
+     * 🔴 DIALECT DIVERGENCE (deliberate, both preserved verbatim — the real-DB suites are the oracle):
+     *   - TiDB: `BEGIN PESSIMISTIC` + a separate `SELECT 1 … FOR UPDATE` busy-check, then a plain INSERT. The
+     *     pessimistic txn is REQUIRED: TiDB's snapshot (REPEATABLE READ) txn would evaluate a NOT EXISTS against
+     *     the txn-start snapshot and miss a rival's just-committed row EVEN under the sentinel lock.
+     *   - PG: plain `BEGIN` + one `INSERT … SELECT … WHERE NOT EXISTS(...)`. READ COMMITTED takes a FRESH
+     *     statement snapshot, so the NOT EXISTS run after the sentinel lock is granted already sees the committed
+     *     rival — the conditional insert is atomic enough once serialized.
+     */
     createBakeIfIdle(input: CreateBakeInput): Promise<{
         created: boolean;
         bake: BakeRecord | null;
     }>;
     getBake(bakeId: string): Promise<BakeRecord | null>;
     getBakeByIdem(idemKey: string): Promise<BakeRecord | null>;
+    /**
+     * Find an in-flight (queued/running) bake with the identical normalized argv — so a re-submit WITHOUT an
+     * idempotency key still returns the live bake rather than starting a duplicate build (P2.1 "an in-flight
+     * identical-input bake returns the EXISTING row"). argv is the canonical normalized vector, so a JSON
+     * equality is the dedupe key. Newest first (the live one).
+     */
     findActiveByArgv(argv: string[]): Promise<BakeRecord | null>;
+    /**
+     * The OLDEST in-flight (queued/running) NON-dry-run bake — the single-flight at-submit guard (P2.7). Concurrency
+     * is 1 (one docker daemon), so a new submit while ANY non-dry-run bake is in flight is `409 busy` UNLESS it is
+     * the identical-argv one (then the caller attaches to it, idempotent). dryRun bakes never take the lease, so they
+     * are excluded here. Oldest first = the one that holds/will-hold the lease (the build the UI should attach to).
+     */
     findActiveAny(): Promise<BakeRecord | null>;
+    /**
+     * The OLDEST queued bake id — the runner's long-poll claim target (P2.12). dryRun bakes never take the lease, so
+     * they are still discoverable here (the runner resolves them with no docker), but ordering oldest-first gives a
+     * stable FIFO. Returns null when the queue is empty. The actual claim is a CAS (`claimBake`), so two runners
+     * racing this both see the id but only one wins the conditional UPDATE — no double-build.
+     */
     findNextQueuedId(): Promise<string | null>;
+    /**
+     * Single-flight CLAIM (P2.7) — the runner leases the next queued bake. Two CASes in one transaction:
+     *   1. flip the bake row `queued → running` (conditional UPDATE `WHERE status='queued'`, 1 row affected wins);
+     *   2. take the single-row `image_bake_lease` for the pool (INSERT, or steal an EXPIRED lease via CAS).
+     * Only the runner that wins BOTH gets the bake; a loser (someone else already claimed, or the lease is held by
+     * a live build) gets null. Mints + stores the per-bake `ingest_secret` (so a stale/rogue runner can't inject
+     * frames into another bake) and the initial `lease_until`. Returns the claimed row (with the secret) or null.
+     */
     claimBake(bakeId: string, runnerId: string, leaseMs: number): Promise<BakeRecord | null>;
+    /**
+     * Append one event. image-api is the SOLE ++seq writer: `seq = maxSeq(bakeId)+1`. The `(bakeId,line_ord)`
+     * UNIQUE is the at-least-once ingest dedupe (P2.10) — a runner re-sending a line it already acked races to
+     * INSERT and the loser is a NO-OP (the frame is already stored at its seq). Returns the seq written, or null
+     * when the line was a duplicate (already stored). A null `lineOrd` (image-api-synthesized frame:
+     * register/done/heartbeat-derived) never collides on the line-unique (NULLs are distinct in a UNIQUE index).
+     *
+     * seq allocation + the INSERT are NOT one atomic statement, so two concurrent appends could pick the same
+     * seq+1; the (bakeId,seq) PK then rejects the loser with a dup-key. M2: that PK collision is DISTINGUISHED from
+     * a benign line re-send (by the dup-key attribution channel) and RETRIED in a bounded loop with a fresh
+     * maxSeq+1 — never silently swallowed (which would drop a frame, incl. the terminal `done`, at a clean HTTP
+     * 200). A line dup is the at-least-once re-send no-op (returns null). The runner also serializes its per-bake
+     * pump (runner.ts), so the same-seq race is the rare burst case, not the norm.
+     */
     appendEvent(bakeId: string, kind: string, data: unknown, opts?: {
         lineOrd?: number | null;
         level?: string | null;
     }): Promise<number | null>;
     private lineOrdExists;
+    /** Highest event seq for a bake (0 if none) — the ++seq allocator + the resume cursor head. */
     maxSeq(bakeId: string): Promise<number>;
+    /** Earliest retained event seq (0 if none) → the SSE 416 boundary (a resume below this was evicted, P2.9). */
     retainedFrom(bakeId: string): Promise<number>;
+    /** Events with seq strictly greater than `afterSeq` (0 for the whole stream), ascending. */
     getEvents(bakeId: string, afterSeq: number): Promise<BakeEvent[]>;
+    /** Coarse 4-value lifecycle transition (the column the SSE reader polls for terminality). */
     setStatus(bakeId: string, status: BakeStatus): Promise<void>;
+    /** Denormalize build.sh's 8-value `state` for the UI progress bar (NEVER drives terminality, P2.3). */
     setState(bakeId: string, state: BakeState): Promise<void>;
+    /**
+     * Terminal write (P2.10 step 4): flip the coarse `status` + persist all the terminal facts (digest/repo/ref/
+     * indexId/exitCode/error/errorCode/state/manifestSha/tag) the `done` frame and the poll row carry, AND release
+     * the pool lease in one transaction (a separate-statement release that failed would wedge the build host).
+     * Idempotent terminal write: only flips a NON-terminal row (`WHERE status IN ('queued','running')`) so a
+     * re-delivered terminal can't clobber the first outcome. Returns the UPDATE's affected count — 1 = THIS call won
+     * the queued/running→terminal transition; 0 = a terminal already exists (M3: the caller then SKIPS appending a
+     * contradictory second terminal `done` event, so at most one terminal `done` per bake matches the coarse row).
+     * 🔴 H3: null `ingest_secret` on the terminal flip so a terminal row can NEVER re-authenticate an ingest
+     * (a lagging/duplicate runner that still holds the secret can't inject frames into a settled bake).
+     */
     setTerminal(bakeId: string, t: BakeTerminal): Promise<number>;
+    /** TiDB stores the terminal facts VERBATIM (no protocol-byte class to defend against). */
     private terminalParamsTidb;
+    /** PG-ONLY protocol-byte handling. R20/R21:身份位(digest/manifestSha/repo/ref)带不可存字节=帧无效——
+     *  **单一谓词**统管状态折叠与全部身份绑位(R21:只查两位会放 dirty repo/ref 的假 COMPLETE 过——终态单赢,
+     *  假成功不可逆)。事务必须提交(lease 释放/secret 清理=单飞池活性底线)。codex R13/R17-H2:NUL 错误文案
+     *  或脏 tag 若让终态事务回滚,lease 保持 = bake 永占单飞池,故文本位走 sanitize 而非拒绝。 */
     private terminalParamsPg;
+    /** Set the index_id once auto-register succeeds (P2.10 — kept distinct from the terminal flip so the `done`
+     *  frame can carry indexId even when the terminal write retries). codex R24:non-terminal 门——并发 done
+     *  竞态下(本请求悬在 registerBuilding 时另一 done 已赢 setTerminal)绝不把 indexId 挂回终态行(R23 折叠
+     *  的 FAILED/null 身份行会被复写成「null 身份却带 index 绑定」的矛盾形)。返回是否真绑定。 */
     setIndexId(bakeId: string, indexId: string): Promise<boolean>;
+    /** Heartbeat the lease forward (P2.7): the runner pushes `lease_until` (+ the lease row's `expires_at`) while
+     *  its build child runs, so the reaper doesn't steal a LIVE build's lease. CAS on the runner owning the row +
+     *  the bake still running. Returns whether it refreshed (false ⇒ lease lost/stolen — the runner should abort). */
     heartbeatLease(bakeId: string, runnerId: string, leaseMs: number): Promise<boolean>;
+    /** Request cooperative cancel (P2.11) — durable + cross-replica; the runner's heartbeat tick polls it and kills
+     *  the build.sh process group. Only flags a non-terminal row (terminal → 0 affected = no-op). Returns whether a
+     *  live bake was flagged (false ⇒ already terminal → the caller answers a no-op 202). */
     requestCancel(bakeId: string): Promise<boolean>;
+    /** Whether a cancel was requested (polled by the runner). */
     isCancelRequested(bakeId: string): Promise<boolean>;
+    /**
+     * Reaper twin of TiDBRunStore.reapStale (P2.7/§P2.6): fail any `running` bake whose lease is STALE (a crashed
+     * runner stopped heartbeating), append a synthetic terminal `done{failed}` so SSE readers SETTLE (never hang),
+     * and force-release the pool lease. `olderThanMs` must exceed >2 lease-heartbeat intervals (≈3× the heartbeat)
+     * so a healthy slow build is not wrongly reaped. Returns the count reaped.
+     *
+     * M3: flip the row terminal FIRST (the CAS on `status='running'`), and append the synthetic `done{failed}` ONLY
+     * when the flip WON (1 row affected). A victim that recovered + COMPLETEd between the SELECT and the flip
+     * no-ops the CAS, so we leak NO contradictory `done{failed}` into its settled SSE log. A reader that polled the
+     * still-running row in the tiny pre-flip gap simply re-polls (streamSseLog re-fetches) and settles on the
+     * eventual terminal — the winner's `done` — rather than a spurious one.
+     */
     reapStaleBakes(olderThanMs: number): Promise<number>;
+    /** Run statements atomically; rolls back on failure (mirrors TiDBRunStore.tx). */
     private tx;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBImageBake extends SqlImageBake {
     constructor(pool: MySqlPool, poolName?: string);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgImageBake extends SqlImageBake {
     constructor(pool: PgPool, poolName?: string);
 }