@sema-agent/server 1.323.0 → 2.0.1

package/dist/sandbox-pkg-source.d.ts

@@ -1,3 +1,21 @@
+/**
+ * RFC B5/B4 抽象点② (docs/design/ENV-SELECT-AND-REGION-SOURCE.md): the deployment-region package-source →
+ * sandbox env derivation. ENV-FIRST: pod/sandbox env OVERRIDES the image's baked `ENV` (k8s container env wins
+ * over image config and is visible to every exec'd process; e2b sandboxEnv likewise) — so the env-overridable
+ * ecosystem pieces (pip/uv/npm/corepack/go/rustup/flutter/playwright/nuget) switch region on EXISTING images,
+ * no rebake needed. Only the file-bound pieces (apt sources, /etc/gemrc, composer global config, cargo
+ * config.toml) still need the in-image `pkg-source.sh` hook (rebaked images; bake prep chowns those files).
+ *
+ * Profiles:
+ *   cn      → inject only the SEMA_PKG_SOURCE marker (the pool's images bake the CN set as their defaults).
+ *   global  → official endpoints for every env-overridable ecosystem (overrides the baked CN ENV values).
+ *   custom  → SEMA_* explicit URLs (from the service process env) forwarded verbatim + mapped onto the same
+ *             ecosystem variables where a mapping is unambiguous (apt has no env form — hook-only).
+ *
+ * The marker `SEMA_PKG_SOURCE` always rides along: the image's pkg-source.sh hook (pod-start / profile.d)
+ * materializes the file-bound pieces from it; images without the hook simply ignore it.
+ */
+/** Explicit URLs for `custom` (RFC B: 极端情况出口). Read from the service process env (operator-trusted). */
 export interface CustomPkgSource {
     aptMirror?: string;
     pipIndex?: string;
@@ -6,6 +24,11 @@ export interface CustomPkgSource {
     npmRegistry?: string;
     nodeMirror?: string;
 }
+/**
+ * Derive the operator-trusted sandbox env for a package-source profile. Returns `{}` for an unknown/empty
+ * profile (unset = byte-identical sandbox — the B5 backward-compat contract).
+ */
 export declare function derivePkgSourceEnv(profile: string | undefined, custom?: CustomPkgSource): Record<string, string>;
+/** Read the `custom` explicit-URL set from the service process env (operator-trusted deployment config). */
 export declare function customPkgSourceFromEnv(env?: NodeJS.ProcessEnv): CustomPkgSource;
 //# sourceMappingURL=sandbox-pkg-source.d.ts.map

package/dist/sandbox-pkg-source.js

@@ -1,23 +1,55 @@
+/**
+ * RFC B5/B4 抽象点② (docs/design/ENV-SELECT-AND-REGION-SOURCE.md): the deployment-region package-source →
+ * sandbox env derivation. ENV-FIRST: pod/sandbox env OVERRIDES the image's baked `ENV` (k8s container env wins
+ * over image config and is visible to every exec'd process; e2b sandboxEnv likewise) — so the env-overridable
+ * ecosystem pieces (pip/uv/npm/corepack/go/rustup/flutter/playwright/nuget) switch region on EXISTING images,
+ * no rebake needed. Only the file-bound pieces (apt sources, /etc/gemrc, composer global config, cargo
+ * config.toml) still need the in-image `pkg-source.sh` hook (rebaked images; bake prep chowns those files).
+ *
+ * Profiles:
+ *   cn      → inject only the SEMA_PKG_SOURCE marker (the pool's images bake the CN set as their defaults).
+ *   global  → official endpoints for every env-overridable ecosystem (overrides the baked CN ENV values).
+ *   custom  → SEMA_* explicit URLs (from the service process env) forwarded verbatim + mapped onto the same
+ *             ecosystem variables where a mapping is unambiguous (apt has no env form — hook-only).
+ *
+ * The marker `SEMA_PKG_SOURCE` always rides along: the image's pkg-source.sh hook (pod-start / profile.d)
+ * materializes the file-bound pieces from it; images without the hook simply ignore it.
+ */
+/** The official (`global`) endpoint set — overrides the pool images' baked CN ENV values. */
 const GLOBAL_ENV = {
+    // python: pip + uv (uv does NOT read pip's variables). The python band bakes the deprecated
+    // UV_INDEX_URL alias; override BOTH aliases to the same value so whichever uv reads, it reads official.
     PIP_INDEX_URL: "https://pypi.org/simple",
     UV_DEFAULT_INDEX: "https://pypi.org/simple",
     UV_INDEX_URL: "https://pypi.org/simple",
+    // node: npm env config beats npmrc files; corepack has its own baked ENV (node band).
     NPM_CONFIG_REGISTRY: "https://registry.npmjs.org",
     COREPACK_NPM_REGISTRY: "https://registry.npmjs.org",
+    // go band bakes goproxy.cn + sum.golang.google.cn
     GOPROXY: "https://proxy.golang.org,direct",
     GOSUMDB: "sum.golang.org",
+    // rust band bakes rsproxy.cn (rustup); the crates registry file (cargo config.toml) is hook territory.
     RUSTUP_DIST_SERVER: "https://static.rust-lang.org",
     RUSTUP_UPDATE_ROOT: "https://static.rust-lang.org/rustup",
+    // flutter band bakes flutter-io.cn
     FLUTTER_STORAGE_BASE_URL: "https://storage.googleapis.com",
     PUB_HOSTED_URL: "https://pub.dev",
+    // browser/python bands bake the npmmirror playwright host; empty string falls through playwright's `||` to
+    // its official CDN (playwright treats a falsy env as unset).
     PLAYWRIGHT_DOWNLOAD_HOST: "",
+    // dotnet band's informational feed pointer
     NUGET_FEED: "https://api.nuget.org/v3/index.json",
 };
+/**
+ * Derive the operator-trusted sandbox env for a package-source profile. Returns `{}` for an unknown/empty
+ * profile (unset = byte-identical sandbox — the B5 backward-compat contract).
+ */
 export function derivePkgSourceEnv(profile, custom) {
     if (!profile)
         return {};
     switch (profile) {
         case "cn":
+            // the images bake the CN set as their defaults — only the marker (hook re-materializes apt, idempotent).
             return { SEMA_PKG_SOURCE: "cn" };
         case "global":
             return { SEMA_PKG_SOURCE: "global", ...GLOBAL_ENV };
@@ -26,12 +58,14 @@ export function derivePkgSourceEnv(profile, custom) {
             const uvIndex = c.uvIndex ?? c.pipIndex;
             return {
                 SEMA_PKG_SOURCE: "custom",
+                // SEMA_* verbatim for the in-image hook (file-bound pieces: apt/gem/composer/cargo)
                 ...(c.aptMirror ? { SEMA_APT_MIRROR: c.aptMirror } : {}),
                 ...(c.pipIndex ? { SEMA_PIP_INDEX: c.pipIndex } : {}),
                 ...(uvIndex ? { SEMA_UV_INDEX: uvIndex } : {}),
                 ...(c.uvPyMirror ? { SEMA_UV_PY_MIRROR: c.uvPyMirror } : {}),
                 ...(c.npmRegistry ? { SEMA_NPM_REGISTRY: c.npmRegistry } : {}),
                 ...(c.nodeMirror ? { SEMA_NODE_MIRROR: c.nodeMirror } : {}),
+                // and the unambiguous env-first mappings (work on existing images, no hook needed)
                 ...(c.pipIndex ? { PIP_INDEX_URL: c.pipIndex } : {}),
                 ...(uvIndex ? { UV_DEFAULT_INDEX: uvIndex, UV_INDEX_URL: uvIndex } : {}),
                 ...(c.uvPyMirror ? { UV_PYTHON_INSTALL_MIRROR: c.uvPyMirror } : {}),
@@ -40,9 +74,12 @@ export function derivePkgSourceEnv(profile, custom) {
             };
         }
         default:
+            // unknown profile — inject only the marker; the in-image hook logs + no-ops on it (fail-safe, not fail-closed:
+            // a typo'd region must not silently flip a deployment to another region's sources).
             return { SEMA_PKG_SOURCE: profile };
     }
 }
+/** Read the `custom` explicit-URL set from the service process env (operator-trusted deployment config). */
 export function customPkgSourceFromEnv(env = process.env) {
     return {
         ...(env.SEMA_APT_MIRROR ? { aptMirror: env.SEMA_APT_MIRROR } : {}),

package/dist/sealed-key.d.ts

@@ -1,37 +1,90 @@
 import type { Logger } from "./observability/logger.js";
+/** Algorithm tag — MUST equal registry-core's `SEALED_BOX_ALG` (v1 sole value; a different alg on
+ *  the wire is a loud per-model rejection in applyEffective, never a guess). */
 export declare const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
+/** The subset applyEffective needs (keeps sema-registry decoupled from fs/boot concerns). */
 export interface SealedKeyOpener {
     has(publicKeyId: string): boolean;
+    /** All private-key ids this host holds (surfaces in the no-private-key warn for operator triage). */
     ids(): string[];
+    /** Unseal a base64 `crypto_box_seal` ciphertext with the EXACT keypair registered under
+     *  `publicKeyId`. Returns the plaintext (utf-8). THROWS on unknown id / malformed base64 /
+     *  MAC failure — fail-loud is the contract; the caller decides what "loud" looks like.
+     *  🔴 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 {
+    /** 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: {
         publicKeyId: string;
         publicKey: string;
         createdAt: string;
     };
 }
+/** Why a model's sealed key could not be unsealed (the poison-pill diagnosis, see SealedKeyPoison). */
 export type SealedKeyPoisonReason = "sealed_decrypt_failed" | "stale_ciphertext" | "unsupported_alg" | "no_key_store";
+/**
+ * Poison-pill entry for the per-model key map (`config.modelApiKeys`): planted by applyEffective when
+ * a model CARRIES `sealedApiKey` but the ciphertext cannot be unsealed. We deliberately do NOT drop
+ * the model from the map — dropping made "sealed key broken" indistinguishable from "no per-model key
+ * configured", and when the deployment also has a gateway MODEL_API_KEY the model's tasks silently
+ * fell back onto the shared account (the exact hole the no-apiKeyEnv-fallback contract exists to
+ * close). createKeyResolver turns this marker into a task-level `SealedKeyPoisonedError` — never
+ * `undefined`, because undefined IS the "use the gateway key" semantic. Carries DIAGNOSIS only:
+ * never the ciphertext, never any plaintext.
+ */
 export interface SealedKeyPoison {
     readonly sealedKeyPoison: true;
     readonly publicKeyId: string;
     readonly reason: SealedKeyPoisonReason;
+    /** Error CLASS of the unseal failure (e.g. "Error") — never the message (message text is logged
+     *  at plant time; keeping the object minimal keeps every serialization face trivially secret-free). */
     readonly errKind?: string;
+    /** ISO timestamp of the apply that detected the failure. */
     readonly at: string;
 }
 export declare function sealedKeyPoison(publicKeyId: string, reason: SealedKeyPoisonReason, errKind?: string): SealedKeyPoison;
 export declare function isSealedKeyPoison(v: unknown): v is SealedKeyPoison;
+/**
+ * The task-level fail-loud face of a poison pill: thrown by the key resolver on EVERY brain call that
+ * would otherwise authenticate this model, so a broken sealed key fails the task visibly (same family
+ * as a rotation-leg auth failure) instead of silently burning the gateway account. Message carries the
+ * sealed-failure marker (reason + publicKeyId + detection time) plus the operator fix — and nothing
+ * secret (no ciphertext, no plaintext, by construction of SealedKeyPoison).
+ */
 export declare class SealedKeyPoisonedError extends Error {
     readonly publicKeyId: string;
     readonly reason: SealedKeyPoisonReason;
     readonly at: string;
     constructor(modelName: string, poison: SealedKeyPoison);
 }
+/** Default id = fingerprint of the RAW public-key bytes: `exec-<sha256(pk)[0..12) hex>`.
+ *  Deterministic → regenerating the id from the same key file is stable across boots. */
 export declare function deriveKeyId(publicKeyRaw: Uint8Array): string;
+/**
+ * Load every keypair under `dir` (creating dir + ONE fresh keypair when none exist) and return the
+ * custody store. Invalid/corrupt files are skipped with a warn (they may be an OLD format or a
+ * half-write — deleting operator key material on a parse error would destroy decryptability, so we
+ * never do; we just don't serve them). Throws only when the store cannot exist at all (fs errors,
+ * zero loadable keys AND generation failed).
+ */
 export declare function ensureSealedKeyStore(dir: string, logger?: Logger): Promise<SealedKeyStore>;
+/**
+ * Best-effort public-key registration with the sema-registry (`POST /api/config/execution-keys`).
+ *
+ * HONESTY over fake automation: that endpoint is ADMIN-gated, and a fleet worker only holds
+ * SERVICE_PULL_TOKEN — so automatic registration works ONLY when the operator deliberately provides
+ * an admin token (SEMA_REGISTRY_ADMIN_TOKEN / REGISTRY_ADMIN_TOKEN in this service's env). Without
+ * one we do the next-best REAL thing: print the FULL public key + id at boot (a public key is not a
+ * secret) with the exact registration instructions, and warn that the web "paste key" face stays
+ * dark for this host until an admin registers it. Never throws (fire-and-forget from boot).
+ */
 export declare function reportExecutionPublicKey(opts: {
+    /** sema-registry base URL (config.configCenter.baseUrl). Absent = no center → manual print only. */
     baseUrl?: string;
+    /** Admin bearer for the center's config write face. Absent = manual print (see above). */
     adminToken?: string;
     key: {
         publicKeyId: string;
@@ -40,6 +93,7 @@ export declare function reportExecutionPublicKey(opts: {
     };
     notes?: string;
     logger?: Logger;
+    /** Test seam. */
     fetchImpl?: typeof fetch;
 }): Promise<void>;
 //# sourceMappingURL=sealed-key.d.ts.map

package/dist/sealed-key.js

@@ -1,9 +1,35 @@
+/**
+ * Sealed-box key custody — the EXECUTION-SIDE half (registry-core 0.10.5/0.10.6):
+ * the user pastes a model API key in the web UI, the BROWSER seals it against this host's X25519
+ * public key (libsodium `crypto_box_seal`), the center stores ONLY the ciphertext
+ * (`ModelEntry.sealedApiKey`, write-only face), and THIS module unseals it at apply time so the
+ * plaintext exists nowhere but this process's memory (`config.modelApiKeys` → getApiKeyAndHeaders).
+ *
+ * Custody layout: `<localDataRoot>/sealed-key/<publicKeyId>.json` — ONE FILE PER KEYPAIR (0600,
+ * dir 0700). Several keypairs MAY coexist: rotation registers a NEW public key with the center
+ * (new ciphertexts are sealed against the newest `createdAt`) while OLD ciphertexts still carry
+ * their old `publicKeyId` — they stay decryptable exactly as long as the operator keeps the old
+ * private-key file around (the registry-core contract: "旧密文可解性=执行侧留存旧私钥决定").
+ * Selection is EXACT by `publicKeyId` — no try-every-key scanning: an id with no file is a loud
+ * per-model failure upstream (applyEffective), never a silent fallback.
+ *
+ * Crypto choice: sealed box (`crypto_box_seal`) is a libsodium-specific construction (ephemeral
+ * X25519 keypair + XSalsa20-Poly1305, nonce = BLAKE2b(epk‖rpk)) — node:crypto has no BLAKE2b and
+ * no sealed box, and tweetnacl (already in the tree via ssh2) lacks BLAKE2b too, so we depend on
+ * `libsodium-wrappers` (pure JS + WASM: no native build step, CI/cross-arch friendly, and the
+ * same library the browser side uses — byte-compatible by construction).
+ */
 import { createHash } from "node:crypto";
 import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import _sodium from "libsodium-wrappers";
+/** Algorithm tag — MUST equal registry-core's `SEALED_BOX_ALG` (v1 sole value; a different alg on
+ *  the wire is a loud per-model rejection in applyEffective, never a guess). */
 export const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
+/** crypto_box_seal overhead: 32B ephemeral pk + 16B MAC. Anything shorter cannot be a sealed box. */
 const SEAL_OVERHEAD_BYTES = 48;
+/** Strict base64 shape (standard alphabet, optional padding) — `Buffer.from(b64)` is lenient and
+ *  would silently swallow garbage, turning "corrupt ciphertext" into a misleading MAC failure. */
 const BASE64_STRICT = /^[A-Za-z0-9+/]+={0,2}$/;
 export function sealedKeyPoison(publicKeyId, reason, errKind) {
     return { sealedKeyPoison: true, publicKeyId, reason, ...(errKind ? { errKind } : {}), at: new Date().toISOString() };
@@ -11,6 +37,13 @@ export function sealedKeyPoison(publicKeyId, reason, errKind) {
 export function isSealedKeyPoison(v) {
     return typeof v === "object" && v !== null && v.sealedKeyPoison === true;
 }
+/**
+ * The task-level fail-loud face of a poison pill: thrown by the key resolver on EVERY brain call that
+ * would otherwise authenticate this model, so a broken sealed key fails the task visibly (same family
+ * as a rotation-leg auth failure) instead of silently burning the gateway account. Message carries the
+ * sealed-failure marker (reason + publicKeyId + detection time) plus the operator fix — and nothing
+ * secret (no ciphertext, no plaintext, by construction of SealedKeyPoison).
+ */
 export class SealedKeyPoisonedError extends Error {
     publicKeyId;
     reason;
@@ -25,6 +58,8 @@ export class SealedKeyPoisonedError extends Error {
         this.at = poison.at;
     }
 }
+/** Default id = fingerprint of the RAW public-key bytes: `exec-<sha256(pk)[0..12) hex>`.
+ *  Deterministic → regenerating the id from the same key file is stable across boots. */
 export function deriveKeyId(publicKeyRaw) {
     return `exec-${createHash("sha256").update(publicKeyRaw).digest("hex").slice(0, 12)}`;
 }
@@ -33,11 +68,18 @@ function b64ToBytes(b64, what) {
         throw new Error(`${what}: not valid base64`);
     return new Uint8Array(Buffer.from(b64, "base64"));
 }
+/**
+ * Load every keypair under `dir` (creating dir + ONE fresh keypair when none exist) and return the
+ * custody store. Invalid/corrupt files are skipped with a warn (they may be an OLD format or a
+ * half-write — deleting operator key material on a parse error would destroy decryptability, so we
+ * never do; we just don't serve them). Throws only when the store cannot exist at all (fs errors,
+ * zero loadable keys AND generation failed).
+ */
 export async function ensureSealedKeyStore(dir, logger) {
     await _sodium.ready;
     const sodium = _sodium;
     await mkdir(dir, { recursive: true, mode: 0o700 });
-    await chmod(dir, 0o700);
+    await chmod(dir, 0o700); // mkdir's mode is ignored when the dir pre-exists — enforce anyway
     const keys = new Map();
     for (const name of (await readdir(dir)).filter((n) => n.endsWith(".json")).sort()) {
         const path = join(dir, name);
@@ -50,6 +92,8 @@ export async function ensureSealedKeyStore(dir, logger) {
             const privateKey = b64ToBytes(raw.privateKey, "privateKey");
             if (publicKey.length !== sodium.crypto_box_PUBLICKEYBYTES || privateKey.length !== sodium.crypto_box_SECRETKEYBYTES)
                 throw new Error("bad key length");
+            // The file's OWN publicKeyId is authoritative (operators may hand-register custom ids with the
+            // center); a filename drift is only cosmetic — warn, honor the content.
             if (name !== `${raw.publicKeyId}.json`)
                 logger?.warn("sealed_key_filename_drift", { file: name, publicKeyId: raw.publicKeyId, note: "content publicKeyId wins; rename the file to silence this" });
             if (keys.has(raw.publicKeyId)) {
@@ -59,6 +103,10 @@ export async function ensureSealedKeyStore(dir, logger) {
             keys.set(raw.publicKeyId, { publicKey, privateKey, publicKeyB64: raw.publicKey, createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "" });
         }
         catch (err) {
+            // Never delete: could be operator key material in an older/foreign format — unreadable here ≠ worthless.
+            // 🔴 审计 #4 LOW: JSON.parse's SyntaxError EMBEDS ~20 chars of the offending input — a file corrupted
+            // near the `privateKey` field would leak a base64 fragment of the secret into the log. Record only
+            // the error CLASS (err.name), never the message.
             logger?.warn("sealed_key_file_unreadable", { file: path, errKind: err instanceof Error ? err.name : "unknown", note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" });
         }
     }
@@ -75,10 +123,11 @@ export async function ensureSealedKeyStore(dir, logger) {
         };
         const path = join(dir, `${record.publicKeyId}.json`);
         await writeFile(path, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
-        await chmod(path, 0o600);
+        await chmod(path, 0o600); // writeFile mode is masked by umask — enforce the exact custody mode
         keys.set(record.publicKeyId, { publicKey: kp.publicKey, privateKey: kp.privateKey, publicKeyB64, createdAt: record.createdAt });
         logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair — register the PUBLIC key with the registry (see sealed_key_public_key)" });
     }
+    // Newest createdAt = the key new ciphertexts must target (registry contract); ties → lexicographic id.
     const latestEntry = [...keys.entries()].sort((a, b) => (a[1].createdAt < b[1].createdAt ? 1 : a[1].createdAt > b[1].createdAt ? -1 : a[0] < b[0] ? -1 : 1))[0];
     return {
         latest: { publicKeyId: latestEntry[0], publicKey: latestEntry[1].publicKeyB64, createdAt: latestEntry[1].createdAt },
@@ -91,13 +140,25 @@ export async function ensureSealedKeyStore(dir, logger) {
             const ciphertext = b64ToBytes(ciphertextB64, "ciphertext");
             if (ciphertext.length < SEAL_OVERHEAD_BYTES)
                 throw new Error(`ciphertext too short (${ciphertext.length}B < sealed-box ${SEAL_OVERHEAD_BYTES}B overhead)`);
+            // Throws on MAC failure (wrong key / corrupt ciphertext) — exactly the loudness we want.
             return sodium.to_string(sodium.crypto_box_seal_open(ciphertext, key.publicKey, key.privateKey));
         },
     };
 }
+/**
+ * Best-effort public-key registration with the sema-registry (`POST /api/config/execution-keys`).
+ *
+ * HONESTY over fake automation: that endpoint is ADMIN-gated, and a fleet worker only holds
+ * SERVICE_PULL_TOKEN — so automatic registration works ONLY when the operator deliberately provides
+ * an admin token (SEMA_REGISTRY_ADMIN_TOKEN / REGISTRY_ADMIN_TOKEN in this service's env). Without
+ * one we do the next-best REAL thing: print the FULL public key + id at boot (a public key is not a
+ * secret) with the exact registration instructions, and warn that the web "paste key" face stays
+ * dark for this host until an admin registers it. Never throws (fire-and-forget from boot).
+ */
 export async function reportExecutionPublicKey(opts) {
     const { baseUrl, adminToken, key, notes, logger } = opts;
     const manual = (why) => {
+        // Full key on purpose: the OPERATOR completes registration by hand. publicKey is public material.
         logger?.warn("sealed_key_public_key", {
             publicKeyId: key.publicKeyId,
             publicKey: key.publicKey,
@@ -121,17 +182,21 @@ export async function reportExecutionPublicKey(opts) {
             signal: AbortSignal.timeout(10_000),
         });
         if (res.ok) {
+            // center 幂等语义:同 id 同 key 重复上报 = 200 {ok,key,idempotent:true}(boot 重报常态)。
             let idempotent = false;
             try {
                 idempotent = (await res.json())?.idempotent === true;
             }
-            catch { }
+            catch { /* body 非 JSON 也算 reported */ }
             logger?.info(idempotent ? "sealed_key_already_registered" : "sealed_key_reported", { publicKeyId: key.publicKeyId, status: res.status });
         }
         else if (res.status === 409) {
+            // 409 = 并发写 CAS 冲突(retry 语义,非「已注册」)。boot 是一次性上报,不循环重试——
+            // 下次 boot 自然重报;这里降级为 manual 面(诚实姿势:本次没写成)。
             manual("registry returned 409 (concurrent write; will re-report on next boot)");
         }
         else {
+            // 400 同 id 异 key = 指纹碰撞或密钥文件被改,绝不静默——manual 面带上下文。
             manual(`registry rejected the report (HTTP ${res.status})`);
         }
     }

package/dist/security.d.ts

@@ -5,6 +5,8 @@ import type { TaskRequestBody } from "./http/wire-types.js";
 import type { StagingHandle } from "./session-sync-kernel.js";
 export { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
 export type { ApprovalHmacKey, PrincipalJwtKey } from "./auth-keys.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 {
     sessionId: string;
     owner: string | null;
@@ -13,12 +15,18 @@ export interface SessionListItem {
     runCount: number;
     objectivePreview: string | null;
     lastStatus: string;
+    /** 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;
+    /** Auto-generated session title (null = untitled / lister face has no session_meta). */
     title: string | null;
 }
+/** A SessionStore that may additionally expose tenant-ownership ops (the TiDB store does) AND the
+ *  `SessionRepo` enumeration/lifecycle seam (§0.5: list/fork/delete homed on the session abstraction's own
+ *  tables, not the `task_run` runs ledger). All optional — an in-memory dev store implements none. */
 export type OwnerAwareSessionStore = SessionStore & {
     ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
     register?: (sessionId: string, owner: string | null) => Promise<void>;
+    /** E16 — enumerate the caller's sessions (owner-filtered on the session store's OWN owner column). */
     listSessions?: (opts: {
         owner?: string;
         cursor?: {
@@ -28,27 +36,73 @@ export type OwnerAwareSessionStore = SessionStore & {
         limit: number;
         q?: string;
     }) => Promise<SessionListItem[]>;
+    /** E17 — fork a session's whole history to a NEW session owned by `owner`; null if the source is unknown. */
     fork?: (sourceId: string, owner: string | null) => Promise<string | null>;
+    /** E18 — the session's current leaf `SessionTreeEntry.id` (a cache-bypassing single read), so the resume-at
+     *  turn-capture can pair it with the turn's message eventId. null when the session has no leaf / does not exist. */
     getLeafId?: (sessionId: string) => Promise<string | null>;
+    /** [1196] 六轮复审:owner+leafId 单行原子快照(SSE watch 探针租户围栏读;两独立读在 delete/reclaim
+     *  缝里可拼出混世代组合)。undefined=无此会话。 */
     getHead?: (sessionId: string) => Promise<{
         owner: string | null;
         leafId: string | null;
     } | undefined>;
+    /** E21 — purge a session's conversation history (session_meta/session_event); idempotent (false if absent).
+     *  `owner` is the single-DB-fleet null-safe SQL owner guard on `session_meta.owner` (defense-in-depth — the
+     *  route already owner-gates; this pins the DELETE to the authenticated tenant so even a buggy gate can't purge
+     *  another tenant's history). */
     deleteSession?: (sessionId: string, owner: string | null) => Promise<boolean>;
+    /** 2c session-sync — EXPORT a session's full durable entry log (compaction floor bypassed) for
+     *  cross-backend migration; `null` when the source is unknown (the read half of fork, as `SessionTreeEntry[]`). */
     exportEntries?: (sessionId: string) => Promise<SessionTreeEntry[] | null>;
+    /** 2c session-sync P1d-α (PULL streaming) — the IDS-ONLY projection of a session's full durable log, oldest-first
+     *  (`SELECT entry_id … ORDER BY seq ASC`). `null` when the source is unknown (mirrors {@link exportEntries}' null).
+     *  Small even for a huge session (no payloads) → the PULL `GET /sync/manifest` carries this instead of the entries,
+     *  and the local peer feeds it to `classifySyncRelationshipByIds` to decide fast-forward / fork before pulling. */
     listEntryIds?: (sessionId: string) => Promise<string[] | null>;
+    /** 2c session-sync P1d-α (PULL streaming) — STREAM a session's full durable entry log (compaction floor bypassed),
+     *  oldest-first, as an async iterable of {@link SessionTreeEntry} so the `GET /sync/entries` NDJSON route holds
+     *  BOUNDED memory regardless of session size (mysql2/pg buffer a plain SELECT → this KEYSET-pages internally,
+     *  `WHERE seq > cursor … LIMIT batchSize`, advancing the cursor each batch, ONE pooled query per batch — a slow
+     *  consumer never pins a connection). `opts.afterSeq` resumes after a given 0-based dense seq (default -1 = from 0);
+     *  `opts.batchSize` is the page size (default 500). Resolves to `null` (NOT an empty iterable) when the session does
+     *  not exist (the existence probe is async — `session_meta` first, like {@link exportEntries} — so the method returns
+     *  a Promise of the iterable-or-null; the iterable itself then pages lazily). The read half of exportEntries, paged. */
     exportEntriesStream?: (sessionId: string, opts?: {
         afterSeq?: number;
         batchSize?: number;
     }) => Promise<AsyncIterable<SessionTreeEntry> | null>;
+    /** 2c session-sync — IMPORT a verbatim entry log into `sessionId`, re-stamping `owner` to the
+     *  authenticated importing principal (never the bundle's). The log is passed through core's
+     *  `validateEntriesForImport` (the single fail-closed invariant gate) before any write. */
     importEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
+    /** 2c session-sync (§7/§8) — IDEMPOTENT replace: atomically purge any existing conversation log for `sessionId`
+     *  then import `entries` verbatim under `owner`. Unlike importEntries (plain INSERT, fresh-only) this is safe to
+     *  re-run / apply over an existing session (fast-forward, retry). owner-guarded delete (defense-in-depth). */
     replaceEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
+    /** 2c session-sync P1d-β (PUSH streaming) — begin a STAGED import into `realSessionId` under a shadow id
+     *  `${realSessionId}#stg-${token}` (the route mints the uuidv7 `token`). Returns a {@link StagingHandle} the NDJSON
+     *  Phase-B route streams batches into (`appendBatch`) then commits (`commit`, the atomic swap) / aborts. The shadow
+     *  rows have NO session_meta → invisible to wake until commit writes meta LAST = the sole commit point. */
     beginImportStaging?: (realSessionId: string, token: string) => StagingHandle;
+    /** 2c session-sync P1d-β (staged-row inspection) — read the rows STAGED under a `${realSessionId}#stg-${token}` id
+     *  (NO session_meta probe — `exportEntries` returns null for an unregistered id), oldest-first. The import gate is now
+     *  the per-line `StreamingImportValidator` (core 1.143.0) driven during the stream, so this is no longer the
+     *  validation path; it remains the staged-row inspection seam (idempotency/dedup tests, diagnostics). Returns `[]` for
+     *  an empty/unknown staging id. */
     readStagedEntries?: (stagingId: string) => Promise<SessionTreeEntry[]>;
+    /** 2c session-sync P1d-β (§4) — reaper for ABANDONED staging sessions: drop staging-id session_event rows with NO
+     *  session_meta whose oldest row is older than the grace window (an in-flight stream stays fresh → never reaped).
+     *  Returns the affected row count. Durable twins only (local stages in memory → no durable rows to reap → absent). */
     sweepStagingSessions?: () => Promise<number>;
 };
+/** True iff `s` matches the canonical uuidv7 shape core mints (see {@link UUIDV7_RE}). */
 export declare function isUuidV7(s: string): boolean;
 export declare function isUuidShape(s: string): boolean;
+/** An HTTP error the server maps to a status code (instead of a generic 500). `code` (optional) is a stable
+ *  machine-readable identifier the HTTP layer echoes as `{code}` beside the human `{error}` message — the
+ *  "typed rejection" posture (structured code on the wire, prose stays with the shell/web).
+ *  `extra` (optional) is folded into the error body verbatim (e.g. the scenario allowlist on a reject). */
 export declare class HttpError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -58,21 +112,75 @@ export declare class HttpError extends Error {
         extra?: Record<string, unknown>;
     });
 }
+/**
+ * Authorization context resolved per request, BEFORE building the TaskSpec. The service owns this —
+ * identity and tenant scope come from the authenticated channel, **never from the request body**.
+ */
 export interface AuthContext {
+    /** Authenticated principal, e.g. `user:42` / `org:7`. Undefined when principal auth is off (dev). */
     principal?: string;
+    /** The session to run against (resolved + ownership-checked here, then returned to the caller). */
     sessionId: string;
+    /** Long-term memory scope, derived from the principal (not the body). Undefined disables memory. */
     memoryScope?: string;
+    /** 142-S4:the request's SHAPE-VALIDATED projectId (body.projectId 过 PROJECT_ID_REGEX 门后回传)。
+     *  身份半场(scope 的 tenant 段)永远来自 verified principal — projectId 只选「哪个项目盘/哪条登记」
+     *  (config.projects 查表键 + proj: 键的 projectId 段),不是 capability。main.ts 拿它查 defaultScopes。 */
     resolvedProjectId?: string;
 }
+/**
+ * S6 — close the "sessionId / scope are bearer capabilities" hole.
+ *
+ * The principal is read from a trusted header set by the authenticated caller (e.g. the OA backend
+ * that already holds the service token). It is NOT taken from the request body, so a caller cannot
+ * forge identity by passing `scope`/`sessionId` for another tenant.
+ *
+ * Then:
+ *   - a supplied `sessionId` is ownership-checked against `session_meta.owner` (403 on mismatch);
+ *     an unknown id is claimed for this principal; a missing id mints a fresh owned session;
+ *   - the memory scope is derived from the principal.
+ *
+ * Returns a function shaped for `ServiceDeps.authorize`. When `sessionStore` is not the TiDB store
+ * (e.g. in-memory dev backend) ownership can't be enforced, so it only derives principal + sessionId.
+ */
 export declare function createAuthorizer(config: ServiceConfig, sessionStore: OwnerAwareSessionStore): (ctx: {
     req: IncomingMessage;
     body: TaskRequestBody;
 }) => Promise<AuthContext>;
+/** F1/F3 (codex scope-ledger audit 2026-07-14) — the auth-boundary principal SHAPE gate, applied to every
+ *  verified identity source (trusted header, SSO-bridge sub, direct-door JWT sub) so no downstream consumer
+ *  ever sees an ambiguous or over-wide principal:
+ *   - RESERVED internal identifiers are REJECTED (修1, 三路复审 A 组 HIGH — see {@link RESERVED_PRINCIPALS} /
+ *     {@link RESERVED_PRINCIPAL_PREFIXES} below): a REAL tenant whose principal string-equals an internal scope
+ *     sentinel would pass the plain string-compare owner/scope gates downstream and merge with internal rows —
+ *     e.g. `"_"` merges with the anonymous scope family (the checkpoint scope column `auth?.principal ?? "_"`
+ *     at suspend, and the decide owner-gate treats `cp.scope === "_"` as anonymous-OPEN, server.ts ~L3710; the
+ *     SendUserFile ledger scope + the /v1/sendfile-links fleet-wide default; the resource-suspend isolation
+ *     key), `"_leader"` merges with the leader durable-approval owner scope (a tenant so named could list/
+ *     decide internal leader approvals), `"_leader-…"` with the leader resource-suspend scope family, and
+ *     `"__none__"` with the missing-principal placeholder scope on the decide/pending gates.
+ *   - length > 190 is REJECTED: every scope/owner column the principal lands in VERBATIM is VARCHAR(190)
+ *     (sendfile_link.scope, approval.owner/scope, memory-engine scope, rate-limit keys, …) — an over-long
+ *     principal would truncate/500 at the INSERT and split one identity into two.
+ *  Throws a typed 400 `HttpError` (the HTTP layer maps it); the message names the rule (a reserved identifier /
+ *  the length cap), never a secret and never the internal scope's semantics. */
 export declare const PRINCIPAL_MAX_LENGTH = 190;
+/** 修1 — the SINGLE registry of internal sentinel/scope identifiers a tenant principal must never equal.
+ *  🔴 新增内部 sentinel scope 必须在此登记(精确值加 RESERVED_PRINCIPALS,前缀族加
+ *  RESERVED_PRINCIPAL_PREFIXES),否则 assertPrincipalShape 会放行同名租户 = 与内部 scope 行合流的越权面。
+ *  Current entries (where each is minted): `"_"` = single-user/anonymous sentinel (checkpoint/sendfile/
+ *  resource-suspend scope family); `"__none__"` = missing-principal placeholder on the decide/pending gates
+ *  (http/server.ts `principal ?? "__none__"`); `"_leader"` = leader durable-approval scope
+ *  (src/leader/wire.ts); prefix `"_leader-"` = the leader resource-suspend scope family
+ *  (`_leader-resource-<workerId>`, src/leader/wire.ts). NB the prefix REQUIRES the hyphen — a tenant named
+ *  `_leaderX` collides with nothing internal and stays valid (boundary pinned by test). */
 export declare const RESERVED_PRINCIPALS: readonly string[];
 export declare const RESERVED_PRINCIPAL_PREFIXES: readonly string[];
 export declare function assertPrincipalShape(principal: string): void;
+/** Read the authenticated principal from the trusted header. Never from the body. */
 export declare function principalFrom(req: IncomingMessage, config: ServiceConfig): string | undefined;
+/** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
+ *  verifies). The trusted twin of `config.principalHeader` (the latter is client-spoofable on a direct door). */
 export declare const PRINCIPAL_TOKEN_HEADER = "x-approval-principal-token";
 export declare function setSsoPrincipal(req: IncomingMessage, principal: string): void;
 export declare function ssoVerifiedPrincipal(req: IncomingMessage): string | undefined;