@sema-agent/server 7.103.1 → 7.104.0

package/dist/roster-bound-http-status.js

@@ -0,0 +1,6 @@
+export const ROSTER_BOUND_HTTP_STATUS = {
+    "config.tool_name_too_long": 503,
+    "config.tool_contract_too_long": 503,
+    "config.tool_roster_bound": 503,
+};
+//# sourceMappingURL=roster-bound-http-status.js.map

package/dist/run-local.js

@@ -3,12 +3,10 @@ import { DEFAULT_MODEL_REF, resolveTaskModel } from "./model-select.js";
 import { defaultModelRefusal, modelUnavailableMessage } from "./model-entry-refusal.js";
 import { buildDurableAbsenceNote, createCorruptReadSeat } from "./observability/corrupt-read-seat.js";
 import { outwardPlane } from "./terminal.js";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { realpathSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { loadRemoteExec } from "@sema-agent/settings-schema/node";
 import { Runner, uuidv7, FileStorageBackend, NodeExecutionEnv, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore, defaultTaskRegistry } from "@sema-agent/core";
 import { singleUserAutoAcceptBaselineApplies } from "./approval.js";
 import { createBrain } from "./brain.js";
@@ -21,7 +19,9 @@ import { validatePromptsDomain, CORE_ENGINE_VERSION } from "./prompts-domain-val
 import { buildUnpricedCeilingNotice, loadConfig, logConfigDiagnostics, parseNumOrFailNonNegative } from "./config.js";
 import { buildStoreOpenRefusalTail } from "./plugins/store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./plugins/store-lock-wait.js";
-import { createConfigProvider } from "./config-provider.js";
+import { configLocalRoot, configProviderKind, createConfigProvider } from "./config-provider.js";
+import { composeExecutionLane } from "./boot/execution-lane.js";
+import { judgeConsolidationValve } from "./boot/memory-consolidation.js";
 import { applyEffective, applyCenterReadFace, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./config-center/facade.js";
 import { hostExecutionEnvFactory } from "./plugins/remote-env-host.js";
 import { executionLaneHomeDir, executionLaneOf } from "./execution-lane-caps.js";
@@ -259,20 +259,25 @@ export async function runLocal(argv, deps = {}) {
         process.env.CONFIG_PROVIDER = "local";
     process.env.SESSION_BACKEND = "memory";
     process.env.REQUIRE_PRINCIPAL = "false";
-    const root = args.root ?? process.env.CONFIG_LOCAL_DIR ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent");
     if (args.root)
         process.env.CONFIG_LOCAL_DIR = args.root;
     const config = loadConfig();
+    const root = configLocalRoot(config);
     const logger = deps.logger ?? createLogger(config.logLevel);
     const metrics = createMetrics();
     const memoryEngineIncident = createMemoryEngineIncidentSink({ logger, metrics });
     installSecretEnvScrubRecorder({ logger, metrics });
     logConfigDiagnostics(logger);
     installOutboundDispatcher(logger);
-    const configProvider = createConfigProvider({
-        provider: config.configProvider ?? "local",
-        ...(config.configLocalDir ? { localDir: config.configLocalDir } : { localDir: root }),
-    });
+    const providerInput = { provider: config.configProvider ?? "local", localDir: root };
+    try {
+        await composeExecutionLane(config, { configSource: configProviderKind(providerInput), localRoot: root, logger, drivesFromFile: ["host"] });
+    }
+    catch (err) {
+        printErr(err instanceof Error ? err.message : String(err));
+        return 2;
+    }
+    const configProvider = createConfigProvider(providerInput);
     let effective;
     try {
         const r = await configProvider.fetchEffective(undefined);
@@ -303,25 +308,6 @@ export async function runLocal(argv, deps = {}) {
     const unpricedCeiling = buildUnpricedCeilingNotice(config.models, config);
     if (unpricedCeiling)
         logger.warn(unpricedCeiling.event, unpricedCeiling.fields);
-    try {
-        const fileRx = await loadRemoteExec(root);
-        if (fileRx?.provider === "host") {
-            config.remoteExec = {
-                provider: "host",
-                ...(fileRx.workdir ? { workspaceBase: fileRx.workdir } : {}),
-                ...(fileRx.commandTimeoutMs != null ? { commandTimeoutMs: fileRx.commandTimeoutMs } : {}),
-            };
-            logger.info("remote_exec_from_file", { provider: "host", root });
-        }
-        else if (fileRx) {
-            logger.warn("remote_exec_file_isolated_lane_unwired", { provider: fileRx.provider, note: "run-local is the host lane; isolated lanes stay env-sourced" });
-        }
-    }
-    catch (err) {
-        logger.error("remote_exec_file_invalid", { root, err: String(err) });
-        printErr(`config.d/remote-exec.json is invalid: ${String(err)}`);
-        return 2;
-    }
     try {
         assertGuardPatternsUsable(config);
     }
@@ -377,6 +363,15 @@ export async function runLocal(argv, deps = {}) {
         : undefined;
     const lspManager = hostRx && config.lspHostEnabled && config.requirePrincipal !== true ? createHostLspManager(config, (event, fields) => logger.info(event, fields)) : undefined;
     const memoryEngine = memoryEngineBackendFor(config, root, memoryEngineIncident);
+    try {
+        judgeConsolidationValve({ config, memoryEngine });
+    }
+    catch (err) {
+        printErr(err instanceof Error ? err.message : String(err));
+        void lspManager?.dispose();
+        await fileBackend.dispose();
+        return 2;
+    }
     let memorySync;
     if (config.memorySync && memoryEngine) {
         memorySync = createMemorySyncRunner({

package/dist/runs.d.ts

@@ -145,12 +145,32 @@ export declare function isSessionConflictResult(result: {
  * 🔴 **可达性如实**:本仓的 HTTP 面**今天铸不出**这条腿 —— 子代由 core 内部的 Agent 工具派生,
  * `fileHistoryLineage` 是 core prepare 的 internals(不在 `TaskSpec` 上),server 从不直接 prepare 一条带
  * lineage 的子代腿。本臂是**分诊面的完备性**(core 说 X ⇒ wire 形是 Y),不是一条今天在跑的路;将来的
- * 委派入口接线那天零改动即生效。同族其余五码今天**仍落 200-with-failed-body**,那是本批**之前**就存在的
- * 缺口(不是本批回归),已在上述对表格里逐码显式登记为债务,并由那道门看住不许陈腐。
+ * 委派入口接线那天零改动即生效。同族其余码(`rewind_files_retired` / `invalid_spec` / `conflicting_targets` /
+ * `restore_failed`)今天**仍落 200-with-failed-body**,那是各自提货批**之前**就存在的缺口(不是回归),已在上述对表格里
+ * 逐码显式登记为债务,并由那道门看住不许陈腐。
+ *
+ * S-724(core 7.31.0 #1048 / #1050):`rewind.capture_disabled` → **422**(关断词与还原同体 = 自相矛盾;本服务的请求面上
+ * 走不到它 —— fresh 受理门先 400 `request.field_conflict`(core 这一拒落在会话分叉之后、不回滚);映射是分诊面完备性)、`rewind.store_unconfigured`
+ * → **409**(部署没有历史店;`FILE_HISTORY_CAPTURE=false` 自本版不再摘店 ⇒ 可达面只剩没有后端的部署形,那里
+ * `capabilities.rewindFiles` 恒报 false —— 三问在 CHANGELOG 7.104.0)。
  */
 export declare function resumeAtHttpStatus(result: {
     terminal: TerminalCause;
 }): number | undefined;
+/**
+ * 同步提交腿的**拒因状态**(S-271 车内 codex r1 [high] 以类修):`resumeAtHttpStatus` 的逐码档,只对**零工作的拒**生效。
+ *
+ * 那张分诊表(`resume_at.*` / 治理闭集 / 名册超界闭集 / 开集 if 链)的每一格都立在同一个前提上:这个码是 prepare 期的拒,
+ * 整次提交一个 turn 都没跑、一个 token 都没烧 ⇒ 答 4xx / 5xx、**不走** `finalizeTaskResult`、不进幂等缓存(只缓存 < 400)。
+ * 可终局码证明不了这个前提:verify / cascade 的聚合结果 = **末轮**终局 + **各轮累计** stats(core `runCascade` /
+ * `runWithVerification`),前一轮真跑了 turn、真执行了工具,末轮才在 prepare 期被拒,码照样是那个 prepare 码。
+ * 真案(车内 codex r1 验真):`modelGate` 把带门类的超界工具从第一级模型的名册上摘掉,第一级跑了一只有副作用的工具,第二级
+ * 名册门拒 ⇒ 修前答 503,跳过计费,同一 Idempotency-Key 重发把第一级的工具再执行一遍。
+ * ⇒ 判据是**这次提交做没做过工作**(累计 `turns` / `tokens` 皆零),不是码:做过工作的失败无论码是什么,都是「跑了然后失败了」
+ * (200 + failed 体、计费、可重放)。入参要求带 `stats`,所以同步腿拿不到「只看码」的那一半 —— 只看码的逐码表留给
+ * `resumeAtHttpStatus` 自己(单元测试直接喂码)。
+ */
+export declare function syncRefusalHttpStatus(result: Pick<TaskResult, "terminal" | "stats">): number | undefined;
 /**
  * E18 resume-at — per-turn anchor capture, shared by runInBackground AND the resume-leg driveResume so the (single,
  * tricky) capture rule can't drift between the two stream-drain loops.

package/dist/runs.js

@@ -1,6 +1,8 @@
 import { runWithVerification, runCascade, defaultTaskRegistry, taskNotificationDedupKey, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
 import { failureCodeOf, sealResultForExit, outwardPlane } from "./terminal.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
+import { ROSTER_BOUND_HTTP_STATUS } from "./roster-bound-http-status.js";
+import { isSessionErrorCode, sessionErrorHttp } from "./session-error-wire.js";
 import { redactErrorMessage } from "./observability/run-terminal.js";
 import { withPrincipal } from "./observability/principal-context.js";
 import { redactSecrets } from "./trace/redact.js";
@@ -74,12 +76,24 @@ export function resumeAtHttpStatus(result) {
     if (Object.hasOwn(GOVERNANCE_HTTP_STATUS, code)) {
         return GOVERNANCE_HTTP_STATUS[code] ?? undefined;
     }
+    if (Object.hasOwn(ROSTER_BOUND_HTTP_STATUS, code)) {
+        return ROSTER_BOUND_HTTP_STATUS[code];
+    }
+    if (isSessionErrorCode(code)) {
+        const wire = sessionErrorHttp(code, "open");
+        if (wire !== undefined)
+            return wire.status;
+    }
     if (code === "resume.session_not_found")
         return 404;
     if (code === "rewind_snapshot.unresolvable")
         return 422;
     if (code === "rewind.child_scope_unsupported")
         return 422;
+    if (code === "rewind.capture_disabled")
+        return 422;
+    if (code === "rewind.store_unconfigured")
+        return 409;
     if (code === "memory.capture_optout_unpersisted")
         return 503;
     if (code === "config.memory_capture_spelling")
@@ -94,6 +108,11 @@ export function resumeAtHttpStatus(result) {
         return undefined;
     return code === "resume_at.not_found" ? 404 : 422;
 }
+export function syncRefusalHttpStatus(result) {
+    if (result.stats.turns !== 0 || result.stats.tokens !== 0)
+        return undefined;
+    return resumeAtHttpStatus(result);
+}
 export class TurnAnchorCapture {
     capture;
     onCaptureFail;
@@ -221,8 +240,9 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     const parkNeedsReview = async (res) => {
         await sink.appendParked("needs_review", res);
         await flushModelUsage();
-        reached = { kind: "needs_review" };
-        await runStore.setNeedsReview(taskId);
+        const sealed = sealResultForExit(res);
+        reached = { kind: "needs_review", result: sealed };
+        await runStore.setNeedsReview(taskId, sealed);
         metrics?.addGauge("runs_active", -1);
         metrics?.inc("tasks_total", { status: "needs_review" });
     };
@@ -361,10 +381,12 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     await flush();
                     const parkStatus = ev.result.terminal.kind === "paused" ? outwardPlane(ev.result.terminal).status : undefined;
                     if (parkStatus === "suspended") {
-                        await sink.appendParked("suspended", await graftParkToolCallId(ev.result, parkCheckpointReader));
+                        const grafted = await graftParkToolCallId(ev.result, parkCheckpointReader);
+                        await sink.appendParked("suspended", grafted);
                         await flushModelUsage();
-                        reached = { kind: "suspended" };
-                        await runStore.setSuspended(taskId);
+                        const sealed = sealResultForExit(grafted);
+                        reached = { kind: "suspended", result: sealed };
+                        await runStore.setSuspended(taskId, sealed);
                         metrics?.addGauge("runs_active", -1);
                         metrics?.inc("tasks_total", { status: "suspended" });
                         continue;
@@ -456,10 +478,10 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await runStore.setTerminal(taskId, plane.status, reached.result, plane.errorMessage ?? null);
             }
             else if (reached?.kind === "suspended") {
-                await runStore.setSuspended(taskId);
+                await runStore.setSuspended(taskId, reached.result);
             }
             else if (reached?.kind === "needs_review") {
-                await runStore.setNeedsReview(taskId);
+                await runStore.setNeedsReview(taskId, reached.result);
             }
             else if (cancelCtrl.signal.aborted && observedDone === undefined) {
                 const c = cancelledResult();

package/dist/sealed-key.d.ts

@@ -13,16 +13,43 @@ export interface SealedKeyOpener {
      *  🔴 The returned plaintext is a live secret: memory-only, never log it, never persist it. */
     open(ciphertextB64: string, publicKeyId: string): string;
 }
-export interface SealedKeyStore extends SealedKeyOpener {
+/**
+ * S-737 —— the store's **discovery-safe face**: ONLY the newest public key. This is what the HTTP layer is handed
+ * (`ServiceDeps.sealedKeyPublic` → `GET /v1/capabilities` `sealedKey`) — never the whole store — so private-key
+ * material, the custody path and the held-id list are structurally unreachable from that layer (not merely
+ * "not read"). Built from a live store by {@link buildSealedKeyPublicFace}, which copies out `latest` alone.
+ */
+export interface SealedKeyPublicFace {
     /** The keypair NEW ciphertexts should be sealed against (max `createdAt`, ties broken by id) —
-     *  this is the key we report/print for center registration. `publicKey` is base64 (32 raw bytes,
-     *  44 chars): public by definition, safe to log. */
-    latest: {
+     *  this is the key we report/print for center registration and project onto `GET /v1/capabilities`.
+     *  `publicKey` is base64 (32 raw bytes, 44 chars): public by definition, safe to log. */
+    readonly latest: {
         publicKeyId: string;
         publicKey: string;
         createdAt: string;
     };
 }
+/** The custody store = the private half ({@link SealedKeyOpener}: open / has / ids) + the public face. */
+export interface SealedKeyStore extends SealedKeyOpener, SealedKeyPublicFace {
+}
+/** Copy the public face out of a live store — a NEW plain object carrying `latest` only (no `open` / `has` / `ids`
+ *  reachable through it, whatever the caller later casts it to). Plain data ⇒ `build*`. */
+export declare function buildSealedKeyPublicFace(store: SealedKeyPublicFace): SealedKeyPublicFace;
+/**
+ * S-737 —— the `GET /v1/capabilities` `sealedKey` segment: exactly three keys — the algorithm (the pinned v1
+ * {@link SEALED_KEY_ALG}, never a hand-copied literal), the id to write into `sealedApiKey.publicKeyId`, and the
+ * base64 X25519 public key to `crypto_box_seal` against. `createdAt` is deliberately NOT projected (it answers
+ * nothing a sealer needs; the wire keeps to the three keys the contract names).
+ */
+export interface SealedKeyCapability {
+    readonly alg: typeof SEALED_KEY_ALG;
+    readonly publicKeyId: string;
+    readonly publicKey: string;
+}
+/** The ONE projection from the public face to the caps segment. `undefined` in ⇒ `undefined` out: the caps route
+ *  omits the key entirely (present-iff this process built its custody store — see the route for the two meanings
+ *  of absence). */
+export declare function projectSealedKeyCapability(face: SealedKeyPublicFace | undefined): SealedKeyCapability | undefined;
 /** Why a model's sealed key could not be unsealed (the poison-pill diagnosis, see SealedKeyPoison). CUSTODY failures only:
  *  a sealedApiKey that is malformed (alg other than the pinned v1 SEALED_KEY_ALG, non-base64 ciphertext) makes the whole
  *  catalog entry unavailable instead (S-704 `config.model_entry_invalid`, settings-schema `SealedApiKey` is the shape

package/dist/sealed-key.js

@@ -8,6 +8,15 @@ import { centerFetch } from "./config-center/center-request.js";
 export const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
 const SEAL_OVERHEAD_BYTES = 48;
 const BASE64_STRICT = /^[A-Za-z0-9+/]+={0,2}$/;
+export function buildSealedKeyPublicFace(store) {
+    const { publicKeyId, publicKey, createdAt } = store.latest;
+    return { latest: { publicKeyId, publicKey, createdAt } };
+}
+export function projectSealedKeyCapability(face) {
+    if (face === undefined)
+        return undefined;
+    return { alg: SEALED_KEY_ALG, publicKeyId: face.latest.publicKeyId, publicKey: face.latest.publicKey };
+}
 export function sealedKeyPoison(publicKeyId, reason, errKind) {
     return { sealedKeyPoison: true, publicKeyId, reason, ...(errKind ? { errKind } : {}), at: new Date().toISOString() };
 }

package/dist/security.d.ts

@@ -3,6 +3,7 @@ import { type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import type { TaskRequestBody } from "./http/wire-types.js";
 import type { StagingHandle } from "./session-sync-kernel.js";
+import type { SessionFaceReader } from "./session-incarnation.js";
 /** One row of the session-list projection (CC /resume picker) — the durable session abstraction's enumeration
  *  output (§0.5). Mirrors {@link RunStore}'s shipped `SessionSummary` shape so the wire response is unchanged. */
 export interface SessionListItem {
@@ -16,7 +17,7 @@ export interface SessionListItem {
     /** K-5c (shell §K): the latest run's task_id — the shell's one-hop live-tail re-attach anchor on resume. */
     lastRunId: string | null;
     /** [ref]([ref]/[ref]):the LATEST run's **engine run id**(`TaskResult.runId`)when known —— OMIT-when-absent,
-     *  恒不铸 null。runs-ledger listers 从 latest run 的终局 `result` JSON 提取(⇒ 在跑 latest 键诚实缺席);
+     *  恒不铸 null。runs-ledger listers 从 latest run 的 `result` JSON 提取(终局与 park 时写、认领续跑即清空 —— S-173 ⇒ 在跑 latest 键诚实缺席);
      *  local lister 走 `noteTaskRun` 席实时记录(⇒ 在跑也在场)——两面缺席集合不完全相等,读法一致:
      *  缺席 = 「此行无已知 engine runId」,禁读成其它含义。⚠️ 与 `lastRunId`(= latest run 的 **task_id**)
      *  是两条身份轴,命名对齐 core `SessionStoreSummary.lastTaskRunId`。wire:additive 键零投影透传
@@ -94,6 +95,9 @@ export declare function legacyUnownedSessionOk(requirePrincipal: boolean, gateOw
 export declare function legacyUnownedAmnestyOpen(requirePrincipal: boolean, gateOwner: string | null): boolean;
 export type OwnerAwareSessionStore = SessionStore & {
     ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
+    /** S-790 / S-506([ref] §2)—— 属主 + **化身**一次读(`undefined` = 无此会话;行在而化身为空 ⇒ 响亮拒)。规则的唯一属主
+     *  是 `src/session-incarnation.ts`。只关心属主的消费点照旧读 `ownerOf`;判「这还是不是同一位住客」的读它。 */
+    sessionFaceOf?: SessionFaceReader;
     register?: (sessionId: string, owner: string | null) => Promise<void>;
     /** E16 — enumerate the caller's sessions (owner-filtered on the session store's OWN owner column).
      *  `includeUnowned` = [ref] 窄互认第二臂的**第三条件**(`owner IS NULL`)的 SQL 承载位:置真时

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

@@ -21,8 +21,8 @@
  *  · 名单型旋钮臂 —— `ENV_NAME_ALLOWLIST_KNOBS` 的每一只(`env-name-allowlist-knobs.ts`,表键派生):名单**原文**可能夹着一枚被错展开进来
  *    的令牌,按凭据类对待。服务侧三只(`LSP_ENV_ALLOW` S-699 / `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` S-713)同时是目录 secret 行,
  *    目录臂先认;本臂接住的是**不在服务目录里**的那一只 —— bake-runner 的 `BAKE_ENV_ALLOW`(它不是服务进程的配置)。
- * core 形状规则的缺口由 core 源头修 —— 7.30.1 #1072 已补 `KEYS|TOKENS|PASSWORDS`(S-616 提货),目录臂独担的只剩
- * `OTEL_EXPORTER_OTLP_HEADERS`(`*_HEADERS` 不在形状规则射程,是边界不是缺陷票)与名单型旋钮(形状规则按名判,本来就不该认它们)。
+ * core 形状规则的缺口由 core 源头修 —— 7.30.1 #1072 补 `KEYS|TOKENS|PASSWORDS`(S-616),7.33.7 #1180 按名认 OTLP 头变量一族(7.103.2 车PM 提货;目录臂照旧点名
+ * `OTEL_EXPORTER_OTLP_HEADERS` = 双保险,互证钉在 `test/secret-env-scrub-disclosure.test.ts`),目录臂独担的只剩名单型旋钮(值是变量名单,core 本来就不该认它们)。
  * 本层不改 core 的判据,也不自造第二份形状规则。目录里加一个 secret 型键 / 叶表加一只名单型旋钮,每条腿当场就剥它。
  *
  * ## 不变的面

package/dist/session-children-retire.d.ts

@@ -0,0 +1,92 @@
+/**
+ * S-790 件B([ref] §3)—— **删会话带走以它为根的后台子代**:一只会话被删,以它为根的子代跟着结束 —— parked 的作废
+ * (行转终态,审批卡随之离开待决面),在跑的停掉。**这件事做完,才删会话元数据**(调用方:`boot/session-faces.ts` 的删除协调器)。
+ *
+ * ## 两步、两种失败,类型上分开(合并复审 gpt-6 腿 [high] 之后的形,裁定 2026-09-28)
+ *  1. {@link probeSessionChildren} —— **可达性预检,零写**。在协调器的任何破坏性步骤**之前**跑:有本进程结束不了的子代(在别的副本上
+ *     跑的 running 行:本进程没有它的句柄、耐久行的写者不是本进程 —— 本进程 `stopTask` 对它只答 `not_local`)⇒
+ *     `{ reachable: false, unreachableHandles }`,协调器立刻答 409 `conflict.session_children_alive`,一行不删。409 的语义因此只有一句:**拒在删之前**。
+ *     (修前的形是「先删账本、再结束子代、结束不了再答 409」—— 409 说「什么都没删」,而 run / event 账本已经提交删除了。)
+ *  2. {@link retireSessionChildren} —— 结束子代(预检之后、账本删除之后)。停不净的只可能是**时序**失败(本进程发出的停止还没落盘 /
+ *     一只在预检与停止之间冒出来的子代),不是可达性 ⇒ `{ stopped: "incomplete", remainingHandles }`,协调器按既有腿的失败契约**抛**
+ *     {@link SessionChildrenStopIncompleteError}(路由通用 500),不删 session_meta,幂等重试收敛。
+ *  「一个 `remaining > 0` 同时表示两件事」的双关由此消失:预检的失败是 409,结束的失败是 500,两只函数、两个返回型。
+ *
+ * ## 动词(core 板 [ref] ⑧⑨ 给定;本车第零步探针 `test/core-probe-parked-stop-root-access.test.ts` 真跑证实)
+ *  · 枚举 = `agentStore.listBySession(scope, 根会话)`(耐久行,锚 = 行的 session / parent / root 任一),并上本进程登记表里的
+ *    `activeDelegationHandles(scope, 根会话)`(没接耐久店的部署只有这一半)。scope 轴由调用方给(协调器:会话行的 `owner ?? "default"`)。
+ *  · **parked** 行 ⇒ `checkpointStore.expire(token, 卡自己的 scope)`(与 core 自己的本进程仲裁器同一只 CAS)+
+ *    `registry.reconcileParkedAgents(stores, scope)` ⇒ 行 `failed`(stoppedBy `system`)、卡离开待决面。任何副本上都做得到 ⇒ 预检把它
+ *    算作可达(前提是本部署有 checkpoint 店)。
+ *    ⚠️ **不对 parked 行调 `stopTask`**:只在耐久店里的行(park 它的进程不在 / 别的副本 / 重启后 —— parked 行活过重启是常态)
+ *    `stopTask` 什么都不改;本进程里的活 handle 先 expire 再 stopTask,core 答误导的 `park_resume_won`(core [ref] 原文)。
+ *  · **running** 行 ⇒ `stopTask(handle, { scope, sessionId: 根会话 })` ⇒ `killed`。可达与否**只有一个判据**,与 core `stopTask` 答 `not_local`
+ *    的那一条同源({@link runsOnAnotherReplica}):本进程**没有**这只句柄(不论状态)**且**耐久行 running、写者(`writerId`)不是本进程
+ *    (`registry.writerId`)⇒ 不可达(别的副本 / 写它的进程已不在)。本进程有句柄 —— 哪怕已经 killed、终态写还在飞 —— 或耐久行的写者就是
+ *    本进程 ⇒ 可达,交给有上界的结束循环(已停的句柄上 `stopTask` 是 no-op,循环等耐久写落地;等不到就是时序失败 500)。
+ *    (修复验证轮两条 opus 腿同命中:修前预检看的是内存句柄的**状态**(不是 running / pending ⇒ 够不着),本副本刚停、写在飞的子代因此被答成
+ *    「在别的副本上」的 409 —— 同一个「这只子代在不在本进程」的判断有两个写者。)
+ *
+ * ## 循环(有上界)
+ * 作废 / 停止与一次并发的 `/decide` 可能交错:expire 的 CAS 输给了决定腿的 resolve ⇒ 那只子代被唤醒成 running ⇒ 下一轮枚举看见
+ * 它、停掉它。循环到「枚举不出活的子代」为止,轮数有上界({@link RETIRE_MAX_ROUNDS});本进程 kill 的耐久写是 core 的异步写链,
+ * 两轮之间留一小段退避让它落盘。
+ */
+import type { BackgroundAgentStore, CheckpointStore, TaskRegistry } from "@sema-agent/core";
+/** 重新枚举的轮数上界。 */
+export declare const RETIRE_MAX_ROUNDS = 6;
+/** 两步共用的枚举口。 */
+interface ChildrenSource {
+    agentStore: BackgroundAgentStore | undefined;
+    registry: Pick<TaskRegistry, "activeDelegationHandles">;
+}
+export interface ProbeSessionChildrenDeps extends ChildrenSource {
+    /** 缺席 = 本部署没有耐久审批;撞见 parked 行却没有它 ⇒ 那只作废不了 ⇒ 不可达(拒在删之前)。 */
+    checkpointStore: Pick<CheckpointStore, "get" | "expire"> | undefined;
+    registry: Pick<TaskRegistry, "activeDelegationHandles" | "getAccessibleTask" | "writerId">;
+}
+export interface RetireSessionChildrenDeps extends ChildrenSource {
+    /** 缺席 = 本部署没有耐久审批(不可能有 parked 行);撞见 parked 行却没有它 ⇒ 那只作废不了,留到剩余(预检本该已经拒掉它)。 */
+    checkpointStore: Pick<CheckpointStore, "get" | "expire"> | undefined;
+    registry: Pick<TaskRegistry, "stopTask" | "reconcileParkedAgents" | "activeDelegationHandles">;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** 可达性预检的结果(零写)。`unreachableHandles` 只含本进程结束不了的那几只;可达的子代不在这里。 */
+export type SessionChildrenReachability = {
+    readonly reachable: true;
+    readonly live: number;
+} | {
+    readonly reachable: false;
+    readonly live: number;
+    readonly unreachableHandles: readonly string[];
+};
+/** 结束子代的结果。`incomplete` = 时序失败(本进程的停止还没落盘 / 预检之后冒出来的子代),不是可达性。 */
+export type RetireSessionChildrenOutcome = {
+    readonly stopped: "all";
+    readonly found: number;
+    readonly rounds: number;
+} | {
+    readonly stopped: "incomplete";
+    readonly found: number;
+    readonly rounds: number;
+    readonly remainingHandles: readonly string[];
+};
+/**
+ * **可达性预检**(零写;协调器在任何破坏性步骤之前调)。parked 行在有 checkpoint 店时可达(expire + reconcile 在任何副本上都成);
+ * running 行除非 {@link runsOnAnotherReplica} 都可达(`getAccessibleTask` / `agentStore.get` 都是纯读,不动任何东西)。
+ */
+export declare function probeSessionChildren(deps: ProbeSessionChildrenDeps, rootSessionId: string, scope: string): Promise<SessionChildrenReachability>;
+/** 以 `rootSessionId` 为根、在 `scope` 分区里的后台子代:作废 parked、停掉 running,重新枚举到没有活的为止(有上界)。 */
+export declare function retireSessionChildren(deps: RetireSessionChildrenDeps, rootSessionId: string, scope: string): Promise<RetireSessionChildrenOutcome>;
+/**
+ * 结束子代这一步的**时序**失败(可达性已在预检过了):本进程发出的停止在上界内没有全部落地。协调器抛它 ⇒ 路由通用 500;
+ * session_meta 不删(E21「子腿失败 ⇒ 不删 meta ⇒ 幂等重试收敛」的既有契约),账本那一腿此时已经删了 —— 与任何一条子腿中途失败同形。
+ * 文案不带句柄(句柄进运维 warn `session_delete_children_stop_incomplete`)。
+ */
+export declare class SessionChildrenStopIncompleteError extends Error {
+    readonly sessionId: string;
+    readonly remaining: number;
+    constructor(sessionId: string, remaining: number);
+}
+export {};
+//# sourceMappingURL=session-children-retire.d.ts.map

package/dist/session-children-retire.js

@@ -0,0 +1,85 @@
+export const RETIRE_MAX_ROUNDS = 6;
+const RETIRE_BACKOFF_MS = [0, 25, 50, 100, 200, 400];
+async function liveChildren(deps, rootSessionId, scope) {
+    const out = new Map();
+    if (deps.agentStore !== undefined) {
+        for (const s of await deps.agentStore.listBySession(scope, rootSessionId)) {
+            if (s.status === "running" || s.status === "parked")
+                out.set(s.handle, { handle: s.handle, status: s.status });
+        }
+    }
+    for (const handle of deps.registry.activeDelegationHandles(scope, rootSessionId)) {
+        if (!out.has(handle))
+            out.set(handle, { handle, status: "running" });
+    }
+    return [...out.values()];
+}
+export async function probeSessionChildren(deps, rootSessionId, scope) {
+    const live = await liveChildren(deps, rootSessionId, scope);
+    const unreachableHandles = [];
+    for (const child of live) {
+        const unreachable = child.status === "parked" ? deps.checkpointStore === undefined : await runsOnAnotherReplica(deps, child.handle, rootSessionId, scope);
+        if (unreachable)
+            unreachableHandles.push(child.handle);
+    }
+    return unreachableHandles.length === 0 ? { reachable: true, live: live.length } : { reachable: false, live: live.length, unreachableHandles };
+}
+async function runsOnAnotherReplica(deps, handle, rootSessionId, scope) {
+    if (deps.registry.getAccessibleTask(handle, { scope, sessionId: rootSessionId }) !== undefined)
+        return false;
+    if (deps.agentStore === undefined)
+        return false;
+    const row = await deps.agentStore.get(handle, scope);
+    return row?.status === "running" && row.writerId !== deps.registry.writerId;
+}
+export async function retireSessionChildren(deps, rootSessionId, scope) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let live = await liveChildren(deps, rootSessionId, scope);
+    const found = live.length;
+    let rounds = 0;
+    while (live.length > 0 && rounds < RETIRE_MAX_ROUNDS) {
+        rounds++;
+        let parkedSeen = false;
+        for (const child of live) {
+            if (child.status === "parked") {
+                parkedSeen = true;
+                await expireParkedCard(deps, child.handle, scope);
+            }
+            else {
+                await deps.registry.stopTask(child.handle, { scope, sessionId: rootSessionId }, deps.agentStore !== undefined ? { agentStore: deps.agentStore } : {});
+            }
+        }
+        if (parkedSeen && deps.agentStore !== undefined && deps.checkpointStore !== undefined) {
+            await deps.registry.reconcileParkedAgents({ agentStore: deps.agentStore, checkpointStore: deps.checkpointStore }, scope, Date.now());
+        }
+        await sleep(RETIRE_BACKOFF_MS[Math.min(rounds, RETIRE_BACKOFF_MS.length - 1)]);
+        live = await liveChildren(deps, rootSessionId, scope);
+    }
+    return live.length === 0
+        ? { stopped: "all", found, rounds }
+        : { stopped: "incomplete", found, rounds, remainingHandles: live.map((c) => c.handle) };
+}
+async function expireParkedCard(deps, handle, scope) {
+    if (deps.agentStore === undefined || deps.checkpointStore === undefined)
+        return;
+    const row = await deps.agentStore.get(handle, scope);
+    if (row === null || row.status !== "parked" || row.parkedCheckpointToken === undefined)
+        return;
+    const token = row.parkedCheckpointToken;
+    const cp = await deps.checkpointStore.get(token);
+    if (cp === null || cp.status !== "pending")
+        return;
+    await deps.checkpointStore.expire(token, cp.scope);
+}
+export class SessionChildrenStopIncompleteError extends Error {
+    sessionId;
+    remaining;
+    constructor(sessionId, remaining) {
+        super(`session ${sessionId}: ${remaining} background agent(s) this replica stopped had not settled within ${RETIRE_MAX_ROUNDS} rounds — ` +
+            `the session record was kept so the delete can be retried (it converges once they settle)`);
+        this.sessionId = sessionId;
+        this.remaining = remaining;
+        this.name = "SessionChildrenStopIncompleteError";
+    }
+}
+//# sourceMappingURL=session-children-retire.js.map

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

@@ -0,0 +1,58 @@
+/**
+ * 🔴 **core `SessionError` 闭集 → HTTP 的唯一映射**(S-612,server 7.104.0;设计稿 [ref] §2.1)。
+ *
+ * ## 为什么要一只属主
+ * 修前 wire 上只有**一处**认得 `SessionError` 的码:`http/routes/session-sync.ts` 的暂存导入腿把 `invalid_session`
+ * 手写成 422。其余每一条路都把它交给全局兜底 ⇒ `500 internal.error "internal error"`,码丢。core 7.30.0(#1041)
+ * 给文件会话店铸了 `corrupt_session`(存档没有会话头 ⇒ 这只会话唤不醒),而它在 wire 上一个名字都没有
+ * (真跑读数见 S-612 收车档 §0:冷启动时三条提交口与每一条经归属探针 / 读存档碰到它的口都答 500 `internal.error`;
+ * owner 已知时同步口是 200 + failed 体、并照常走计费收尾)。
+ *
+ * ## 为什么多一个 `face` 参数(而不是单参)
+ * core 的 `invalid_session` 是**同词两义**(亲读 dist:`engine/session/import-validate.js` 的导入门拒调用方交来的
+ * 日志,`engine/session/storage-base.js` 的建树 / 走根拒**已存**日志里指向缺席条目的叶子或祖先 —— 后者即 core #1077)。
+ * 本仓对它的成文义是前者(调用方的日志没过校验 ⇒ 422),而后者今天在打开会话的各口上答的是通用 500 / 同步口
+ * 200 + failed(S-612 的 3b 负控格钉住这一形,#1077 落地后按 core 的新码再对一次)。单参签名装不下这件事:要么
+ * 打开面的每个消费点都写一句 `code === "corrupt_session"` 特判,要么把 #1077 形从今天的应答改成「你交的日志坏了」。
+ * ⇒ 面是映射的一维,写进属主,不散在消费点。
+ *  · `"open"`   —— 为某只会话**打开它已存的日志**(提交各腿的引擎 prepare、鉴权门的归属探针、直接读会话的口);
+ *  · `"import"` —— 校验 / 写入**调用方交来的**日志(2c session-sync 的暂存导入)。
+ *
+ * ## 逐词(`undefined` = 登记过的留白:这个词在这一面上没有自己的 wire 答复,站点的既有处置照旧)
+ *  · `corrupt_session` —— 两面同答 **500 `corrupt_session`**。这只会话的存档读不出、唤不醒。不是 4xx:调用方没做错
+ *    任何事;不是 503:重试改不了判(修复在运维手里)—— 与会话规则店的 `corrupt` 同一档同一理由。码不另铸(core 的词
+ *    原样上 wire,契约既有立场:不为上游码铸孪生码)。三种会话后端同词:文件店由 core 铸,两只 SQL 店由
+ *    `plugins/session-event-payload.ts` 铸(坏的 `session_event.payload` 行)。
+ *  · `invalid_session` —— `import` 面 **422 `invalid_entries`**(修前 session-sync 的那一行,码位 / 状态逐字不变);
+ *    `open` 面留白(#1077 形,见上)。
+ *  · `not_found` —— 留白:每一面各有自己的「不存在」答法(404 `not_found.session` / 同步口的 `resume.session_not_found` /
+ *    列表里的缺席),码位各不相同,不由本表统一。
+ *  · `invalid_entry` / `invalid_fork_target` / `placement_refused` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
+ *    应答(它们在 core 的追加 / 分叉 / 放置面上抛,落进各站点既有的处置或通用 500)。给它们起名是另一件事、另一张票。
+ *  · `storage` / `conflict` / `unknown` —— 留白:`conflict` 由提交腿的 CAS 冲突臂按结果处置(`runs.ts`
+ *    `isSessionConflictResult`),`storage` / `unknown` 是故障类,通用 500 就是它们今天的应答。
+ *
+ * core 给闭集加一个词 ⇒ 下面的 `switch` 编译红,由人裁定它在两面上的答复,而不是让它静默落进某个恰好存在的臂
+ * ([ref] 词表纪律;同形先例 `session-policy-wire.ts` 的 `sessionPolicyErrorHttp`)。
+ */
+import type { SessionError } from "@sema-agent/core";
+/** core `SessionError` 的码闭集(core 不从包根导出这个型名 ⇒ 从导出类的 `code` 键派生,不手抄)。 */
+export type SessionErrorCode = SessionError["code"];
+/** 映射的面(见文件头注)。 */
+export type SessionErrorFace = "open" | "import";
+/** 一个词在一面上的 wire 答复。 */
+export interface SessionErrorWire {
+    readonly status: number;
+    readonly errorCode: string;
+    /**
+     * 固定句(缺席 = 发 core 的原句,过既有脱敏)。只有 import 面的 `invalid_session` 用它:core 导入门的原句点名的是
+     * 调用方日志里的条目 id / 父子关系,修前这一口就只回一句固定话(冻结在 `test/api-error-text-freeze.test.ts` 的
+     * 常量锚格),本批逐字不改。
+     */
+    readonly sentence?: string;
+}
+/** import 面 `invalid_session` 的固定句(修前 session-sync 暂存导入腿那一行的原文)。 */
+export declare const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
+export declare function sessionErrorHttp(code: SessionErrorCode, face: SessionErrorFace): SessionErrorWire | undefined;
+export declare function isSessionErrorCode(code: string): code is SessionErrorCode;
+//# sourceMappingURL=session-error-wire.d.ts.map

package/dist/session-error-wire.js

@@ -0,0 +1,38 @@
+export const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
+const CORRUPT_SESSION = { status: 500, errorCode: "corrupt_session" };
+const INVALID_ENTRIES = { status: 422, errorCode: "invalid_entries", sentence: STAGED_IMPORT_INVALID_SENTENCE };
+export function sessionErrorHttp(code, face) {
+    switch (code) {
+        case "corrupt_session":
+            return CORRUPT_SESSION;
+        case "invalid_session":
+            return face === "import" ? INVALID_ENTRIES : undefined;
+        case "not_found":
+        case "invalid_entry":
+        case "invalid_fork_target":
+        case "placement_refused":
+        case "storage":
+        case "conflict":
+        case "unknown":
+            return undefined;
+        default: {
+            const unhandled = code;
+            throw new Error(`unhandled SessionError code: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+const SESSION_ERROR_CODE_PRESENCE = {
+    not_found: true,
+    invalid_session: true,
+    invalid_entry: true,
+    invalid_fork_target: true,
+    storage: true,
+    conflict: true,
+    placement_refused: true,
+    corrupt_session: true,
+    unknown: true,
+};
+export function isSessionErrorCode(code) {
+    return Object.hasOwn(SESSION_ERROR_CODE_PRESENCE, code);
+}
+//# sourceMappingURL=session-error-wire.js.map