@sema-agent/server 1.322.0 → 2.0.0

package/dist/images/bake-validate.js

@@ -1,3 +1,24 @@
+/**
+ * Bake input WHITELIST + vetted-argv builder (IMAGE-API-DESIGN.md §P2.4 — the anti-RCE core).
+ *
+ * bands/profile/baseRef/bump compose a Dockerfile + a `FROM` + a `docker build` = arbitrary code on the build
+ * host. So EVERY field is validated SERVER-SIDE against a CLOSED SET *before* an argv is built; off-list → an
+ * error, never coerced. The runner only ever sees the VETTED argv this module emits (never operator free-text)
+ * and only runs `build.sh`, which composes Dockerfiles from the in-repo `bands/` via `gen-dockerfile.sh` — there
+ * is no path here to inject a raw Dockerfile or a shell command.
+ *
+ * Set membership is the gate (NOT regex): `^[a-z0-9-]+$` is belt-only — `python; rm -rf /` ∉ the frozen set →
+ * rejected, and the argv is a RAW vetted VECTOR the runner array-spawns (each element in its own argv slot, no
+ * shell), never concatenated into a command string.
+ *
+ * The frozen catalogs below MIRROR the recipe source of truth (`gen-dockerfile.sh` `profile_bands()` + the
+ * `bands/` dir). A DRIFT test (test/image-bake-validate.test.ts) asserts they still match — a silently-drifted
+ * list would either reject a valid profile or admit a removed band. Keep them in lockstep with the recipes.
+ */
+/**
+ * FROZEN profile catalog — mirrored from `e2b-template/dev-sandbox/gen-dockerfile.sh` `profile_bands()`.
+ * (db / browser-nodriver are opt-in overlays, NOT in `code-full` — `code-full-db` adds db; per design §4.)
+ */
 export const FROZEN_PROFILES = [
     "code-python",
     "code-node",
@@ -19,6 +40,7 @@ export const FROZEN_PROFILES = [
     "code-full",
     "code-full-db",
 ];
+/** FROZEN band set — mirrored from the `e2b-template/dev-sandbox/bands/` directory (one dir per band). */
 export const FROZEN_BANDS = [
     "python",
     "node",
@@ -40,6 +62,11 @@ export const FROZEN_BANDS = [
     "browser-nodriver",
     "db",
 ];
+/**
+ * FROZEN bump-tool set — the toolchain identifiers a `--bump <tool>=<ver>` may target. Conservative union of the
+ * version-overridable toolchains the bands accept (`<TOOL>_VERSION` env, build.sh forwards `--bump tool=ver`).
+ * Set-membership is the gate; the value is range-checked by VER_RE. Off-list tool → 400 (never coerced).
+ */
 export const FROZEN_BUMP_TOOLS = [
     "node",
     "python",
@@ -58,15 +85,30 @@ export const FROZEN_BUMP_TOOLS = [
 const PROFILE_SET = new Set(FROZEN_PROFILES);
 const BAND_SET = new Set(FROZEN_BANDS);
 const BUMP_TOOL_SET = new Set(FROZEN_BUMP_TOOLS);
+/** Bump value range (P2.4d): printable version-ish tokens only, ≤40 chars — folds into the lockhash. */
 export const VER_RE = /^[A-Za-z0-9._-]{1,40}$/;
+/** Belt-only band shape (set-membership is the real gate); a defense-in-depth reject of structurally weird ids. */
 export const BAND_SHAPE_RE = /^[a-z0-9-]+$/;
+/** A digest must be an immutable sha256 ref (the allow-list check against the index is the real gate, P2.4c). */
 export const DIGEST_RE = /^sha256:[a-f0-9]{64}$/;
 function reject(status, error, conflictBands) {
     return conflictBands ? { ok: false, status, error, conflictBands } : { ok: false, status, error };
 }
+/**
+ * Validate + normalize a `POST /v1/images/bakes` body into a vetted argv, or a typed rejection.
+ *
+ * Order is deliberate: profile XOR bands → bands set-membership (dupes/empties/shape) → bump set+range →
+ * baseRef shape (the index allow-list check is done by the caller via `baseRefAllowed`, async) → build the
+ * raw vetted argv. The output repo is server-fixed (`sema-images/<profile>`); the caller CANNOT set
+ * `--tag` (build.sh auto-computes the immutable tag — kills namespace-squat) nor an arbitrary `FROM`.
+ *
+ * `baseRefAllowed` is checked HERE for shape only; the digest-in-index allow-list is the caller's async step
+ * (it owns the TiDB index). A present-but-malformed `baseRef` is rejected before any DB hit.
+ */
 export function validateBake(body) {
     const hasProfile = body.profile !== undefined && body.profile !== null && body.profile !== "";
     const hasBands = body.bands !== undefined && body.bands !== null;
+    // profile XOR bands — exactly one required.
     if (hasProfile && hasBands)
         return reject(400, "provide profile OR bands, not both");
     if (!hasProfile && !hasBands)
@@ -85,6 +127,7 @@ export function validateBake(body) {
             return reject(400, "bands must be an array of band ids");
         if (body.bands.length === 0)
             return reject(400, "bands must be a non-empty array");
+        // Cap length at the all-bands count — a longer list can only be dupes/garbage.
         if (body.bands.length > FROZEN_BANDS.length)
             return reject(400, `at most ${FROZEN_BANDS.length} bands`);
         const seen = new Set();
@@ -97,18 +140,21 @@ export function validateBake(body) {
             if (seen.has(raw))
                 return reject(400, `duplicate band '${raw}'`);
             seen.add(raw);
+            // "custom"/tenant bands are a P4 affordance → 501 (not a 400) so the UI distinguishes "not yet" from "bad".
             if (!BAND_SET.has(raw))
                 offList.push(raw);
         }
         if (offList.length > 0) {
+            // An off-list band that is the reserved tenant marker routes to P4; any other off-list id is an unknown band.
             if (offList.includes("custom")) {
                 return reject(501, "custom/tenant bake is P4");
             }
             return reject(400, `unknown band(s): ${offList.join(", ")}`, offList);
         }
         bands = body.bands;
-        profile = "custom";
+        profile = "custom"; // build.sh records profile="custom" for --bands; the argv carries --bands, not --profile.
     }
+    // bump — {tool:ver}: tool ∈ FROZEN_BUMP_TOOLS, ver ∈ VER_RE. Off-list/range → 400.
     let bump = null;
     if (body.bump !== undefined && body.bump !== null) {
         if (typeof body.bump !== "object" || Array.isArray(body.bump)) {
@@ -125,6 +171,8 @@ export function validateBake(body) {
         }
         bump = Object.keys(out).length > 0 ? out : null;
     }
+    // baseRef — caller CANNOT pass an arbitrary FROM. Shape-check here (the index allow-list is the caller's async
+    // step). Default = the pinned current base, injected by the caller when baseRef is absent.
     let baseRef = null;
     if (body.baseRef !== undefined && body.baseRef !== null && body.baseRef !== "") {
         if (typeof body.baseRef !== "string" || !DIGEST_RE.test(body.baseRef)) {
@@ -135,6 +183,7 @@ export function validateBake(body) {
     const push = body.push === true;
     const dryRun = body.dryRun === true;
     const logs = body.logs === true;
+    // pkgSource — RFC B4 closed set (cn|global); off-list → 400, never coerced (same discipline as every field).
     let pkgSource = null;
     if (body.pkgSource !== undefined && body.pkgSource !== null && body.pkgSource !== "") {
         if (body.pkgSource !== "cn" && body.pkgSource !== "global") {
@@ -152,9 +201,25 @@ export function validateBake(body) {
         dryRun,
         logs,
         pkgSource,
+        // argv is built by the caller AFTER it resolves the effective baseRef (the index allow-list + default base).
         argv: [],
     };
 }
+/**
+ * Build the VETTED, NORMALIZED build.sh argv from an accepted validation + the caller-resolved effective fields
+ * (the index-checked baseRef and the build-host CACHE_BASE — both runner-environment facts image-api injects,
+ * never operator free-text). The elements are RAW (no shell-quoting): the runner array-spawns build.sh so each
+ * element lands in its own argv slot (no shell can re-interpret a frozen-set value). The runner runs
+ * `build.sh <argv...>` and ONLY this.
+ *
+ * Server-fixed invariants enforced here (NOT caller-settable, P2.4d):
+ *   - `--json` always (machine output the runner parses).
+ *   - selection is `--profile <p>` XOR `--bands a,b,c` (already vetted).
+ *   - NO `--tag` (build.sh auto-computes the immutable tag — kills namespace-squat / overwrite-by-naming).
+ *   - the output repo is server-fixed `sema-images/<profile>` (build.sh's IMAGE_PREFIX default; not forwarded).
+ *   - `--base-ref` is the index-checked effective base (caller resolves the default when absent).
+ *   - `--cache-base` is the build-host promoted cache (runner env).
+ */
 export function buildBakeArgv(v, effective) {
     const args = [];
     if (v.bands && v.bands.length > 0) {
@@ -178,6 +243,11 @@ export function buildBakeArgv(v, effective) {
     if (v.dryRun)
         args.push("--dry-run");
     args.push("--json");
+    // Return the RAW vetted vector. Set-membership against FROZEN_PROFILES/BANDS/BUMP_TOOLS is the RCE gate; the
+    // runner array-spawns build.sh with each element in its own argv slot (no shell), so a frozen-set value can
+    // never be re-interpreted by a shell. Shell-quoting here would embed literal single-quotes into each slot →
+    // build.sh sees `'--profile'` (quotes included) and dies "unknown arg" on the first one (H2). Quoting is wrong
+    // for an array-spawn boundary; the injection boundary is the array slot, not a joined command string.
     return args;
 }
 //# sourceMappingURL=bake-validate.js.map

package/dist/images/manifest.d.ts

@@ -1,8 +1,19 @@
+/**
+ * build.sh manifest → image-index projection (IMAGE-API-DESIGN.md §1/§3, pool design §6).
+ *
+ * `sandbox-manifest.json` is the replay-sufficient build record; the index row is its queryable projection +
+ * the push-time facts (registry repo + runtime digest). This module is the SINGLE pure mapping used by both the
+ * one-time seed and the P3 atomic-publish pipeline — kept side-effect-free so it is unit-tested without a DB.
+ */
 import type { ImageIndexUpsert, ImageNestedBuildMode, ImageStatus } from "../plugins/store-contracts.js";
+/** Project the manifest's `nestedBuild` (string posture OR bool) → the enum (center contract). */
 export declare function nestedBuildModeOf(v: string | boolean | undefined): ImageNestedBuildMode;
+/** The fields of build.sh's `sandbox-manifest.json` this projection reads (a superset is fine; extras ignored). */
 export interface BuildManifest {
+    /** "custom" for `--bands` builds; the real profile is then the tag's repo part. */
     profile?: string;
     bands?: string[];
+    /** e.g. "code-flutter:dev-20260619". */
     tag?: string;
     digest?: string;
     generatorVersion?: string;
@@ -22,15 +33,23 @@ export interface BuildManifest {
     visibility?: string;
     sizeBytes?: number;
 }
+/** The push-time facts the manifest cannot know (the registry repo + the runtime-pinned digest + lifecycle). */
 export interface ManifestProjectOpts {
+    /** Registry repo the digest lives in, e.g. "docker.io/claybobby/code-flutter" (historically SWR — deprecated). */
     repo: string;
+    /** Runtime-pinned digest (the registry RepoDigest after push); falls back to the manifest digest pre-push. */
     digest?: string;
+    /** Lifecycle status to register with (default "published" — the seed runs post-verify). */
     status?: ImageStatus;
+    /** sha256 of the manifest blob (the replay anchor). */
     manifestSha?: string | null;
     sizeBytes?: number | null;
     signed?: boolean;
 }
+/** Parse a docker-style size ("64m" / "512M" / "1g") → MB. Undefined on an unparseable / absent value. */
 export declare function shmToMB(v: string | undefined): number | undefined;
+/** --bands builds record profile="custom", so the tag's repo part ("code-flutter:tag" → "code-flutter") wins. */
 export declare function profileFromManifest(m: BuildManifest): string;
+/** Pure projection: a build.sh manifest + the push-time facts → an index upsert. */
 export declare function manifestToIndexEntry(m: BuildManifest, opts: ManifestProjectOpts): ImageIndexUpsert;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/images/manifest.js

@@ -4,16 +4,18 @@ const NESTED_BUILD_MODES = [
     "rootless-buildkit",
     "privileged-dind",
 ];
+/** Project the manifest's `nestedBuild` (string posture OR bool) → the enum (center contract). */
 export function nestedBuildModeOf(v) {
     if (typeof v === "string") {
         return NESTED_BUILD_MODES.includes(v)
             ? v
             : v
-                ? "rootless-buildkit"
+                ? "rootless-buildkit" // an unknown non-empty posture is treated as the safe default the pool uses
                 : "none";
     }
     return v ? "rootless-buildkit" : "none";
 }
+/** Parse a docker-style size ("64m" / "512M" / "1g") → MB. Undefined on an unparseable / absent value. */
 export function shmToMB(v) {
     if (!v)
         return undefined;
@@ -23,12 +25,14 @@ export function shmToMB(v) {
     const n = Number(m[1]);
     return (m[2] ?? "m").toLowerCase() === "g" ? n * 1024 : n;
 }
+/** --bands builds record profile="custom", so the tag's repo part ("code-flutter:tag" → "code-flutter") wins. */
 export function profileFromManifest(m) {
     if (m.profile && m.profile !== "custom")
         return m.profile;
     const repo = (m.tag ?? "").split(":")[0] ?? "";
     return repo || m.profile || "custom";
 }
+/** Pure projection: a build.sh manifest + the push-time facts → an index upsert. */
 export function manifestToIndexEntry(m, opts) {
     const profile = profileFromManifest(m);
     const tag = (m.tag ?? "").includes(":") ? (m.tag ?? "").split(":")[1] : (m.tag ?? "");
@@ -57,6 +61,7 @@ export function manifestToIndexEntry(m, opts) {
         sizeBytes: opts.sizeBytes ?? m.sizeBytes ?? null,
         status: opts.status ?? "published",
         visibility,
+        // a tenant image carries its owner; the standard pool's "standard-pool" owner is NOT a tenant.
         tenantId: visibility === "tenant" && m.owner && m.owner !== "standard-pool" ? m.owner : null,
         manifestSha: opts.manifestSha ?? null,
         recipeGitSha: m.recipeGitSha && m.recipeGitSha !== "nogit" ? m.recipeGitSha : null,

package/dist/index.d.ts

@@ -2,14 +2,10 @@ export { loadConfig, type ServiceConfig } from "./config.js";
 export { createBrain } from "./brain.js";
 export { createSessionStore } from "./plugins/session-store.js";
 export { createStoreBackend, type StoreBackend } from "./plugins/store-backend.js";
-export { createTidbPool, ensureSchema, SCHEMA_STATEMENTS } from "./plugins/tidb-pool.js";
-export { TiDBSessionStore } from "./plugins/tidb-session-store.js";
-export { TiDBSessionStorage } from "./plugins/tidb-session-storage.js";
 export { CachingSessionStore, type CachingOptions } from "./plugins/caching-session-store.js";
-export { TiDBRunStore } from "./plugins/tidb-run-store.js";
 export type { RunRecord, RunEvent } from "./plugins/store-contracts.js";
 export { runInBackground } from "./runs.js";
-export { TiDBApprovalStore, type ApprovalRow, type ApprovalStatus, } from "./plugins/tidb-approval-store.js";
+export { type ApprovalRow, type ApprovalStatus } from "./plugins/approval-store-sql.js";
 export { createOaApprovalPolicy, type OaApprovalOptions } from "./approval.js";
 export { createHardenedVmRunner, runInHardenedVm, type HardenedVmLimits, type HardenedMembrane } from "./orchestration/hardened-vm-runner.js";
 export { createWorkerHardenedVmRunner } from "./orchestration/hardened-vm-worker-runner.js";

package/dist/index.js

@@ -1,14 +1,19 @@
+// Library surface (for embedding the service wiring in another Node app — e.g. the shell's seamless local mode
+// runs the sema-server HTTP wire in-process via createHttpServer + a local StoreBackend).
 export { loadConfig } from "./config.js";
 export { createBrain } from "./brain.js";
 export { createSessionStore } from "./plugins/session-store.js";
+// design/158 B5-①([1971] 声明后落):中立后端缝 —— 嵌入姿势(见顶注)= createHttpServer + StoreBackend。
 export { createStoreBackend } from "./plugins/store-backend.js";
-export { createTidbPool, ensureSchema, SCHEMA_STATEMENTS } from "./plugins/tidb-pool.js";
-export { TiDBSessionStore } from "./plugins/tidb-session-store.js";
-export { TiDBSessionStorage } from "./plugins/tidb-session-storage.js";
+// ── B5-②(clay 两拍终裁 2026-07-30:cli/core 零消费,弃用窗撤销直接删)——6 个 TiDB 方言专属导出已摘 ──
+// 判据:①backend-可插铁律(公面即承诺,方言类在公面=邀请绕过中立缝直连方言);②公面瘸腿(PG 孪生
+// 从未导出);③全生态扫描零消费。替代:构造走 createStoreBackend(kind mysql|pg|local),DDL 审阅走
+// docs/schema/baseline-{mysql,pg}.sql(生成基线,机器门逐字节)。类/函数本体仍是内部实现(深径 import)。
 export { CachingSessionStore } from "./plugins/caching-session-store.js";
-export { TiDBRunStore } from "./plugins/tidb-run-store.js";
 export { runInBackground } from "./runs.js";
-export { TiDBApprovalStore, } from "./plugins/tidb-approval-store.js";
+// B5-② 补漏:TiDBApprovalStore 是证据包漏数的第 7 个方言导出,同判据同车摘(全生态零消费);
+// 两个中立行类型改从 A12 后的真源(approval-store-sql.ts)导出。
+export {} from "./plugins/approval-store-sql.js";
 export { createOaApprovalPolicy } from "./approval.js";
 export { createHardenedVmRunner, runInHardenedVm } from "./orchestration/hardened-vm-runner.js";
 export { createWorkerHardenedVmRunner } from "./orchestration/hardened-vm-worker-runner.js";

package/dist/key-resolver.d.ts

@@ -1,5 +1,28 @@
 import type { Model } from "@sema-agent/core";
 import { type SealedKeyPoison } from "./sealed-key.js";
+/**
+ * Build a per-model API-key resolver for `TaskSpec.getApiKeyAndHeaders` from the catalog's
+ * name → env-var-NAME map (sema-registry `apiKeyEnv`). core threads this per brain call — and per cascade
+ * rung — so each model/rung authenticates with its OWN upstream account/key.
+ *
+ * Additive by construction: a model absent from the map — or whose env var is unset — returns
+ * `undefined`, so core falls back to the brain's construction-time gateway key (today's behavior, no
+ * regression). When no per-model keys are configured at all this returns `undefined`, leaving the spec
+ * field unset so core's default path is byte-for-byte unchanged.
+ *
+ * Only the api KEY is per-model; the base URL stays brain-owned (design/15) — core's seam carries
+ * `{ apiKey, headers? }`, not a baseUrl. Same-account-rotation could round-robin inside this function.
+ *
+ * `modelApiKeys` (sealed-box custody) carries per-model entries unsealed from `ModelEntry.sealedApiKey` —
+ * resolved FIRST (sealed outranks the env-NAME reference, the registry-core mutual-exclusion ruling). Each
+ * entry is either the PLAINTEXT key (successful unseal) or a `SealedKeyPoison` marker (unseal FAILED at
+ * apply time): a poisoned model THROWS `SealedKeyPoisonedError` on every resolve — task-level fail-loud —
+ * because returning `undefined` here means "use the gateway key", and a broken sealed key must NEVER
+ * silently burn the shared gateway account (the core invariant of the poison-pill fix; a poisoned model
+ * skips its env reference too, same mutual-exclusion as a healthy sealed key). The maps are disjoint by
+ * construction in applyEffective (a sealed model never lands in modelApiKeyEnv); the ordering here is
+ * belt-and-suspenders. 🔴 Plaintext values are live secrets: memory-only, never log them.
+ */
 export declare function createKeyResolver(modelApiKeyEnv: Record<string, string>, env?: NodeJS.ProcessEnv, modelApiKeys?: Record<string, string | SealedKeyPoison>): ((model: Model) => Promise<{
     apiKey: string;
 } | undefined>) | undefined;

package/dist/key-resolver.js

@@ -1,16 +1,41 @@
 import { isSealedKeyPoison, SealedKeyPoisonedError } from "./sealed-key.js";
+/**
+ * Build a per-model API-key resolver for `TaskSpec.getApiKeyAndHeaders` from the catalog's
+ * name → env-var-NAME map (sema-registry `apiKeyEnv`). core threads this per brain call — and per cascade
+ * rung — so each model/rung authenticates with its OWN upstream account/key.
+ *
+ * Additive by construction: a model absent from the map — or whose env var is unset — returns
+ * `undefined`, so core falls back to the brain's construction-time gateway key (today's behavior, no
+ * regression). When no per-model keys are configured at all this returns `undefined`, leaving the spec
+ * field unset so core's default path is byte-for-byte unchanged.
+ *
+ * Only the api KEY is per-model; the base URL stays brain-owned (design/15) — core's seam carries
+ * `{ apiKey, headers? }`, not a baseUrl. Same-account-rotation could round-robin inside this function.
+ *
+ * `modelApiKeys` (sealed-box custody) carries per-model entries unsealed from `ModelEntry.sealedApiKey` —
+ * resolved FIRST (sealed outranks the env-NAME reference, the registry-core mutual-exclusion ruling). Each
+ * entry is either the PLAINTEXT key (successful unseal) or a `SealedKeyPoison` marker (unseal FAILED at
+ * apply time): a poisoned model THROWS `SealedKeyPoisonedError` on every resolve — task-level fail-loud —
+ * because returning `undefined` here means "use the gateway key", and a broken sealed key must NEVER
+ * silently burn the shared gateway account (the core invariant of the poison-pill fix; a poisoned model
+ * skips its env reference too, same mutual-exclusion as a healthy sealed key). The maps are disjoint by
+ * construction in applyEffective (a sealed model never lands in modelApiKeyEnv); the ordering here is
+ * belt-and-suspenders. 🔴 Plaintext values are live secrets: memory-only, never log them.
+ */
 export function createKeyResolver(modelApiKeyEnv, env = process.env, modelApiKeys = {}) {
     if (Object.keys(modelApiKeyEnv).length === 0 && Object.keys(modelApiKeys).length === 0)
         return undefined;
     return async (model) => {
         const sealed = modelApiKeys[model.name];
+        // Poison pill: the operator configured a sealed key for this model but it cannot be unsealed —
+        // fail the brain call LOUD (never undefined = never the gateway fallback).
         if (isSealedKeyPoison(sealed))
             throw new SealedKeyPoisonedError(model.name, sealed);
         if (sealed)
-            return { apiKey: sealed };
+            return { apiKey: sealed }; // sealed-box custody wins (registry-core: sealed 压过 apiKeyEnv)
         const envName = modelApiKeyEnv[model.name];
         if (!envName)
-            return undefined;
+            return undefined; // model has no per-model key → core uses the gateway key
         const apiKey = env[envName];
         return apiKey ? { apiKey } : undefined;
     };

package/dist/leader/diffout.d.ts

@@ -1,12 +1,31 @@
+/**
+ * v2 MVP M2 — diff-OUT-of-container (design/50 §7 solution (b), V2-MVP-PLAN.md, findings F1/F3, council#1/#13/#14).
+ *
+ * The Coordinator pulls a worker's commits as a patch series over `execStream` `git format-patch --stdout` —
+ * the diff comes OUT of the worker container, **no push credentials ever go IN** (preserves §5/F3 isolation).
+ * The patch then feeds the ephemeral no-creds integration sandbox (M3) via `git am`/`git apply`.
+ *
+ * Council round-1 folded:
+ * - #14: `--stdout` (else format-patch writes .patch FILES and prints only filenames to stdout).
+ * - #13 + maxOutputBytes: fail-on-truncation — a runaway diff must NOT be silently half-captured.
+ * - exit-code: non-zero `git` → failure (the worker branch / base is bad), surfaced not swallowed.
+ * - ref validation: baseSha/ref are interpolated into a shell command in the container; reject anything that
+ *   isn't a safe git rev token so a worker-influenced value can't inject.
+ */
 import type { OutputChunk, ExecStreamOptions } from "@sema-agent/core";
+/** Only the one method M2 consumes from the remote env (the real RemoteExecutionEnv satisfies it). */
 export interface ExecStreamLike {
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
 }
 export interface PullDiffOptions {
+    /** Worker branch / rev to diff up to (default HEAD — the worker container's checked-out work). */
     ref?: string;
+    /** Repo dir inside the container (execStream cwd). */
     cwd?: string;
+    /** Fail-on-truncation cap (bytes). Default 5 MiB. */
     maxBytes?: number;
     signal?: AbortSignal;
+    /** Idle read timeout (E2B #1128 — never hang on an unreachable sandbox). Default 30s. */
     readTimeoutMs?: number;
 }
 export type PullDiffResult = {
@@ -20,5 +39,9 @@ export type PullDiffResult = {
     exitCode?: number;
 };
 export declare function safeRev(rev: string): boolean;
+/**
+ * Pull `<baseSha>..<ref>` from a worker container as a `git format-patch` series. Never throws — failures
+ * (bad rev, non-zero git, truncation, transport loss, empty diff) are returned as `{ ok: false }`.
+ */
 export declare function pullDiff(env: ExecStreamLike, baseSha: string, opts?: PullDiffOptions): Promise<PullDiffResult>;
 //# sourceMappingURL=diffout.d.ts.map

package/dist/leader/diffout.js

@@ -1,15 +1,21 @@
 const DEFAULT_MAX_DIFF_BYTES = 5 * 1024 * 1024;
 const DEFAULT_READ_TIMEOUT_MS = 30_000;
+/** A safe git rev token: sha, branch/tag name, or `A..B`. No shell metacharacters, no leading dash. */
 const SAFE_REV = /^[A-Za-z0-9._/-]{1,200}$/;
 export function safeRev(rev) {
     return SAFE_REV.test(rev) && !rev.startsWith("-") && !rev.includes("..--");
 }
+/**
+ * Pull `<baseSha>..<ref>` from a worker container as a `git format-patch` series. Never throws — failures
+ * (bad rev, non-zero git, truncation, transport loss, empty diff) are returned as `{ ok: false }`.
+ */
 export async function pullDiff(env, baseSha, opts = {}) {
     const ref = opts.ref ?? "HEAD";
     if (!safeRev(baseSha) || !safeRev(ref)) {
         return { ok: false, error: `unsafe git rev (baseSha=${JSON.stringify(baseSha)} ref=${JSON.stringify(ref)})` };
     }
     const maxBytes = opts.maxBytes ?? DEFAULT_MAX_DIFF_BYTES;
+    // --stdout (council#14): emit the whole series to stdout, not .patch files. Newest-last (default order).
     const cmd = `git format-patch --stdout ${baseSha}..${ref}`;
     let patch = "";
     let bytes = 0;
@@ -18,7 +24,7 @@ export async function pullDiff(env, baseSha, opts = {}) {
     try {
         for await (const chunk of env.execStream(cmd, {
             ...(opts.cwd ? { cwd: opts.cwd } : {}),
-            maxOutputBytes: maxBytes + 1,
+            maxOutputBytes: maxBytes + 1, // +1 so we can DETECT the overflow (council#13 fail-on-truncation)
             readTimeoutMs: opts.readTimeoutMs ?? DEFAULT_READ_TIMEOUT_MS,
             ...(opts.signal ? { signal: opts.signal } : {}),
         })) {
@@ -38,6 +44,7 @@ export async function pullDiff(env, baseSha, opts = {}) {
         }
     }
     catch (e) {
+        // execStream throws on transport loss / suspendVM-aborted in-flight command (no exit chunk).
         return { ok: false, error: `execStream failed before exit: ${e instanceof Error ? e.message : String(e)}` };
     }
     if (exitCode === undefined) {

package/dist/leader/diffup.d.ts

@@ -1,14 +1,46 @@
+/**
+ * design/68 §8 F2(a) — worker SELF-UPLOAD diff-out (the factory-env counterpart of diffout.ts's pullDiff).
+ *
+ * With a factory env the runner owns the container lifecycle (create at task start, destroy at finish — and
+ * durable suspend only produces a complete ownedEnv on this path), so the leader can no longer pull the diff
+ * from a still-alive env after the task. Instead (the gate#2-proven MinIO presigned pattern):
+ *   1. the env factory STAGES each fresh container (seed repo + write an upload script holding a presigned
+ *      PUT URL) — adapter-side, so the URL/bulk never enters the model's CONTEXT by construction (it does sit
+ *      on the sandbox filesystem, readable if the agent goes looking — the objective forbids inspecting it;
+ *      the URL is single-object, PUT-only, short-TTL, so that residual face is small);
+ *   2. the worker's objective ends with a MANDATORY final step: run the upload script (`git format-patch` →
+ *      `curl -T <file>` — a real file, so Content-Length is set; MinIO 411-rejects chunked presigned PUTs);
+ *   3. after fan-out the leader fetches the object over a presigned GET on the CONTROL PLANE (fetchUploadedDiff).
+ * A worker that skips the upload surfaces as `{ok:false}` → merge quarantines it (honest failure, no hang).
+ * pullDiff stays as the compat path for static (leader-owned) envs — M2 降兼容.
+ */
 import { type PullDiffResult } from "./diffout.js";
+/** The staged upload script. `repoDir`/`workDir` are deployment config; `baseSha` is interpolated into a
+ *  shell line, so it is re-validated HERE (fail-closed) — callers should already have applied diffout's
+ *  safeRev rules, but this function is the last line before the shell. The patch is written OUTSIDE the repo
+ *  dir so it never shows up as untracked noise in the worker's `git status`. */
 export declare function buildUploadScript(p: {
     repoDir: string;
     baseSha: string;
     putUrl: string;
     workDir: string;
 }): string;
+/** The objective suffix that makes the upload the worker's last task step (no URL through the model). */
 export declare function uploadStepSuffix(workDir: string): string;
+/**
+ * Fetch the worker-uploaded patch over a presigned GET (control plane; creds stay adapter-held). Returns the
+ * same result shape as pullDiff so merge consumes either path. 🔴 The presigned URL is a short-lived bearer
+ * credential — it must never appear in returned errors (gate#3 council#5 redaction rule).
+ */
 export declare function fetchUploadedDiff(getUrl: string, opts?: {
     maxBytes?: number;
     fetchImpl?: typeof fetch;
 }): Promise<PullDiffResult>;
+/**
+ * Wrap an ExecutionEnv so a one-shot `stage(env)` (seed repo + write the upload script) runs before the FIRST
+ * workspace-touching call — the adapters are lazy-connect, so there is no explicit connect() hook to ride; this
+ * guarantees seed-before-agent on whichever call comes first. A failed staging rejects that call (task fails
+ * honestly) and RESETS, so a retried call re-attempts staging instead of replaying a cached rejection.
+ */
 export declare function withStaging<T extends object>(env: T, stage: (env: T) => Promise<void>, finalize?: (env: T) => Promise<void>): T;
 //# sourceMappingURL=diffup.d.ts.map

package/dist/leader/diffup.js

@@ -1,8 +1,30 @@
+/**
+ * design/68 §8 F2(a) — worker SELF-UPLOAD diff-out (the factory-env counterpart of diffout.ts's pullDiff).
+ *
+ * With a factory env the runner owns the container lifecycle (create at task start, destroy at finish — and
+ * durable suspend only produces a complete ownedEnv on this path), so the leader can no longer pull the diff
+ * from a still-alive env after the task. Instead (the gate#2-proven MinIO presigned pattern):
+ *   1. the env factory STAGES each fresh container (seed repo + write an upload script holding a presigned
+ *      PUT URL) — adapter-side, so the URL/bulk never enters the model's CONTEXT by construction (it does sit
+ *      on the sandbox filesystem, readable if the agent goes looking — the objective forbids inspecting it;
+ *      the URL is single-object, PUT-only, short-TTL, so that residual face is small);
+ *   2. the worker's objective ends with a MANDATORY final step: run the upload script (`git format-patch` →
+ *      `curl -T <file>` — a real file, so Content-Length is set; MinIO 411-rejects chunked presigned PUTs);
+ *   3. after fan-out the leader fetches the object over a presigned GET on the CONTROL PLANE (fetchUploadedDiff).
+ * A worker that skips the upload surfaces as `{ok:false}` → merge quarantines it (honest failure, no hang).
+ * pullDiff stays as the compat path for static (leader-owned) envs — M2 降兼容.
+ */
 import { safeRev } from "./diffout.js";
 const DEFAULT_MAX_DIFF_BYTES = 5 * 1024 * 1024;
+/** The staged upload script. `repoDir`/`workDir` are deployment config; `baseSha` is interpolated into a
+ *  shell line, so it is re-validated HERE (fail-closed) — callers should already have applied diffout's
+ *  safeRev rules, but this function is the last line before the shell. The patch is written OUTSIDE the repo
+ *  dir so it never shows up as untracked noise in the worker's `git status`. */
 export function buildUploadScript(p) {
     if (!safeRev(p.baseSha))
         throw new Error(`buildUploadScript: unsafe baseSha ${JSON.stringify(p.baseSha)}`);
+    // presignS3Url percent-encodes all specials today, so a "'" can't occur — escape anyway (belt-and-suspenders;
+    // the URL sits inside single quotes in the script below).
     const putUrl = p.putUrl.replaceAll("'", "'\\''");
     return [
         "#!/bin/sh",
@@ -10,14 +32,21 @@ export function buildUploadScript(p) {
         "set -e",
         `cd ${p.repoDir}`,
         `git format-patch --stdout ${p.baseSha}..HEAD > ${p.workDir}/.leader-out.patch`,
+        // -T <file> (not stdin): sets Content-Length — MinIO returns 411 on chunked presigned PUTs (gate#3 council#3).
         `curl -fsS -X PUT -T ${p.workDir}/.leader-out.patch '${putUrl}'`,
         `echo leader-diff-uploaded`,
         "",
     ].join("\n");
 }
+/** The objective suffix that makes the upload the worker's last task step (no URL through the model). */
 export function uploadStepSuffix(workDir) {
     return `\n\nMANDATORY FINAL STEP: after your final commit, run exactly: sh ${workDir}/.leader-upload.sh — it exports your branch diff for integration. Do not modify, inspect, or skip it; if it fails, fix your git state (commit your work) and run it again.`;
 }
+/**
+ * Fetch the worker-uploaded patch over a presigned GET (control plane; creds stay adapter-held). Returns the
+ * same result shape as pullDiff so merge consumes either path. 🔴 The presigned URL is a short-lived bearer
+ * credential — it must never appear in returned errors (gate#3 council#5 redaction rule).
+ */
 export async function fetchUploadedDiff(getUrl, opts = {}) {
     const maxBytes = opts.maxBytes ?? DEFAULT_MAX_DIFF_BYTES;
     const f = opts.fetchImpl ?? fetch;
@@ -29,6 +58,7 @@ export async function fetchUploadedDiff(getUrl, opts = {}) {
         return { ok: false, error: `diff fetch failed: ${e instanceof Error ? e.message.replaceAll(getUrl, "<presigned-url>") : "network error"}` };
     }
     if (res.status === 404 || res.status === 403) {
+        // MinIO answers 403 (signature scope) for a missing key on some configs — both mean "no upload landed".
         return { ok: false, error: `no uploaded diff (worker skipped the mandatory upload step, or upload failed) [${res.status}]` };
     }
     if (!res.ok)
@@ -40,7 +70,14 @@ export async function fetchUploadedDiff(getUrl, opts = {}) {
         return { ok: false, error: "uploaded diff is empty (worker committed nothing past base)" };
     return { ok: true, patch, bytes: patch.length };
 }
+/** The minimal surface staging must run before (the agent reaches the workspace through these). */
 const STAGED_METHODS = new Set(["exec", "execStream", "writeFile", "readFile"]);
+/**
+ * Wrap an ExecutionEnv so a one-shot `stage(env)` (seed repo + write the upload script) runs before the FIRST
+ * workspace-touching call — the adapters are lazy-connect, so there is no explicit connect() hook to ride; this
+ * guarantees seed-before-agent on whichever call comes first. A failed staging rejects that call (task fails
+ * honestly) and RESETS, so a retried call re-attempts staging instead of replaying a cached rejection.
+ */
 export function withStaging(env, stage, finalize) {
     let staged;
     const ensure = () => {
@@ -57,6 +94,11 @@ export function withStaging(env, stage, finalize) {
                 return v;
             const fn = v.bind(t);
             if (prop === "destroy" && finalize) {
+                // Belt for the MANDATORY upload step (found live: task02b run4 collapse-solo): a worker that did the
+                // porting but FORGOT `sh .leader-upload.sh` loses its work when the runner destroys the env — diff-out
+                // 404s and merge quarantines a worker that actually finished. Run `finalize` best-effort before the
+                // teardown, only if the env was ever staged (never spawn a pod just to upload nothing). Idempotent:
+                // re-running the upload script after a model-run upload overwrites the same object with the same diff.
                 return async (...args) => {
                     if (staged)
                         await Promise.resolve(staged).then(() => finalize(env)).catch(() => { });
@@ -66,6 +108,7 @@ export function withStaging(env, stage, finalize) {
             if (!STAGED_METHODS.has(prop))
                 return fn;
             if (prop === "execStream") {
+                // async-iterable return — staging must complete before the underlying stream starts.
                 return (...args) => (async function* () {
                     await ensure();
                     yield* fn(...args);

package/dist/leader/endpoint.d.ts

@@ -1,24 +1,38 @@
 import type { LeaderResult } from "./leader.js";
 export interface LeaderRequestBody {
+    /** The task to decompose + execute (the Planner turns it into N disjoint sub-tasks). */
     objective: string;
+    /** Durable-remote base the Coordinator pushes onto (`--force-with-lease=<ref>:<baseSha>`). */
     baseSha?: string;
     [k: string]: unknown;
 }
 export interface LeaderRun {
     id: string;
+    /** LEADER-REPAIRLOOP-INTEGRATION §5/§10.6 — `needs_human` is the THIRD terminal state: the repair loop / merge
+     *  push chokepoint ABSTAINED (a `candidate_only`/`needs_human_oracle`/`conflict` repair terminal), held the push,
+     *  and surfaced a candidate awaiting a human `/decide` accept — distinct from "broke" (`failed`). Default runs
+     *  never reach it (no `repairTerminal` ⇒ `completed`/`failed` exactly as before). */
     status: "running" | "completed" | "failed" | "needs_human";
     result?: LeaderResult;
     error?: string;
     startedAt: number;
     finishedAt?: number;
+    /** BL-4: the principal that submitted this run (null = anonymous/single-tenant). The GET is owner-checked so
+     *  an owned run is visible ONLY to its owner (404 to others — no existence oracle), like GET /v1/runs/:id. */
     owner?: string | null;
 }
 export interface LeaderEndpoint {
+    /** Returns a {status,body} to send, or null if the (method,url) is not a leader route. Kicks the background
+     *  run for POST. `body` is the already-parsed request body (server reads it; undefined for GET). `requester`
+     *  (BL-4) is the authenticated principal: recorded as the run owner on POST and owner-checked on GET. */
     handle(method: string, url: string, body: unknown, requester?: string | null): {
         status: number;
         body: object;
     } | null;
+    /** 对抗复查 B-1(CRITICAL):the number of leader runs still RUNNING in the background — the drain gate
+     *  counts them (a SIGTERM used to see 0 and hard-shut mid-leader-run). */
     inflight(): number;
+    /** In-memory run registry (exposed for tests / a future reaper). */
     runs: Map<string, LeaderRun>;
 }
 export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody) => Promise<LeaderResult>, opts?: {
@@ -26,6 +40,12 @@ export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody
         info?: (m: string, x?: Record<string, unknown>) => void;
         error?: (m: string, x?: Record<string, unknown>) => void;
     };
+    /** SDK 全量核查(2026-07-24,黑板 GD 组)撞获:`wire.ts` 的 runLeader 实际要求 objective 之外还有
+     *  durableRemote/testCmd/seedCmd/baseSha 全部非空,但这个同步门此前只查 objective——一个不完整的
+     *  请求会先拿到 202"运行中",然后在后台**必然**失败(wire.ts:369),消费方只能靠后续 GET 才发现。
+     *  这个字段名列表由调用方(main.ts wire 真实 runLeader 实现)传入,endpoint 本身不需要知道
+     *  runLeader 的内部实现细节,依旧保持 pure/testable。不传 = 向后兼容旧行为(只查 objective) ——
+     *  本文件其余全部既有用例都用最小 {objective} payload,不能被这个修复打红。 */
     requiredFields?: readonly string[];
 }): LeaderEndpoint;
 //# sourceMappingURL=endpoint.d.ts.map