@sema-agent/server 7.126.0 → 7.127.1

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

@@ -11,6 +11,7 @@ import { spaceCommitAlive } from "../workspace-space-commit.js";
 import { incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
 import { WORKSPACE_CACHE_SPACE_LABEL, workspaceCacheClaimOf, workspaceCacheEnv } from "../workspace-cache.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { SANDBOX_IPV6_DEFAULT, sandboxEgressGaps, sandboxPodSysctls } from "../sandbox-egress-policy.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -73,7 +74,38 @@ function spaceLaneOf(policy, occupant) {
 function spaceReadFailed(what, detail, cause) {
     return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace space ${what} read failed${detail}`, cause instanceof Error ? cause : undefined) };
 }
+function restoreFailureIsTransient(cls) {
+    switch (cls) {
+        case "timeout":
+        case "transport":
+        case "store_busy":
+            return true;
+        case "download":
+        case "untar":
+            return false;
+        default: {
+            const unreachable = cls;
+            throw new Error(`unhandled restore failure class: ${String(unreachable)}`);
+        }
+    }
+}
+const RESTORE_MAX_ATTEMPTS = { park: 1, space: 2 };
 const RESTORE_DOWNLOAD_EXIT = 22;
+const RESTORE_TRANSFER_EXIT = 75;
+const RESTORE_STORE_BUSY_STATUSES = [408, 429, 500, 502, 503, 504];
+const RESTORE_STORE_BUSY_EXIT = 69;
+function restoreClassOfExit(exitCode) {
+    switch (exitCode) {
+        case RESTORE_STORE_BUSY_EXIT:
+            return "store_busy";
+        case RESTORE_DOWNLOAD_EXIT:
+            return "download";
+        case RESTORE_TRANSFER_EXIT:
+            return "transport";
+        default:
+            return "untar";
+    }
+}
 const SPACE_COMMIT_POLL_MS = 1000;
 class FenceCallAborted extends Error {
     constructor() {
@@ -92,6 +124,8 @@ export function errorMessageOf(e) {
     return typeof m === "string" && m ? m : String(e);
 }
 export { exitCodeFromStatus } from "./k8s-exec-protocol.js";
+export const K8S_SANDBOX_NAMESPACE_DEFAULT = "sandboxes";
+const SANDBOX_POD_LABELS = { app: "sema-sandbox", "managed-by": "sema-server" };
 export class RemoteK8sExecutionEnv {
     capabilities;
     cwd;
@@ -101,6 +135,7 @@ export class RemoteK8sExecutionEnv {
     handleSnapshotId;
     inFlightExecs = 0;
     connectPromise;
+    restoreRefusal;
     homeDir;
     cdPath = "unknown";
     cfg;
@@ -119,7 +154,7 @@ export class RemoteK8sExecutionEnv {
             token: config.token,
             caCert: config.caCert,
             insecureTls: config.insecureTls ?? false,
-            namespace: config.namespace ?? "sandboxes",
+            namespace: config.namespace ?? K8S_SANDBOX_NAMESPACE_DEFAULT,
             image: config.image,
             runtimeClass: config.runtimeClass ?? "kata-qemu",
             mountPath: config.mountPath ?? K8S_WORKSPACE_MOUNT_DEFAULT,
@@ -130,6 +165,7 @@ export class RemoteK8sExecutionEnv {
             dataTimeoutMs: dataTimeoutMsOf(config),
             cpu: config.cpu ?? "1",
             memory: config.memory ?? "2Gi",
+            ipv6: config.ipv6 ?? SANDBOX_IPV6_DEFAULT,
             retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 1000 },
             ...(config.s3Snapshot ? { s3Snapshot: config.s3Snapshot } : {}),
             ...(config.sessionId ? { sessionId: config.sessionId } : {}),
@@ -256,6 +292,8 @@ export class RemoteK8sExecutionEnv {
             case "unreadable":
                 return this.provision(signal);
             case "open": {
+                if (this.restoreRefusal)
+                    return this.restoreRefusal;
                 const settled = await this.awaitSpaceCommit(lane.space, signal);
                 if (!settled.ok)
                     return settled;
@@ -439,6 +477,23 @@ export class RemoteK8sExecutionEnv {
             return { ok: false, reason: "delete_failed", detail: `claim delete-by-label failed: ${errorMessageOf(e)}` };
         }
     }
+    async egressPolicyGaps() {
+        const read = async (apiPath) => {
+            try {
+                const r = await this.request("GET", apiPath);
+                return r.status >= 200 && r.status < 300 ? { ok: true, json: r.json } : { ok: false, detail: `HTTP ${r.status}` };
+            }
+            catch (e) {
+                return { ok: false, detail: errorMessageOf(e) };
+            }
+        };
+        const nodes = await read("/api/v1/nodes");
+        const policies = await read(`/apis/networking.k8s.io/v1/namespaces/${this.cfg.namespace}/networkpolicies`);
+        const probe = { metadata: { labels: { ...SANDBOX_POD_LABELS } }, spec: {} };
+        if (this.cfg.podSpecPatch?.labels)
+            applyPodSpecPatch(probe, { labels: this.cfg.podSpecPatch.labels });
+        return sandboxEgressGaps({ nodes, policies, podLabels: probe.metadata.labels, ipv6: this.cfg.ipv6 });
+    }
     reclaimDeadlinePassed(what) {
         return `reclaim deadline (${this.cfg.dataTimeoutMs} ms, the snapshot time bound, one per reclaim call) passed — ${what}`;
     }
@@ -457,15 +512,17 @@ export class RemoteK8sExecutionEnv {
     async createPod(signal, cache) {
         const ns = this.cfg.namespace;
         const podEnv = { ...(cache ? workspaceCacheEnv(cache.mount) : {}), ...(this.cfg.podEnv ?? {}) };
+        const sysctls = sandboxPodSysctls(this.cfg.ipv6);
         const pod = {
             apiVersion: "v1",
             kind: "Pod",
             metadata: {
                 generateName: "sbx-",
-                labels: { app: "sema-sandbox", "managed-by": "sema-server" },
+                labels: { ...SANDBOX_POD_LABELS },
             },
             spec: {
                 ...(this.cfg.runtimeClass ? { runtimeClassName: this.cfg.runtimeClass } : {}),
+                ...(sysctls ? { securityContext: { sysctls: sysctls.map((x) => ({ ...x })) } } : {}),
                 restartPolicy: "Never",
                 automountServiceAccountToken: false,
                 activeDeadlineSeconds: Math.ceil(this.cfg.timeoutMs / 1000),
@@ -843,39 +900,73 @@ export class RemoteK8sExecutionEnv {
         const presigned = this.presignSnapshot({ ...target, method: "GET", snapshotId });
         if (!presigned.ok)
             return presigned;
-        const c = await this.provision(abortSignal);
-        if (!c.ok)
-            return c;
         const url = presigned.value;
-        const cmd = `code=$(curl -s -o /tmp/ws.tgz -w '%{http_code}' ${shellQuote(url)}); ` +
+        const cmd = `code=$(curl -s -o /tmp/ws.tgz -w '%{http_code}' ${shellQuote(url)}); rc=$?; ` +
+            `if [ "$rc" != "0" ]; then echo "snapshot GET got no whole answer (curl exit $rc, HTTP $code)" >&2; exit ${RESTORE_TRANSFER_EXIT}; fi; ` +
             `if [ "$code" = "404" ]; then echo EMPTY_SNAPSHOT; exit 0; fi; ` +
+            `case "$code" in ${RESTORE_STORE_BUSY_STATUSES.join("|")}) echo "snapshot GET HTTP $code" >&2; exit ${RESTORE_STORE_BUSY_EXIT};; esac; ` +
             `if [ "$code" != "200" ]; then echo "snapshot GET HTTP $code" >&2; exit ${RESTORE_DOWNLOAD_EXIT}; fi; ` +
             `tar xzf /tmp/ws.tgz -C ${shellQuote(this.cfg.mountPath)} && rm -f /tmp/ws.tgz`;
-        const r = await this.runExec(cmd, { timeoutMs: this.cfg.dataTimeoutMs, livenessMs: 0 });
-        const failure = !r.ok
-            ? { cls: r.error.code === "timeout" ? "timeout" : "transport", detail: `workspace snapshot restore failed: ${this.redactUrl(r.error.message, url)}`, cause: r.error }
-            : r.value.exitCode !== 0
-                ? { cls: r.value.exitCode === RESTORE_DOWNLOAD_EXIT ? "download" : "untar", detail: `workspace snapshot restore exited ${r.value.exitCode}: ${this.redactUrl(r.value.stderr, url).slice(0, 300)}` }
-                : undefined;
-        if (failure) {
+        for (let attempt = 1;; attempt++) {
+            const c = await this.provision(abortSignal);
+            if (!c.ok)
+                return c;
+            const r = await this.runExec(cmd, { timeoutMs: this.cfg.dataTimeoutMs, livenessMs: 0 });
+            const failure = !r.ok
+                ? { cls: r.error.code === "timeout" ? "timeout" : "transport", detail: `workspace snapshot restore failed: ${this.redactUrl(r.error.message, url)}`, cause: r.error }
+                : r.value.exitCode !== 0
+                    ? { cls: restoreClassOfExit(r.value.exitCode), detail: `workspace snapshot restore exited ${r.value.exitCode}: ${this.redactUrl(r.value.stderr, url).slice(0, 300)}` }
+                    : undefined;
+            if (!failure) {
+                if (target.lane === "space" && r.ok && r.value.stdout.includes("EMPTY_SNAPSHOT"))
+                    await this.dropDanglingLatest(target.space, snapshotId);
+                return ok(this.workspaceHandle());
+            }
             const name = this.podName;
             this.podName = undefined;
             this.podIP = undefined;
             if (name)
                 await this.deletePod(name).catch(() => { });
-            if (target.lane === "park")
-                return { ok: false, error: new RemoteExecutionError("connect_failed", failure.detail, failure.cause) };
-            this.spaceLine("workspace_restore_failed", target.space, { snapshotId, class: failure.cls, boundMs: this.cfg.dataTimeoutMs, error: failure.detail });
-            return {
-                ok: false,
-                error: new RemoteExecutionError("connect_failed", `${failure.detail} — the workspace's latest snapshot (${snapshotId}) is in the store but did not come back (${failure.cls}, bound ${this.cfg.dataTimeoutMs}ms), ` +
-                    "so this run does not start on an empty /workspace. Ways out: raise WORKSPACE_SNAPSHOT_TIMEOUT_MS if the archive is large, " +
-                    "or set WORKSPACE_PERSIST=off for one run (it starts from an empty /workspace and deletes no snapshot)", failure.cause),
-            };
+            if (attempt < RESTORE_MAX_ATTEMPTS[target.lane] && restoreFailureIsTransient(failure.cls)) {
+                if (await this.restorePause(abortSignal))
+                    continue;
+                return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while retrying the workspace restore") };
+            }
+            switch (target.lane) {
+                case "park":
+                    return { ok: false, error: new RemoteExecutionError("connect_failed", failure.detail, failure.cause) };
+                case "space": {
+                    const tries = attempt === 1 ? "1 attempt" : `${attempt} attempts`;
+                    this.spaceLine("workspace_restore_failed", target.space, { snapshotId, class: failure.cls, attempts: attempt, boundMs: this.cfg.dataTimeoutMs, error: failure.detail });
+                    this.restoreRefusal = {
+                        ok: false,
+                        error: new RemoteExecutionError("connect_failed", `${failure.detail} — the workspace's latest snapshot (${snapshotId}) is in the store but did not come back (${failure.cls}, ${tries}, bound ${this.cfg.dataTimeoutMs}ms each), ` +
+                            "so this run does not start on an empty /workspace. Ways out: raise WORKSPACE_SNAPSHOT_TIMEOUT_MS if the archive is large, " +
+                            "or set WORKSPACE_PERSIST=off for one run (it starts from an empty /workspace and deletes no snapshot)", failure.cause),
+                    };
+                    return this.restoreRefusal;
+                }
+                default: {
+                    const unreachable = target;
+                    throw new Error(`unhandled snapshot lane: ${String(unreachable.lane)}`);
+                }
+            }
         }
-        if (target.lane === "space" && r.ok && r.value.stdout.includes("EMPTY_SNAPSHOT"))
-            await this.dropDanglingLatest(target.space, snapshotId);
-        return ok(this.workspaceHandle());
+    }
+    restorePause(signal) {
+        return new Promise((resolve) => {
+            if (signal?.aborted)
+                return resolve(false);
+            const onAbort = () => {
+                clearTimeout(timer);
+                resolve(false);
+            };
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve(true);
+            }, this.cfg.retry.backoffMs);
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
     }
     async dropDanglingLatest(space, snapshotId) {
         const prefix = this.cfg.s3Snapshot?.keyPrefix ?? "kata";
@@ -1583,6 +1674,9 @@ export function createSpaceReclaimer(config, deps) {
         },
     };
 }
+export async function checkSandboxEgressPolicy(config, deps) {
+    return new RemoteK8sExecutionEnv(config, deps).egressPolicyGaps();
+}
 export function k8sExecutionEnvFactory(config, deps) {
     return (ctx) => new RemoteK8sExecutionEnv({ ...config, sessionId: ctx.sessionId }, deps);
 }

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

@@ -7,10 +7,11 @@ import type { StoreBackend } from "./store-backend.js";
  * - `memory` (default): core's in-memory `TtlSessionStore` (lost on restart, 7-day idle TTL).
  * - `tidb`: the durable "Session event-log center" (L1) — append-only events + wake/resume +
  *   cross-instance CAS (F2), on whichever SQL engine `DB_BACKEND` selects (TiDB or PG, via the store backend).
- *   Optionally wrapped in a warm cache (reuse a hot session across turns; requires session affinity) —
- *   set `SESSION_CACHE_TTL_SEC=0` to disable.
+ *   Optionally wrapped in a warm cache (reuse a hot session across turns; a hit is served only while the store's
+ *   head still names the cached leaf, so it is correct under any routing across replicas) — set
+ *   `SESSION_CACHE_TTL_SEC=0` to disable.
  */
-export declare function createSessionStore(config: ServiceConfig, backend?: StoreBackend, metrics?: {
+export declare function createSessionStore(config: Pick<ServiceConfig, "sessionBackend" | "sessionCacheTtlSec">, backend?: Pick<StoreBackend, "session">, metrics?: {
     inc(name: string, labels?: Record<string, string>, n?: number): void;
 }): SessionStore;
 /**

package/dist/plugins/session-store.js

@@ -6,7 +6,7 @@ export function createSessionStore(config, backend, metrics) {
             throw new Error("a DB session backend requires a store backend (DB_BACKEND=mysql|pg + a reachable DB).");
         const store = backend.session();
         return config.sessionCacheTtlSec > 0
-            ? new CachingSessionStore(store, { ttlSec: config.sessionCacheTtlSec, onConflictEvict: metrics ? () => metrics.inc("stale_cache_conflict_total") : undefined })
+            ? new CachingSessionStore(store, { ttlSec: config.sessionCacheTtlSec, onStaleHit: metrics ? () => metrics.inc("session_cache_stale_hit_total") : undefined })
             : store;
     }
     return new TtlSessionStore({ defaultTtlDays: 7 });

package/dist/plugins/store-backend.d.ts

@@ -5,6 +5,7 @@ import { type OutcomeSink } from "./file-outcome-sink.js";
 import { type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
 import { type OneTimeMigrationReport } from "./one-time-migrations.js";
+import type { SessionHeadReader } from "./caching-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { type ApprovalExemptionStore } from "./approval-exemption-store.js";
@@ -144,7 +145,11 @@ export interface StoreBackend {
     /** Protocol-truth kind (clay 2026-07-06 wording): "mysql" = any MySQL-protocol server (MySQL / TiDB /
      *  MariaDB) behind the one mysql2 pool — the startup summary prints durable(mysql) for all of them. */
     readonly kind: "mysql" | "pg" | "local";
-    /** Connect + create schema (also the reachability probe). */
+    /** Connect + create schema (also the reachability probe). On the SQL backends it first checks the database for the
+     *  schema that the one-time migrations of server 7.74.0–7.125.x retired and **refuses** with `RetiredSchemaPresentError`
+     *  (code `config.schema_mismatch`, exported from the package root) before it issues the first CREATE; only then does it create.
+     *  The check lives in this method itself, so the public sequence `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
+     *  needs no step of its own. The LOCAL backend has no SQL pool and nothing to probe. */
     ensureSchema(): Promise<void>;
     close(): Promise<void>;
     run(): RunStore;
@@ -337,8 +342,9 @@ export interface StoreBackend {
     breaker?(onWriteFail?: (streak: number) => void): BreakerStateStore;
     costQuota?(limitMicroUsd: number, windowMs: number, onDegraded?: CounterDegradeHook): CostQuotaStore;
     rateLimiter?(limit: number, onDegraded?: CounterDegradeHook): RateLimiterStore;
-    /** Session store (caller wraps caching). DB-backed on tidb/pg; the in-memory/file `LocalSessionStore` on local. */
-    session(): SessionStore;
+    /** Session store (caller wraps caching). DB-backed on tidb/pg; the in-memory/file `LocalSessionStore` on local. Carries the
+     *  head read the warm cache checks every hit against. */
+    session(): SessionStore & SessionHeadReader;
     /** The raw mysql2 pool — ONLY on the TiDB backend (undefined on PG). For the few TiDB-specific raw-SQL
      *  consumers outside the store abstraction (session audit, degenerate-output instrument); those features are
      *  no-ops on PG until ported. */
@@ -381,8 +387,9 @@ export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "l
  * 而兄弟行都写 `shared(${kind})`。)
  */
 export declare function counterStoreLabel(store: unknown, kind: string | undefined): string;
-/** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
- *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured.
+/** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily); the next
+ *  step is `ensureSchema()` (retired-schema check, then the CREATEs; it is also the reachability probe), then
+ *  `runOneTimeMigrations()`. Returns undefined when no DB is configured.
  *
  *  `onWarn` (additive, optional) is the boot-time warning sink the LOCAL backend needs for core's
  *  permission-rule DISCLOSURE face ([ref] §1): an unreadable / checksum-mismatched / symlinked rule file

package/dist/plugins/store-backend.js

@@ -12,7 +12,7 @@ import { FileRunStore } from "./file-run-store.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
-import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
+import { NO_SQL_MIGRATIONS, assertRetiredSchemaAbsentOnPool, runSqlOneTimeMigrations } from "./one-time-migrations.js";
 import { LocalSessionStore, createLocalSessionRepo } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
@@ -337,11 +337,20 @@ export function createStoreBackend(config, onWarn, onError) {
         if (!config.pg)
             return undefined;
         const pool = createPgPool(pgPoolOptions(config.pg, config.dbQueryTimeoutMs), onWarn);
-        return new PgBackend(pool, config);
+        return withRetiredSchemaProbe(new PgBackend(pool, config), { dialect: "pg", pool });
     }
     if (!config.tidb)
         return undefined;
-    return new TiDBBackend(createTidbPool(config), config);
+    const pool = createTidbPool(config);
+    return withRetiredSchemaProbe(new TiDBBackend(pool, config), { dialect: "tidb", pool });
+}
+function withRetiredSchemaProbe(inner, target) {
+    const guarded = Object.create(inner);
+    guarded.ensureSchema = async () => {
+        await assertRetiredSchemaAbsentOnPool(target);
+        await inner.ensureSchema();
+    };
+    return guarded;
 }
 export async function openStoreBackendWithFallback(config, logger) {
     const sqlEngine = config.dbBackend === "mysql" || config.dbBackend === "pg" ? config.dbBackend : undefined;

package/dist/plugins/store-contracts.d.ts

@@ -36,6 +36,9 @@ import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core"
  * 收法:**一个基类,一条重抛**。新 File 店的拒启只要 `extends StoreBootRefusalError` 就自动落在正确的
  * 一侧;忘了继承是**可见**的(它是一个必须显式选择的父类),而忘了往 if 链里加一行是不可见的。
  * (core 的 `AdoptionError` 不在本仓,改不了它的继承链 ⇒ 降级臂保留它那一条 `instanceof`,共两条。)
+ *
+ * 族的含义是「**确定的拒启表态**」,不限 File 店:SQL `ensureSchema()` 里库带着已退役 schema 的拒启(`RetiredSchemaPresentError`)也属此族。三处读它,读法一致 ——
+ * 降级臂不吞(穿过 `mayFallback`)、SQL 开库的等待窗不重试它(`store-open-wait.ts`:再等也等不来另一个答案)、「库打不开」的拒句不改写它(它自己的拒句才是真话)。
  */
 export declare class StoreBootRefusalError extends Error {
 }

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

@@ -1,4 +1,5 @@
 import { STORE_LOCK_POLL_MS } from "./store-lock-wait.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 const REAL_CLOCK = {
     now: () => performance.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -46,6 +47,8 @@ export async function openWithinWait(open, waitMs, onWait, clock = REAL_CLOCK) {
                     throw lastFailure.error;
                 throw new StoreOpenWindowExpired(waitMs);
             case "failed": {
+                if (outcome.error instanceof StoreBootRefusalError)
+                    throw outcome.error;
                 if (lastFailure === undefined)
                     onWait({ waitMs, error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) });
                 lastFailure = { error: outcome.error };

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

@@ -37,13 +37,26 @@ export type ScenarioBodyKey = (typeof TASK_BODY_SCENARIO_KEYS)[number];
 export type NamedKeysOf<T> = {
     [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
 };
-/**
- * FRESH 提交面的**顶层**键闭集裁决:受理集之外的键 ⇒ 返回拒体(调用方 400 `request.body_shape`);
- * 全部受理 ⇒ `null`。
- *
- * 判据边界(与 settings 那只同源,有意窄):只判**键名**;体本身非对象 ⇒ 本门不判(留给既有的
- * 「missing 'objective' string」那道门,免得同一个体被两句话抢答)。
- */
+/** FRESH 提交面(`POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs`)的顶层键裁决。 */
 export declare function taskBodyKeyIssue(raw: unknown): KeyClosureIssue | null;
+declare const RUN_STEER_BODY_KEYS: readonly ["mode", "priority", "text"];
+declare const CONTENT_STEER_BODY_KEYS: readonly ["content"];
+declare const INTERRUPT_STEER_BODY_KEYS: readonly ["text"];
+/** `POST /v1/runs/:id/steer` 的体形(键 = 受理集,值形由路由逐键判)。 */
+export type RunSteerBody = {
+    readonly [K in (typeof RUN_STEER_BODY_KEYS)[number]]?: unknown;
+};
+/** 子代 steer / resume 与 workflow 子代 steer 的体形。 */
+export type ContentSteerBody = {
+    readonly [K in (typeof CONTENT_STEER_BODY_KEYS)[number]]?: unknown;
+};
+/** `POST /v1/runs/:id/interrupt` 带 text 形的体形。 */
+export type InterruptSteerBody = {
+    readonly [K in (typeof INTERRUPT_STEER_BODY_KEYS)[number]]?: unknown;
+};
+/** 送话口的三种体形(闭集;词外是编译错)。 */
+export type SteerBodyForm = "run" | "content" | "interrupt";
+/** 送话口的顶层键裁决(四扇门同一只;`form` 选受理集)。 */
+export declare function steerBodyKeyIssue(raw: unknown, form: SteerBodyForm): KeyClosureIssue | null;
 export {};
 //# sourceMappingURL=request-key-closure.d.ts.map

package/dist/request-key-closure.js

@@ -32,26 +32,42 @@ const TASK_BODY_DECLARED_KEYS = [
 ];
 const TASK_BODY_SCENARIO_KEYS = ["repo"];
 const ACCEPTED_BODY = new Set([...TASK_BODY_DECLARED_KEYS, ...TASK_BODY_SCENARIO_KEYS]);
-const UNSUPPORTED_BODY = new Set(["handsReadOnly", "readDenyPatterns", "readFace", "shellGate", "writeFace"]);
-export function taskBodyKeyIssue(raw) {
+const UNSUPPORTED_BODY_KEYS = ["handsReadOnly", "readDenyPatterns", "readFace", "shellGate", "userAttachments", "writeFace"];
+const UNSUPPORTED_BODY = new Set(UNSUPPORTED_BODY_KEYS);
+const UNSUPPORTED_LABEL = "unsupported (an engine seat this service does not read from the request body — set by the deployment, or not offered in this version)";
+function closedBodyKeyIssue(raw, accepted, door) {
     if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
         return null;
     const buckets = { unknown: [], unsupported: [] };
-    scanKeyClosure(raw, "", ACCEPTED_BODY, UNSUPPORTED_BODY, buckets);
+    scanKeyClosure(raw, "", accepted, UNSUPPORTED_BODY, buckets);
     if (buckets.unknown.length === 0 && buckets.unsupported.length === 0)
         return null;
     buckets.unknown.sort();
     buckets.unsupported.sort();
     const parts = [
-        ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, "unknown (not a task-request key — check the spelling)")] : []),
-        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, "unsupported (an engine seat this service derives, never reads from the body)")] : []),
+        ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, `unknown (not ${door} key — check the spelling)`)] : []),
+        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, UNSUPPORTED_LABEL)] : []),
     ];
     return {
         message: `body: unrecognized top-level key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
             `${parts.join("; ")}. ` +
-            `Accepted: ${[...ACCEPTED_BODY].sort().join(",")}`,
+            `Accepted: ${[...accepted].sort().join(",")}`,
         unknownKeys: buckets.unknown.slice(0, MAX_KEY_ECHO),
         unsupportedKeys: buckets.unsupported.slice(0, MAX_KEY_ECHO),
     };
 }
+export function taskBodyKeyIssue(raw) {
+    return closedBodyKeyIssue(raw, ACCEPTED_BODY, "a task-request");
+}
+const RUN_STEER_BODY_KEYS = ["mode", "priority", "text"];
+const CONTENT_STEER_BODY_KEYS = ["content"];
+const INTERRUPT_STEER_BODY_KEYS = ["text"];
+const STEER_DOORS = {
+    run: { accepted: new Set(RUN_STEER_BODY_KEYS), door: "a steer-request" },
+    content: { accepted: new Set(CONTENT_STEER_BODY_KEYS), door: "a steer-request" },
+    interrupt: { accepted: new Set(INTERRUPT_STEER_BODY_KEYS), door: "an interrupt-request" },
+};
+export function steerBodyKeyIssue(raw, form) {
+    return closedBodyKeyIssue(raw, STEER_DOORS[form].accepted, STEER_DOORS[form].door);
+}
 //# sourceMappingURL=request-key-closure.js.map

package/dist/run-acceptance.d.ts

@@ -0,0 +1,51 @@
+/**
+ * **一次提交的「受理」读法** —— 标题器只在引擎**受理**这条 run 之后起(一条律,唯一属主 = 本文件)。
+ *
+ * ## 受理是哪一刻
+ * 引擎把这次提交的 objective 收进会话的那一帧:`human_input{ carrier: "objective", delivery: "applied" }`。它是第一次模型调用
+ * 之前的最后一帧;在它之前引擎能拒的一切 —— prepare 门(`config.tool_face_control` / `config.user_invoked_skill_unknown` /
+ * `config.memory_capture_unsupported` …)、第一回合前的内联图片准入(`config.image_invalid`)、部署的 UserPromptSubmit 拦截、
+ * 开跑前的预算 / 墙钟 —— 都还没让这次输入进会话。`wiring_manifest` 不是受理:它在 prepare 通过时就出了,图片准入与提示拦截
+ * 都在它之后(core `run-identity-wiring.js` 推 wiring_manifest,`run-leg.js` 才做图片准入、推 human_input、调模型)。
+ *
+ * 只回结果、不交流的腿(verify / cascade:core 在自己里面排空每条腿的流,宿主手里没有流)看不到那一帧。它们的受理证据是结果本身:
+ * 结果里跑过 turn(`stats.turns > 0`)⇒ objective 进过会话、模型答过。**token 不是证据**:被 UserPromptSubmit 拦下的 objective 不进会话,
+ * 而同一条 run 的收尾压缩可以在已有历史的会话上花 token(turns 0、tokens > 0)—— 按 token 判会把被拦下的输入送去起名。
+ * 两种证据说的是同一件事,本文件把它们收成一只闩:先到的那一个算数,只算一次。
+ *
+ * ## 受理之后 / 之前
+ *  · 受理 ⇒ 标题器起一次(会话没有标题时它才真去生成;判据在标题器里,本文件不重复)。
+ *  · 没受理就收场(零工作的拒、受理前取消 / 拦截)⇒ 标题器不起:被拒的输入不花一次模型调用,也不被送去起名。
+ *    这次提交在提交门铸下的会话行照旧留下(无标题、零消息),与此前同 —— 「提交没让引擎受理就收场」的会话去留是另一件事,不在本文件。
+ *
+ * ## 谁喂它
+ * 三条提交腿(同步 / 流式 / durable)各在两处喂同一只:持流的那一形把每一帧交给 {@link RunAcceptance.observe};终局落行之后调一次
+ * {@link RunAcceptance.settle}。腿上不再有「什么时候起标题」的判断,标题器的唯一调用点是本文件的闩。座由提交门在 `prepareSpec` 里
+ * 随 spec 一起铸(`PreparedTaskSubmission.acceptance`);不经提交门的内部车道铸一只不带标题器的座,也就不起标题。
+ */
+export interface RunAcceptanceDeps {
+    /** 标题器(缺席 = 本部署不自动起名)。 */
+    sessionTitler?: {
+        maybeTitle(sessionId: string, objective: string, model?: string): void;
+    };
+}
+export interface RunAcceptanceInput {
+    sessionId?: string;
+    objective: string;
+    /** 本 turn 真实驱动的模型 id(标题器与 turn 同链路)。 */
+    model?: string;
+}
+export interface RunAcceptance {
+    /** 持流的腿逐帧调用(判哪一帧算受理只在这里)。不抛、不等。 */
+    observe(ev: {
+        type: string;
+    }): void;
+    /** 终局落行之后:还没在流上见过受理帧、而结果里跑过 turn(只回结果的腿)⇒ 受理。只读 `stats.turns`。不抛、不等。 */
+    settle(result: {
+        readonly stats: {
+            readonly turns: number;
+        };
+    }): void;
+}
+export declare function createRunAcceptance(deps: RunAcceptanceDeps, input: RunAcceptanceInput): RunAcceptance;
+//# sourceMappingURL=run-acceptance.d.ts.map

package/dist/run-acceptance.js

@@ -0,0 +1,27 @@
+function isObjectiveApplied(ev) {
+    if (ev.type !== "human_input")
+        return false;
+    const h = ev;
+    return h.carrier === "objective" && h.delivery === "applied";
+}
+export function createRunAcceptance(deps, input) {
+    let accepted = false;
+    const accept = () => {
+        if (accepted)
+            return;
+        accepted = true;
+        if (input.sessionId)
+            deps.sessionTitler?.maybeTitle(input.sessionId, input.objective, input.model);
+    };
+    return {
+        observe(ev) {
+            if (!accepted && isObjectiveApplied(ev))
+                accept();
+        },
+        settle(result) {
+            if (result.stats.turns > 0)
+                accept();
+        },
+    };
+}
+//# sourceMappingURL=run-acceptance.js.map

package/dist/runs.d.ts

@@ -9,6 +9,7 @@ import type { QuestionCoordinator } from "./question.js";
 import { type ToolApprovalCoordinator } from "./tool-approval.js";
 import { type FleetRunPublisher } from "./fleet/fleet-bus.js";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
+import type { RunAcceptance } from "./run-acceptance.js";
 import type { VerifyRoundsSpec } from "./http/verify-rounds.js";
 import type { UserInputLedger } from "./user-input-ledger.js";
 /**
@@ -91,14 +92,6 @@ export declare function taskHandleStop(registry: typeof defaultTaskRegistry, han
  * 语义上这两种时序是同一件事:本请求赢下了这条 session,而这条 session 的连接是被人断掉的。
  */
 export declare function markChildrenStoppedByUserOnAbort(signal: AbortSignal, taskId: string, principal: string | null | undefined): void;
-/**
- * A session CAS conflict is swallowed by core into a failed `TaskResult` (it is not thrown from
- * `runTaskStream`), so detect it from the result. Prefer the structured `code` (core ≥1.8); fall
- * back to the conflict wording only for older results without one.
- */
-export declare function isSessionConflictResult(result: {
-    terminal: TerminalCause;
-}): boolean;
 export declare function resumeAtHttpStatus(result: {
     terminal: TerminalCause;
 }): number | undefined;
@@ -202,8 +195,6 @@ export declare function parkToolCallId(result: unknown, cs: ParkCheckpointReader
  *  不塞进 `checkpointGate`——那是 core 的类型,server 不改其形)。非 park / 无 token / tool-less /
  *  读失败 ⇒ **同一引用**原样返回(键缺席)。graft 不负责 strip——组合序恒为 graft → strip。 */
 export declare function graftParkToolCallId<T>(result: T, cs: ParkCheckpointReader | undefined): Promise<T>;
-/** Evict a stale warm-cache entry after a cross-instance write conflict (broken-affinity backstop). */
-export declare function evictIfConflict(runner: Runner, sessionId: string | undefined, result: TaskResult): void;
 /**
  * Drive a task to completion in the background, persisting its events to the durable run log (S2).
  *
@@ -328,7 +319,12 @@ trustedInternals?: Pick<RunInternals, "workflowParkedResume">,
  * 已收敛、未告知的崩溃丢失铸成 `task.user_steer_undrained` / `task.user_followup_undrained`(`cause:"crashed"`,码按受理时的车道选);腿收场时把本腿上的受理 settle 掉。
  * 缺席 ⇒ 两手都不做(与本参数存在之前逐字相同)。
  */
-userInputLedger?: UserInputLedger): Promise<void>;
+userInputLedger?: UserInputLedger, 
+/**
+ * 这次提交的受理座(`src/run-acceptance.ts`):标题器只在引擎受理之后起。普通流形逐帧喂;只回结果的 verify / cascade 形(以及终局写口的
+ * 重试腿)终局落行之后收尾一次。缺席 ⇒ 不起标题(起标题此前由路由层在建行时做)。
+ */
+acceptance?: RunAcceptance): Promise<void>;
 /** How often a running instance refreshes its run's updated_at (liveness, independent of events).
  *  Must stay strictly below `runStaleSec` (asserted at startup AND on every hot config candidate) or the
  *  reaper would race live runs. [ref]:数值的单源是 `config-invariants.ts`(那条不变量的属主),两个消费面