@sema-agent/server 1.322.0 → 2.0.0

package/dist/config-types.d.ts

@@ -1,64 +1,189 @@
+/** design/158 A1: the ServiceConfig TYPE face, split out of the 1.8k-line loader module (config.ts)
+ *  so pure-type consumers (http/server, plugins/*, hooks/hook-llm, security, brain, sema-registry)
+ *  depend on a LEAF with zero runtime edges — this is the substantive step that dissolves the
+ *  type-closed edges into config.ts (lens2 §A). TYPES ONLY: loadConfig and every runtime value stay
+ *  in config.ts, which re-exports these names so existing `from "./config.js"` importers keep
+ *  compiling unchanged. All imports below are top-level `import type` (erased — never a load edge,
+ *  see test/module-cycle-gate.test.ts header on verbatimModuleSyntax). */
 import type { SealedKeyPoison } from "./sealed-key.js";
 import type { McpServerSpec, Model, ModelRoles } from "@sema-agent/core";
 import type { ApprovalHmacKey, PrincipalJwtKey } from "./auth-keys.js";
 import type { ElicitationThrottle } from "./elicitation.js";
 import type { InfraCostRates } from "./observability/cost-taxonomy.js";
 import type { Autonomy, CommandRule } from "./runtime-governance.js";
+/** A sema-registry MCP server resolved to a core spec (env-NAME refs already → real values) plus the
+ *  scenarios it applies to (empty = all). `resolveSpec` filters by scenario and passes `spec` to core. */
 export interface ScopedMcpServer {
     scenarios: string[];
     spec: McpServerSpec;
 }
+/** Sandbox-image-pool BAKE config (IMAGE-API-DESIGN.md §P2). `enabled=false` ⇒ the /v1/images/bakes* block is
+ *  off (the control plane never mounts). The runner-facing facts (the runner principal, the build-host CACHE_BASE,
+ *  the default base ref) live here so image-api injects only VETTED, server-fixed values into the build.sh argv —
+ *  operator free-text never reaches the runner. */
 export interface ImageBakeConfig {
     enabled: boolean;
+    /** The dedicated operator principal the bake-runner authenticates as on the internal claim/ingest routes
+     *  (§P2.4e). A runner-only route requires the resolved principal to EXACTLY equal this. `BAKE_RUNNER_PRINCIPAL`
+     *  (default `system:bake-runner`). */
     runnerPrincipal: string;
+    /** The registry host prefix the auto-registered repo/ref is built under, so an `push:true` bake row's
+     *  `repo = ${registry}/${profile}` matches the P1 seed convention (seed-image-index.ts) and the index id
+     *  `sha256(repo@digest)` is stable across seed and bake. `BAKE_IMAGE_REGISTRY` env; **code default = null**
+     *  ⇒ the host-less `sema-images/<profile>` (node-local, documented non-pullable). Fleet posture (clay 拍
+     *  2026-07-13, SWR 弃用): `docker.io/claybobby`(海外主源;CN 兜底=内网 Gitea registry)。 */
     registry: string | null;
+    /** The build-host promoted fetch-once cache base injected as `--cache-base` (NEVER caller-settable — a foreign
+     *  origin would defeat the domestic-only iron rule). `BAKE_CACHE_BASE` (e.g. http://172.17.0.1:8099). */
     cacheBase: string | null;
+    /** The pinned current sandbox-base ref injected as `--base-ref` when the caller omits `baseRef` (§P2.4c default).
+     *  When NULL the server falls back to the index's latest published `sandbox-base` digest (design §P2.4c
+     *  "SANDBOX_BASE_REF / the index's latest published base"), so a deployment that publishes a sandbox-base needs
+     *  no separate pin. A caller-supplied baseRef must additionally be a known-published sandbox-base digest in the
+     *  index. `SANDBOX_BASE_REF` (sha256:…). */
     defaultBaseRef: string | null;
+    /** The lease duration / heartbeat window (ms) — the runner heartbeats `lease_until` forward within this and
+     *  the reaper steals an expired lease. `BAKE_LEASE_MS` (default 90000 ≈ 3× a 30s heartbeat). */
     leaseMs: number;
+    /** A `running` bake whose lease is stale by more than this (ms) is reaped → failed (§P2.7). Must exceed >2
+     *  lease-heartbeat intervals. `BAKE_STALE_MS` (default 180000). */
     staleMs: number;
+    /** Per-principal submission rate guard window seconds + max (§P2.4c — fills the register DoS gap). 0 = off.
+     *  `BAKE_SUBMIT_RATE_MAX` / `BAKE_SUBMIT_RATE_WINDOW_SEC` (default 10 per 60s). */
     submitRateMax: number;
     submitRateWindowSec: number;
 }
+/** Service configuration, read from environment. */
 export interface ServiceConfig {
     port: number;
+    /** OpenAI-compatible model gateway base URL (without /chat/completions). */
     gatewayBaseUrl: string;
     gatewayApiKey?: string;
+    /** Secondary openai-compatible gateways for cross-gateway FAILOVER (same protocol + same model id).
+     *  Tried in order after the primary when a gateway fails before streaming any content. */
     gatewayFallbackUrls: string[];
+    /** Optional Anthropic Messages API ROUTE (cloud). Selected for models whose `provider` is
+     *  "anthropic" (routing is by model.provider); the local gateway serves every other provider. */
     anthropic?: {
+        /** `x-api-key` auth. OPTIONAL since the Anthropic-compatible Bearer path: a Bearer-only
+         *  provider may auth by `authToken` alone. When BOTH are set, authToken wins. */
         apiKey?: string;
+        /** Anthropic-compatible-ecosystem `ANTHROPIC_AUTH_TOKEN` (many such providers use Bearer, not x-api-key):
+         *  sent as `Authorization: Bearer <token>`; when set, `apiKey` is NOT sent (二选一, AUTH_TOKEN priority). */
         authToken?: string;
+        /** Default https://api.anthropic.com (overridden by model.baseUrl). */
         baseUrl?: string;
+        /** `anthropic-version` header; core default 2023-06-01. */
         version?: string;
+        /** Prompt-cache breakpoints on system + last tool (stable prefix). Default true. */
         cacheBreakpoints: boolean;
         maxRetries: number;
     };
+    /** Resilience brain stack (1.38, design/27): tiered timeouts + an optional circuit breaker layered
+     *  UNDER the existing failover (gatewayFallbackUrls). Every field defaults to off/disabled, so the
+     *  brain composition stays byte-identical until an operator opts in. The breaker only changes
+     *  behaviour when paired with ≥2 gateway routes (it fast-fails a tripped primary so failover switches
+     *  immediately instead of waiting out timeouts). BreakerState is core's in-process Map for now —
+     *  cross-replica shared state (TiDB adapter) is a documented follow-up. */
     resilience: {
+        /** Abort fetch if response headers don't arrive within this many ms → retryable [network].
+         *  Default 30s ([880] fleet audit). 0 = off. */
         connectTimeoutMs: number;
+        /** Cancel an open SSE stream if no content/thinking delta arrives within this many ms.
+         *  Default 120s ([880] fleet audit — core's idle timer only arms after the first token,
+         *  so this is the only guard for a stream that opens and never emits). 0 = off. */
         firstTokenTimeoutMs: number;
+        /** Mid-stream stall watchdog (1.40.1): after output starts, re-armed on every delta; silence for
+         *  this many ms → cancel + retryable [network]. Catches a gateway that hangs AFTER the first token
+         *  (firstTokenTimeoutMs only covers the first). 0 = off. */
         idleTimeoutMs: number;
+        /** Wrap the primary gateway route(s) in a circuit breaker (in-process state, per model+provider). */
         circuitBreaker: boolean;
+        /** Consecutive transient failures (network/server/rate_limit) that trip the breaker. */
         failureThreshold: number;
+        /** How long the breaker stays open before a half-open probe (ms). */
         cooldownMs: number;
     };
+    /** Default model the service runs tasks on. */
     model: Model;
+    /** Model catalog by name (1.24): always `default` + the main model's id, plus an optional cheap model.
+     *  Used to resolve roles and to allow-list `@-model` mentions. */
     models: Record<string, Model>;
+    /** Per-model API-key override: catalog model NAME → the env var NAME holding that model's key (from
+     *  sema-registry `apiKeyEnv`). Drives the spec's `getApiKeyAndHeaders` so each model/rung authenticates
+     *  with its own upstream account; a model absent here falls back to the gateway key. Env path: empty. */
     modelApiKeyEnv: Record<string, string>;
+    /** sealed-box 托管密钥的解封产物:catalog model NAME → PLAINTEXT api key(`ModelEntry.
+     *  sealedApiKey` 按 publicKeyId 选本机私钥 crypto_box_seal_open 解封,src/sealed-key.ts)。
+     *  🔴 只活在内存 —— 绝不落日志/盘/任何序列化面。互斥语义(registry-core 契约):模型带 sealedApiKey
+     *  ⇒ 它的 apiKeyEnv 引用不采(sealed 压过 env-NAME,解封失败也不回落——fail-loud 见 applyEffective)。
+     *  Env path: empty;populated ONLY by applyEffective(重赋值;keyResolver 随 boot/refresh 重建)。 */
+    /** 值=解封明文 或 SealedKeyPoison 毒丸(解封失败标记;key-resolver 对其任务级 throw,恒不落 gateway key 兜底)。 */
     modelApiKeys: Record<string, string | SealedKeyPoison>;
+    /** 配额倍率表(name+id 双键→ModelEntry.quotaWeight):weight-at-burn 的运行时源——tracer 在
+     *  brain.call 记账点读它算 weightedTokens(lease 双轴+usage 批报)。registry apply IN-PLACE hot-apply;
+     *  env lane 恒空(无倍率概念,weight=1 兜底)。 */
     modelQuotaWeights: Record<string, number>;
+    /** registry-core 0.9.0 档位组: the resolved active tier table (`tier word → catalog model name`,
+     *  e.g. `{pro: "ds-pro"}`) fed to `RunnerDeps.tiers` (core 1.265 expandTiers — tier words + CC aliases become
+     *  catalog keys). NO env source — populated ONLY by applyEffective from `models.tierGroups`/`activeTierGroup`
+     *  via registry-core `resolveActiveTiers` (single semantic source). Empty = INERT (core contract). Consumed at
+     *  Runner CONSTRUCTION (restart-to-apply, same tier as models/roles); mutateInPlace keeps the reference. */
     tiers: Record<string, string>;
+    /** 142-S4(registry-core 0.10.0 projects 域):center 项目登记簿的 service 消费面 —
+     *  键=projectId(PROJECT_ID_REGEX,generic lowercase UUID)。消费点:①`memoryScopeFor` 第三参数
+     *  (projectId 在场 ⇒ 项目盘 v2 键 `proj:<tenant>/<projectId>`);②`defaultScopes` 作
+     *  `TaskSpec.memory.scopes` 的种子(v2 scope 键串,OPEN 值域——本表只登记不解释)。NO env source —
+     *  populated ONLY by applyEffective(mutateInPlace,boot+refresh 整表替换);env lane 恒空(INERT)。
+     *  ProjectRegistration 的审计字段(registeredBy/registeredAt/notes)不进 ServiceConfig(runtime 不消费)。 */
     projects: Record<string, {
         displayName?: string;
         gitRemotes?: string[];
         defaultScopes?: string[];
     }>;
+    /** Role → model map (1.24): `subagent`/`summarize` → the cheap model when `MODEL_CHEAP_ID` is set
+     *  (council lenses + compaction get cheap), `default`/`team`/`synthesize` stay on the main model. */
     roles: ModelRoles;
+    /**
+     * Session backend: in-memory (default), tidb (durable L1 event-log center), or `auto` — probe a
+     * configured DB at startup and fall back to in-memory if it's unreachable (for local/intranet binaries:
+     * "use my DB if I can reach it, else memory"). `auto` is resolved to a concrete value during startup.
+     * NOTE (clay 2026-07-06 wording): the env value `mysql` is accepted as an alias and normalized to the
+     * internal `tidb` label here — `"tidb"` in code reads as "the durable SQL store" generically (whichever
+     * engine DB_BACKEND picks), a historical label kept to avoid churning every comparison site.
+     */
     sessionBackend: "memory" | "tidb" | "auto";
+    /** Warm-cache idle TTL (seconds) for woken TiDB sessions; 0 disables. Requires session affinity. */
     sessionCacheTtlSec: number;
+    /** Rewind snapshot bounds: byte cap in MB (env REWIND_SNAPSHOT_MAX_MB). Unset = core DEFAULT_SNAPSHOT_BOUNDS
+     *  (256 MiB / 10000 files as of core 2026-06-26 — was 2000/64MiB). BYTE-ONLY knob: raises OR lowers just the byte
+     *  cap; file-count/ignoreDirs stay core defaults (more knobs when a case shows up). */
     rewindSnapshotMaxMb?: number;
+    /** Long-term memory (design/138 S1, clay 2026-07-08): the injection-first file-based memory ENGINE
+     *  (core `RunnerDeps.memoryBackend` + `MemoryEngine`) is the ONLY memory plane — the legacy MemoryStore
+     *  path (MEMORY_BACKEND/EMBEDDING_* SQL/file note stores) was dropped without migration. Default ON;
+     *  `MEMORY_ENGINE=off` is the explicit kill-switch. Single-user only — main.ts gates the wiring on
+     *  `requirePrincipal !== true` (the file basement has no tenant isolation → multi-tenant stays dark). */
     memoryEngineEnabled: boolean;
+    /** Memory-engine config root override (env `MEMORY_ENGINE_DIR`). Unset → core's
+     *  `resolveMemoryEngineRoot` default chain (`AGENT_DATA_DIR` env → `~/.ai-agent`). */
     memoryEngineDir?: string;
+    /** N0 (夜测 2026-07-09) remote-lane plane-split override (env `MEMORY_ENGINE_REMOTE_LANE=allow`). The file
+     *  memory engine materializes/harvests on the WORKER's local fs, while a remote exec lane (e2b/k8s/ssh/adb/
+     *  local-docker) routes the model's file tools to the SANDBOX fs — the two planes never meet (sandbox writes
+     *  are never harvested; the injected memory instructions just burn failing turns). Default: a remote lane
+     *  forces memory DARK (fail-closed). `allow` re-enables it for operators whose lane genuinely shares the
+     *  worker fs (e.g. ssh to a host on the same NFS mount). */
     memoryEngineRemoteLaneAllowed: boolean;
+    /** The single-user deployment's one memory scope name (env MEMORY_SCOPE; default "local" under
+     *  single-user). Feeds `spec.memory.scope` — the new engine consumes the same normalized scopes. */
     memoryScope?: string;
+    /** 142-S2.5-W1: TOC 同步 client 腿 —— file memory 形态把本地记忆盘与中心(DB 权威,
+     *  POST /v1/memory/sync/:scope)做一轮一 RTT 双向同步。env 三键:`MEMORY_SYNC_URL`(设了=开;缺省
+     *  undefined=纯本地现状零变化)/`MEMORY_SYNC_TOKEN`(Bearer)/`MEMORY_SYNC_SCOPE`(可选,缺省=
+     *  formatUserScope(memoryScope);已是 v2 typed key 则原样直通,见 loadConfig)。半配置 fail-loud
+     *  (memoryEngineBackend 同款姿势);DB backend(pg/tidb)配了这些键=boot throw(中心侧自己就是
+     *  同步权威,不该再跑 client 腿)。 */
     memorySync?: {
         url: string;
         token: string;
@@ -66,6 +191,13 @@ export interface ServiceConfig {
         maxPushEntries?: number;
         maxPullEntries?: number;
     };
+    /** design/48 v1b + design/61: opt-in remote execution backend (PEER adapters, chosen by REMOTE_EXEC). Unset
+     *  (OA/review deployments) → in-process stub env, zero behavior change. Secrets (apiKey/privateKey) ONLY from env.
+     *   - `e2b`  → per-task E2B Firecracker VM (isolated, suspendable). The default code-agent worker.
+     *   - `k8s`  → per-task Kata pod on our k3s (isolated, NOT suspendable — no managed memory
+     *              snapshot). Self-hosted sandbox lane; auth = explicit K8S_* env or in-cluster service account.
+     *   - `ssh`  → a real host over SSH (NOT isolated/suspendable; design/61 §5). AI-orchestrated batch deploy.
+     *   - `adb`  → a real device over ADB (NOT isolated/suspendable). On-device APP testing. */
     remoteExec?: {
         provider: "e2b";
         apiKey: string;
@@ -86,6 +218,7 @@ export interface ServiceConfig {
         runtimeClass?: string;
         mountPath?: string;
         timeoutMs?: number;
+        /** Resource-profile knobs: sandbox pod limits (adapter defaults: 2Gi / 1 cpu). */
         memory?: string;
         cpu?: string;
         s3Snapshot?: {
@@ -127,11 +260,25 @@ export interface ServiceConfig {
         commandTimeoutMs?: number;
         env?: Record<string, string>;
     };
+    /**
+     * SVC-3 git-WORKTREE ISOLATION (design/97 CORE-6). Opt-in (WORKTREE_ISOLATION_ENABLED + WORKTREE_REPO_ROOT).
+     * When set, the deployment's `executionEnvFactory` is wrapped so an agent core marks `isolation:"worktree"`
+     * (via the TRUSTED RunInternals — never a TaskSpec) runs in its OWN detached git worktree under `repoRoot`.
+     * Operator-supplied ONLY (never a task input). v1 covers the `host` lane (the TOC fan-out lane); other lanes
+     * pass through unwrapped (a worktree-rooted REMOTE env is a follow-on). See plugins/worktree-isolation.ts.
+     */
     worktreeIsolation?: {
+        /** Operator-trusted base repo root where `git worktree add/remove/prune` run. Absolute, a git repo. */
         repoRoot: string;
+        /** Operator-trusted allowlist of permitted roots; `repoRoot` must be within one (defence in depth).
+         *  Default `[repoRoot]`. */
         allowedRoots?: string[];
+        /** Base commit/ref for every worktree (default core's `HEAD` at creation time). */
         commit?: string;
     };
+    /** MCP servers from sema-registry (`/effective.mcp`), resolved at startup (env-NAME refs → values) and
+     *  filtered per scenario in `resolveSpec`. Not env-derived — populated by the sema-registry adapter when
+     *  present (restart-to-apply, like models/roles); undefined = no center MCP (scenarios use no MCP). */
     mcpServers?: ScopedMcpServer[];
     tidb?: {
         host: string;
@@ -141,9 +288,27 @@ export interface ServiceConfig {
         database: string;
         connectionLimit?: number;
     };
+    /** Which SQL engine the durable stores run on (clay 2026-06-21 PG migration; 2026-07-06 wording: canonical
+     *  value is `mysql` = any MySQL-protocol server — MySQL, TiDB, MariaDB — over the same mysql2 pool; the env
+     *  value `tidb` is a back-compat alias normalized to `mysql` at parse). `mysql` reads the `tidb`-named
+     *  connection coords above (MYSQL_* env preferred, TIDB_* accepted); `pg` (PostgreSQL dialect) reads `pg`
+     *  below. A subsystem that selects a DB backend (sessionBackend === "tidb", read as "the SQL DB") then
+     *  runs on the engine `dbBackend` picks. TiDB is fully supported (any MySQL-protocol engine works —
+     *  memory no longer needs a VECTOR column since design/138 moved it onto the file engine). Env: DB_BACKEND. */
     dbBackend: "mysql" | "pg" | "local" | "memory";
+    /** clay 拍(2026-07-27):operator 是否显式设了 DB_BACKEND。main.ts 的降级判据——**默认推导**的
+     *  local(裸 boot)在 mkdir/ensure 失败时降级 memory + warn + gauge(auto-DB 不可达先例);
+     *  **显式** DB_BACKEND=local 失败仍 fail-loud(operator 要了 durable,静默丢=丢数据)。 */
     dbBackendExplicit: boolean;
+    /** Data root for the file-backed `local` StoreBackend (clay 2026-06-26 P0.5 variant-2): the dir core's
+     *  `FileStorageBackend` opens (sessions/memory/policy/snapshots) so a locally-run HTTP service's sessions
+     *  SURVIVE a process restart + the resume picker is restart-visible. Resolved from `LOCAL_DATA_ROOT ??
+     *  AGENT_DATA_DIR ?? ~/.ai-agent` — the SAME root main.ts:102 + run-local.ts:198 resolve, so the HTTP
+     *  service and a run-local on the same box agree on one data dir (boot-locked single-instance). Only the
+     *  `local` backend reads it. */
     localDataRoot?: string;
+    /** PostgreSQL connection (used iff dbBackend === "pg"). Mirror of `tidb`. Env: PG_HOST/PG_PORT/PG_USER/
+     *  PG_PASSWORD/PG_DATABASE/PG_POOL_SIZE. */
     pg?: {
         host: string;
         port: number;
@@ -152,7 +317,20 @@ export interface ServiceConfig {
         database: string;
         connectionLimit?: number;
     };
+    /** S9 deeper fix (SILENT-FALLBACK): per-query DB timeout in ms — a DB-side stall must surface as a rejected
+     *  query (which the S9 flush-streak / stalled-watchdog telemetry already counts), not an unbounded hang.
+     *  Scope differs by engine (native support): on `pg` it is POOL-WIDE (`statement_timeout` server-side cancel +
+     *  `query_timeout` client-side backstop — see pgPoolOptions); on `mysql` mysql2 has NO pool-level knob, so it
+     *  overrides only the write-behind counter family's per-query timeout (the S9 pain face; default 30s there even
+     *  when this is unset). Unset = pool-wide OFF (byte-compat: legit heavyweight statements — boot DDL, ≤64 MiB
+     *  snapshot-blob rows — make a universal default unsafe). Env: DB_QUERY_TIMEOUT_MS (soft knob, S20 warn-on-typo). */
     dbQueryTimeoutMs?: number;
+    /** Object-store offload for the E19/2c file-snapshot BLOBS (clay 2026-06-26). The conversation TRANSCRIPT stays
+     *  DB-first; ONLY the snapshot BYTES (binary file content, up to ~64 MiB/file — a perf-suboptimal TiDB blob row) move
+     *  to MinIO. The snapshot MANIFEST (relPath→hash) STAYS in SQL (`snapshot_manifest`), so the transcript hot read never
+     *  touches MinIO. Built (by the tidb/pg StoreBackend) into a MinioBlobBackend iff MINIO_ENDPOINT + MINIO_ACCESS_KEY +
+     *  MINIO_SECRET_KEY are all set — else the file-snapshot stores keep the SQL `snapshot_blob` default (byte-identical to
+     *  today). Reuses the SAME MinIO env names as the k8s workspace-snapshot lane (zero remap). */
     snapshotBlobStore?: {
         endpoint: string;
         bucket: string;
@@ -162,104 +340,428 @@ export interface ServiceConfig {
         keyPrefix?: string;
         presignTtlSec?: number;
     };
+    /** (a)(clay 拍 a+c,2026-07-27)SQL 默认店的 per-blob 帽显式覆写(字节)。未设 ⇒ SqlBlobBackend
+     *  的方言默认(tidb=6MiB=TiDB 默认 txn-entry-size-limit 真库实测矮墙,pg=不设帽);设了 ⇒ 两方言
+     *  都生效(调高过 entry/packet 限的部署放宽用)。软旋钮:坏值=undefined 走默认。 */
     snapshotBlobSqlMaxBytes?: number;
+    /** (c) 的显式逃生口:云形(mysql|pg 后端)缺 MinIO 本应 boot fail-loud(bytes-in-DB 撞包墙已两役
+     *  实证,大字节归对象存储);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` 显式接受 SQL 店 + (a) 的帽
+     *  (单机/测试台形)。严格 "true" 判——这是安全姿势开关,不收宽松真值。 */
     snapshotBlobAllowSql: boolean;
+    /** plugins 域 clone host 白名单(`PLUGINS_ALLOW_HOSTS`,缺省 github.com;契约 [1361]① 双保险面,
+     *  消费在 capabilities/center-plugins.ts)。 */
     pluginsAllowHosts: string[];
+    /** 监听绑址([1934] cli 实锤:此前 `HOST` **零消费**、`listen(port)` 恒绑所有接口)。
+     *  `BIND_HOST`(兼容 `HOST`)。显式值恒生效;缺省见 {@link resolveBindHost}——**无鉴权写面
+     *  (allowUnauthedWrites 且零凭证)自动收窄到 127.0.0.1**,其余维持全接口(既有部署零影响)。 */
     bindHost?: string;
+    /** D-1 附件孤儿对象 GC 的 grace(毫秒;`ATTACHMENT_ORPHAN_GRACE_MS`,默认 1h,**0=关掉本腿**)。
+     *  复审 F10:同 tick 邻居(workflowOrphanGraceMs/attachmentUnboundTtlMs/scratchpadSweepTtlMs)都有
+     *  旋钮——存量对象巨大的部署要调慢/停掉,不该被迫取消 MinIO 配置(那会连带关掉整个附件面)。 */
     attachmentOrphanGraceMs: number;
+    /** workspace 浏览面(#3,[1894]①)单文件读上限(字节;`WORKSPACE_FILE_MAX_BYTES`,默认 8MiB)。
+     *  超限=413 结构化信封 {sizeBytes, limit} 指路 archive 口。软旋钮:坏值走默认。 */
     workspaceFileMaxBytes: number;
+    /** SendUserFile dual-track public-link issuance (design settled cross-repo 2026-07-14; S3_PUBLIC_* are
+     *  [766]② cross-repo contract names — never rename). Enabled iff the adapter-held MinIO/S3 creds are set:
+     *  `endpoint` = MINIO_ENDPOINT (the shared snapshot-lane name, wins when both are set) with S3_ENDPOINT
+     *  as the external-S3 compat alias (one address serving both internal + public faces), plus
+     *  MINIO_ACCESS_KEY + MINIO_SECRET_KEY (optional MINIO_REGION) — any of the three unset/empty ⇒ the whole
+     *  block is absent and the tool is honestly not mounted (prior behavior, fail-safe default).
+     *  `publicEndpoint` = S3_PUBLIC_ENDPOINT (falls back to S3_ENDPOINT when that is already public); absent ⇒
+     *  the tool mounts but fail-louds at issue time with the fix (never mints an internal-host link).
+     *  Buckets: S3_PUBLIC_BUCKET (default "sema-public") for the permanent track — its anonymous policy MUST
+     *  be GetObject-only (`mc anonymous set-json`, NOT `set download` which also enables ListBucket and lets
+     *  the unguessable-key capability URLs be enumerated); the private presigned track shares
+     *  SESSION_SNAPSHOT_BUCKET (default "session-snapshots") under a "sendfile/" prefix.
+     *  SEND_USER_FILE_URL_TTL = default ttl seconds when the tool call omits one; 0 = permanent (the settled
+     *  default). Unset/non-integer/negative fail-SAFE to 0 — never NaN into a signature. */
     sendUserFile?: {
         endpoint: string;
         publicEndpoint?: string;
         publicBucket: string;
         privateBucket: string;
         privateKeyPrefix: string;
+        /** v2: endpoint the SANDBOX's presigned PUT is Host-bound to. Default publicEndpoint (an e2b cloud
+         *  sandbox only reaches the public face); in-cluster k8s pods may prefer the internal endpoint.
+         *  Env: SEND_USER_FILE_SANDBOX_PUT_ENDPOINT. */
         sandboxPutEndpoint?: string;
         accessKey: string;
         secretKey: string;
         region?: string;
         defaultTtlSec: number;
     };
+    /** Bearer token the service requires from callers (optional). Single-token deployment tier (one-tenant /
+     *  on-prem): authenticates, but the request's `source` stays NULL (no system identity to derive). */
     authToken?: string;
+    /** Per-SYSTEM service credentials: token → system name (`SERVICE_AUTH_TOKENS="<tok>=oa,<tok>=cc-mcp"`).
+     *  The request's `source` is DERIVED from which credential authenticated — never self-declared by the
+     *  caller — and persisted on the run row (audit / per-door value attribution). Rotation/revocation is
+     *  per system. Coexists with `authToken` during migration (that one authenticates with source=NULL). */
     authTokens: Record<string, string>;
+    /** Escape hatch for local dev: when true, task-submission endpoints (POST /v1/tasks[/stream], /v1/runs,
+     *  /v1/leader) accept requests even when no `authToken` is configured. Default false = fail-closed, so a
+     *  deploy that forgets `SERVICE_AUTH_TOKEN` REFUSES submissions (center: a worker must validate a
+     *  service-to-service token, else anything in-cluster can submit & bill directly). `ALLOW_UNAUTHED_WRITES`.
+     *  有意设计(文档化):本开关只豁免「零凭证形态」的 fail-closed 503;一旦配了凭证
+     *  (SERVICE_AUTH_TOKEN 或 TOKENS 名录),凭证必须使用——unauthed 仍 401,两 env 不叠加
+     *  (半配置绕行=后门,刻意优先级)。 */
     allowUnauthedWrites?: boolean;
+    /** Optional READ-ONLY token that ALSO authorizes GET /metrics + /metrics/summary (in addition to
+     *  authToken). Set the SAME value fleet-wide so a control plane (sema-registry) can pull every worker's
+     *  metrics with ONE token it holds — without ever holding each worker's full `authToken`. */
     metricsToken?: string;
+    /** Read-only Task Trace API token (S1). Like `metricsToken` but for GET /v1/tasks[/:id/turns|/stream] — lets
+     *  sema-registry pull worker traces fleet-wide with ONE read-only token, never holding each worker's full
+     *  `authToken`. Read-only: cannot run tasks or change config. `TRACE_TOKEN`. */
     traceToken?: string;
+    /** CORS v2(2026-07-11):`CORS_ORIGIN` 接受 CSV **白名单**。单值=v1 兼容
+     *  (无请求 Origin 也回显该值——curl/同源读者不受影响);多值=按请求 Origin 匹配回显+`Vary: Origin`
+     *  (缓存正确性),不匹配=不设 allow-origin(浏览器拒)。未设=无 CORS 面(默认关)。 */
     corsOrigins: string[];
+    /** D-1 附件上传:单文件字节上限(server 权威;缺省 32 MiB)。字节本体在对象存储(clay 裁 2026-07-27
+     *  云形必配 MinIO),故上限不是 DB 行约束而是:①上传路径整段在内存缓冲(readRawBody reject-not-OOM,
+     *  上限=单请求 RAM 束)②物化路径 env.writeFile 一次成写。32 MiB 真三方(TiDB+PG+MinIO)整程回读
+     *  实证在店套件。`ATTACHMENT_MAX_BYTES`。 */
     attachmentMaxBytes: number;
+    /** D-1 附件 mime 白名单(部署策略旋钮,`ATTACHMENT_MIME_ALLOWLIST` CSV;支持 `type/*` 通配)。
+     *  **缺省不设限**:声明 mime 是客户端自述、不可验证,不构成安全边界——真防线=尺寸上限+沙箱内消费;
+     *  设它是部署方的内容策略选择,不是安全开关(拒答带 415 + 明示允许集)。 */
     attachmentMimeAllowlist?: string[];
+    /** D-1 未绑定附件 TTL(上传后从未被任何 task 引用的行,过期由 reaper 收割;缺省 24h)。 */
     attachmentUnboundTtlMs: number;
+    /** Header carrying the authenticated principal (S6). Identity never comes from the body. */
     principalHeader: string;
+    /** Require the principal header on task requests (set true in multi-tenant production). */
     requirePrincipal: boolean;
+    /** Runtime governance "second baton" (center §10): operator autonomy mode, expanded TIGHTEN-ONLY onto each
+     *  task's TaskSpec (`read-only`/`plan` → read-only hands, `ask` → shellGate always, `auto`/unset → no extra
+     *  tightening). Per-request HOT (read live in resolveSpec); primarily sema-registry-managed, `AUTONOMY` env for
+     *  the env/local path. See runtime-governance.ts. undefined = unmanaged. */
     autonomy?: Autonomy;
+    /** Runtime governance "second baton" (center §10): per-command coarse name-level rules, compiled into a
+     *  `combinePolicies`-layered ToolPolicy on top of the deployment baseline (deny-wins, tighten-only). COARSE
+     *  filter, NOT a sandbox (sh -c/$()/pipes bypass argv[0] → fail toward ask). Per-request HOT; sourced from
+     *  sema-registry `EffectiveConfig.runtime` (structured config, not an env scalar). undefined = unmanaged. */
     commandPolicy?: CommandRule[];
+    /** Tool names that require operator approval before running (F4). Empty = no approval gate. */
     approvalRequire: string[];
+    /** Principals allowed to act as OPERATORS on the F4 approval queue (`/v1/approvals`): list ANY
+     *  owner's pending + decide (approve/deny). A non-operator principal may only LIST ITS OWN pending and
+     *  CANNOT decide (a requester approving its own high-risk op would defeat the gate). **Empty/unset =
+     *  legacy behavior** (the shared service token IS the operator boundary — back-compat). */
     operatorPrincipals: string[];
+    /** Tool names that are always denied. */
     approvalDeny: string[];
+    /** Poll interval (ms) for an approval decision. */
     approvalPollMs: number;
+    /** design/45 durable-checkpoint (core 1.67): when true (+ a TiDB pool), F4 uses durable **suspend/resume**
+     *  instead of poll-blocking — a gated tool `ask` suspends the task (status:"suspended" + checkpoint), an
+     *  operator resumes it on any replica. Default OFF → unchanged poll-policy. `DURABLE_APPROVAL=true`. */
     durableApproval: boolean;
+    /** design/80 seam #2 (preemption) / design/74 ("失败≠没做完" third state): when true (+ durable mode), the
+     *  /v1/runs durable path opts every task into core `resourceSuspend` — a budget/turns/walltime limit OR a
+     *  scheduler preempt (`POST /v1/assistant/tasks/:id/preempt`) durably SUSPENDS the task (resumable via
+     *  `POST /v1/assistant/tasks/:id/resume`) instead of FAILING. 🔴 PRECONDITION for `preemptSignal` to fire at
+     *  all (core eligibility: resourceSuspend opt-in AND a durable checkpointStore AND durable tool-results AND a
+     *  remote suspendable env — else preempt is a silent no-op). Default OFF → unchanged fail-on-limit behavior.
+     *  `RESOURCE_SUSPEND=true`. */
     resourceSuspend: boolean;
+    /** Retention TTL (seconds) stamped on a resource/preempt checkpoint's `deadline` so the durable reaper GCs an
+     *  ABANDONED (never-resumed) suspend. 0 ⇒ core default (30d, `DEFAULT_RESOURCE_SUSPEND_TTL`). A legitimate
+     *  resume happens long before this; the deadline only reaps abandonment. `RESOURCE_SUSPEND_TTL_SEC`. */
     resourceSuspendTtlSec: number;
+    /** design/80 D-E (upgrade-budget): max NORMAL gated tool calls AUTO-APPROVED per run-leg before the rest
+     *  escalate to a human — a circuit-breaker against a runaway/inflated approval loop (an AI stuck re-asking),
+     *  NOT a cap on safety asks. 0 = OFF (every gated tool asks a human — unchanged, back-compat default). Clamped
+     *  to ≤10000 (the hard ceiling). A Supervisor deployment sets this high to get "the AI auto-approves routine
+     *  asks, the human only sees the rest". `APPROVAL_AUTO_BUDGET`. */
     approvalAutoBudget: number;
+    /** design/80 D-E (inv#2 — safety asks are never budgetable): gated tools that ALWAYS require a human even when
+     *  the auto-budget is on — the "irreversible / never auto-approve" set. Subset of approvalRequire; empty = the
+     *  budget may auto-approve any required tool. (In-service every gated ask is gate.kind="human", so this set is
+     *  the ONLY way to keep an irreversible tool human-gated under an auto-budget.) `APPROVAL_NEVER_AUTO`. */
     approvalNeverAuto: string[];
+    /** design/80 D-G (HMAC = integrity, not identity; ✅ WIRED — the "SCAFFOLD, not yet wired" note here was STALE,
+     *  corrected 2026-07-25: consumed by `verifyDirectDoorProof` → `verifyApprovalHmac`, reached from the live decide
+     *  routes `http/server.ts:4796`/`:4907`): the sema-registry-managed, ROTATING key-set used to verify an
+     *  approval-decision envelope's integrity on a direct-connect door. Empty (unset `APPROVAL_HMAC_KEYS`) ⇒ D-G
+     *  inactive (BFF-minted-principal is the only /decide door — back-compat), which is why "wired but off" is the
+     *  accurate description of every stock deployment. sema-registry mints + rotates the set; the shape is
+     *  provisional (ASK-CENTER-2026-06-17). */
     approvalHmacKeys: ApprovalHmacKey[];
+    /** design/80 D-G: open the DIRECT-connect /decide door (a CLI/desktop client without the BFF). When true, this
+     *  worker is in DIRECT MODE — it REQUIRES the crypto direct-door proof (signed principal JWT + HMAC envelope) and
+     *  treats the trusted `x-agent-principal` header as UNTRUSTED (the BFF runs on a separate non-direct worker). Off
+     *  (default) ⇒ the BFF trusted-header door is byte-identical. `DIRECT_APPROVAL_DOOR=true`. */
     directApprovalDoor: boolean;
+    /** design/80 D-G: the issuer's PUBLIC JWKS (non-secret, config-projected like operatorPrincipals) the worker
+     *  verifies a direct client's principal JWT against. Empty ⇒ no trust anchor ⇒ the direct door cannot open.
+     *  `PRINCIPAL_JWT_PUBKEYS` (JSON [{kid,alg,key(PEM),status}]). */
     principalJwtPubkeys: PrincipalJwtKey[];
+    /** Expected `iss` / `aud` of a direct client's principal JWT. `PRINCIPAL_JWT_ISS` / `PRINCIPAL_JWT_AUD`. */
     principalJwtIss?: string;
     principalJwtAud?: string;
+    /** Max accepted principal-JWT lifetime (exp − now), seconds — caps the replay window past the short-lived mandate.
+     *  0 = no cap. `PRINCIPAL_JWT_MAX_TTL_SEC` (default 120). */
     principalJwtMaxTtlSec: number;
+    /** Computed: the direct door is truly active (all anchors present). Off ⇒ direct branch never runs. */
     directDoorActive: boolean;
+    /** design/80 b (item 3): the INFRA cost rates the service owns (the engine prices only LLM tokens), composed
+     *  with core's costBreakdown for the supervisor cost surface. All default 0 (= not priced, like MODEL_COST_*).
+     *  `INFRA_COST_TOOL_CALL` / `INFRA_COST_SANDBOX_SEC` / `INFRA_COST_EGRESS_GB` (micro-USD). */
     infraCostRates: InfraCostRates;
+    /** v2 leader endpoint (design/50): enable POST/GET /v1/leader. Requires an ISOLATED remote-exec backend —
+     *  REMOTE_EXEC=e2b, OR REMOTE_EXEC=k8s (Kata pod-sandbox) WITH an S3/MinIO config for the workspace-durable
+     *  snapshot/merge (main.ts:524) — + (deploy) git on the host + a durable remote with creds. Orthogonal to the
+     *  D-G direct door (auth axis) — a worker can be direct-mode + kata + leader at once. Default OFF. `LEADER_ENABLED=true`. */
     leaderEnabled: boolean;
+    /** design/68 A6 (correctness-first knob): `LEADER_FANOUT_ENABLED=false` pins the leader router to the
+     *  deterministic single route (never fans out, zero router cost). Default true (router decides). */
     leaderFanoutEnabled: boolean;
+    /** A value router (S1 verdict §6.3 cash-out, src/router/route-orchestration.ts): auto-decide per-task
+     *  orchestration — default single, escalate to the SUP prevention posture (shellGate gate) on a DETERMINISTIC
+     *  capability-danger signal (write/exec on a NON-isolated env). DEFAULT OFF (`ROUTER_ENABLED=true`): ships the
+     *  mechanism dark; enable after a live validation (the router only ever TIGHTENS via tightenTaskSpec + honors
+     *  caller-explicit modes, so enabling can't loosen any gate). */
     routerEnabled: boolean;
+    /** S8 LLM self-orchestration (design/98): mount core's `run_workflow` tool so a strong model can author a
+     *  deterministic JS orchestration script, run under the HARDENED-vm sandbox (src/orchestration/hardened-vm-runner.ts).
+     *  DEFAULT OFF (`SELF_ORCHESTRATION_ENABLED=true`). When off, core is FAIL-CLOSED (tool not mounted, prompt not
+     *  injected) — zero impact. When on: the hard runner + a CONSERVATIVE governance baseline (workflow children are
+     *  `handsReadOnly` by default) are wired into RunnerDeps; loosen deliberately via SELF_ORCHESTRATION_MODELS etc. */
     selfOrchestrationEnabled: boolean;
+    /** §4 (Fork): deployment enablement for CC `/fork` (the core `Fork` tool wire). Posture default (single-user
+     *  turnkey → ON; multi-tenant OFF); `FORK_ENABLED` overrides. 🆕 In single-user turnkey the Fork tool is mounted for
+     *  the LLM BY DEFAULT (clay 2026-07-01; per-task opt-OUT via `body.enableFork:false`); multi-tenant is honored only
+     *  with a per-principal entitlement resolver wired (core enforces `allowFork` per-principal, registry-core 0.1.47) —
+     *  else fail-closed (see enableForkFromBody). */
     forkEnabled: boolean;
+    /** observer 开闸线(core 1.270.0/1.273.0 `RuntimeCaps.allowObservers`,`=== true` 显式
+     *  opt-in、默认 OFF —— 极性与 allowWorkflows/allowFork 相反):`EXPERIMENTAL_OBSERVER_AGENTS=true` 在
+     *  **单用户部署**直开(env 基线;命名先例=CC 的 CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS
+     *  对儿)。**多租户(REQUIRE_PRINCIPAL=true)不认 env,只认 center caps 的 allowObservers 键**
+     *  (置了也只 boot warn 一次,行为零变——半配置 fail-loud)。⚠️ 非 postureOn:observer 是实验面,
+     *  core ships dark,单用户 turnkey 也不默认开 —— 只认显式 "true"。合成序见 applyObserverEnvOptIn。 */
     experimentalObserverAgents: boolean;
+    /** S8 governance baseline: the model NAMES an LLM-authored workflow script may pick (design/98 §2.5). Empty ⇒
+     *  FAIL-CLOSED (the script cannot pick a model → spawned children use the workflow's default role). NEVER the
+     *  whole catalog. `SELF_ORCHESTRATION_MODELS=a,b`. */
     selfOrchestrationModels: string[];
+    /** S8 v2 resource isolation: run the workflow script in a `worker_thread` (heap cap + terminate) instead of
+     *  in-process. Adds DoS isolation (memory-bomb / microtask-starvation) on top of the escape membrane. Default
+     *  OFF (in-process, faster). `SELF_ORCHESTRATION_WORKER_ISOLATION=true`. */
     selfOrchestrationWorkerIsolation: boolean;
+    /** SVC-1: the durable WorkflowRunStore backend for BACKGROUND workflow runs.
+     *  `file` (DEFAULT) = the crash-safe `FileWorkflowRunStore` ledger under `localDataRoot/workflows` — a
+     *  background run's record SURVIVES a restart, which is what lets the at-least-once completion notify re-derive
+     *  a run's terminal state after a crash. `memory` = the ephemeral `InMemoryWorkflowRunStore` (process-local; no
+     *  crash recovery, no notify journal) — an explicit opt-out for a single-instance/ephemeral deployment.
+     *  `WORKFLOW_RUN_STORE=file|memory`. Only consulted when SELF_ORCHESTRATION_ENABLED. */
     workflowRunStoreBackend: "auto" | "file" | "memory";
+    /** SVC-1 (adversarial-review): a workflow still `running` past this age is deemed a crash-orphan by the periodic
+     *  notify-recovery sweep (core never resumes/reaps a prior `running` row) → finalized-as-abandoned so the
+     *  originator learns it died + the journal entry stops leaking. MUST exceed the max expected workflow runtime
+     *  (the run store has no cross-replica liveness signal). Default 24h. `WORKFLOW_ORPHAN_GRACE_MS`. */
     workflowOrphanGraceMs: number;
+    /** R7 self-wake: opt-in self-wake scheduler on the single-user TOC host lane. When true (and
+     *  the host lane is single-user, `requirePrincipal:false`), a `FileSchedulerBackend` is injected into the host
+     *  `RemoteHostExecutionEnv` → `hasScheduler(env)` mounts core's CronCreate/CronDelete/CronList tools(L8 订正:CronCancel 旧名、Sleep 已撤除), and
+     *  the TOC shell `SchedulerDaemon` reads the SAME store to fire due intents. DEFAULT OFF (the model self-scheduling
+     *  is a power; multi-tenant deployments route scheduling to center, not this host daemon). `SCHEDULER_ENABLED=true`. */
     schedulerEnabled: boolean;
+    /** design/113 C4: host-lane project-memory injection (CLAUDE.md + git narrative). Default **ON** (subject to the
+     *  host-lane + single-user gate), so "open like CC" works without config. `PROJECT_MEMORY_ENABLED=false` opts out.
+     *  design/158 B4 (lens4 N8): this was `projectMemoryDisabled` — the ONE negative boolean on a ServiceConfig whose
+     *  other 16 flags are positive `*Enabled`/`*Allowed`, so every read site had to invert twice. The retired env name
+     *  `PROJECT_MEMORY_DISABLED` still works for one deprecation window (inverted, with a boot notice). */
     projectMemoryEnabled: boolean;
+    /** R7: override the shared scheduler store path. Default `SEMA_CONFIG_DIR`→`~/.sema/scheduled_tasks.json` (the
+     *  server writer + the shell daemon reader MUST agree). `SCHEDULER_STORE_PATH`. */
     schedulerStorePath?: string;
+    /** Boot config-fetch budget (ms): the remote first pull races this window — inside it, boot applies
+     *  the config synchronously (今日常态,健康中心 <300ms);过窗则 server 立即以 env/兜底起服,该次拉取
+     *  转后台,到货即触发一次刷新 tick 热应用(roster 开门/restartRequired 语义照旧)。真机实测:黑洞形
+     *  中心让同步 boot 挂 ~5.7s(SYN 重传节奏,8s fetch 超时内)——本地 TOC 用户的「启动 5 秒」就是它。
+     *  默认 1500;调大(≥8000)≈旧的全阻塞行为。`CONFIG_BOOT_FETCH_BUDGET_MS`。 */
     configBootFetchBudgetMs: number;
+    /** [1009]②/[1014]③ supportsSessionWakeup host-signal (core 1.309 ScheduleWakeup 治本位): the SHELL knows
+     *  whether a resident daemon exists to honor session wakeups — when it spawns a headless engine with none,
+     *  it sets `SCHEDULER_SESSION_WAKEUP=false` and core's ScheduleWakeup refuses up front (fail-loud) instead
+     *  of parking a wakeup that would never fire (TB background-reap族 [991]②b). Default ON (the co-resident
+     *  TOC daemon does honor its own sessions' wakeups); opt-out only — SCHEDULER_ENABLED 同门. */
     schedulerSessionWakeup: boolean;
+    /** R-survey/EnterPlanMode (core 1.167): MODEL-DRIVEN plan mode. When true, runs start with
+     *  `TaskSpec.enablePlanMode:true` but NOT `handsReadOnly` (writable-start) → core auto-mounts `enter_plan_mode`
+     *  (+ `present_plan`) so the model can self-call `enter_plan_mode` at ANY time it judges a task needs planning
+     *  (CC EnterPlanMode parity). 🆕 DEFAULT ON (clay: model-driven plan is resident — the model decides when to plan);
+     *  set `PLAN_MODE_ENABLED=false` to opt out. USER-driven plan (`body.permissionMode=plan` → enablePlanMode +
+     *  handsReadOnly, read-only from start) is unaffected/independent. */
     planModeEnabled: boolean;
+    /** SVC-2 (adversarial-review): the workflow_journal GC retention — the reaper purges journal rows older than
+     *  this (bounds the heaviest, TaskResult-bearing table; a resume older than it re-runs live). Default 7 days.
+     *  `WORKFLOW_JOURNAL_RETENTION_MS`. */
     workflowJournalRetentionMs: number;
+    /** Retention (the store never auto-purges; reap is explicit and the
+     *  deployer's job): the reaper deletes TERMINAL workflow_run rows older than this. SQL twins only (the
+     *  cross-replica backend is where unbounded growth bites; the contract has no cross-scope enumeration, so the
+     *  twins add a DISTINCT-scope sweep — the File store keeps the transcripts-like keep-everything posture).
+     *  Running rows are never reaped (that is the orphan-grace sweep's job). Default 30 days, floor 1m.
+     *  `WORKFLOW_RUN_RETENTION_MS`. */
     workflowRunRetentionMs: number;
+    /** core 1.364 durable background agents([1503] 提货单③):reaper 经 `TaskRegistry.reapDurableAgents`
+     *  (联合 reap——条件删赢了才 release 转录 session;裸 store.reap 会 strand 转录)按 scope 清 TERMINAL
+     *  `a*` 行,老于此值的删。SQL twins 走 DISTINCT-scope 枚举;local FileBackgroundAgentStore 单租户
+     *  scope="default"。Default 7 days, floor 1m。`BG_AGENT_RETENTION_MS`。 */
     backgroundAgentRetentionMs: number;
+    /** 同批:stale-running 翻转窗——running 行的写者心跳(core 60s)断更超过此值 = 宿主进程死,行翻
+     *  failed/stoppedBy=system(诚实终态,跨实例读面永不虚构存活)。core 契约要求 ≥10min(60s 心跳的
+     *  安全裕度),**下限 10min 硬钳**。Default 15min。`BG_AGENT_STALE_RUNNING_MS`。 */
     backgroundAgentStaleRunningMs: number;
+    /** core 1.382(design/153,[1561] 提货单④)`TaskRegistry.reconcileParkedAgents` 的 stale-claim 清算窗
+     *  ——core 该整块逻辑被 `opts.staleClaimMaxAgeMs !== undefined` 门住,缺席 = **整块清算永不运行**
+     *  (claim 后 claimer 进程崩死的行永久卡在"已 claim 不可再 claim"态,只能等 checkpoint TTL 自然过期;
+     *  checkpoint 已 resolved 但 finalize 未落的行——人已做出的审批决定——同样不会被诚实翻 failed)。
+     *  cli 复查([1575] F1)抓获:server 侧此前调用漏传本项,清算臂结构性不可达。Default 1h(claim→drive→
+     *  finalize 正常全链本应秒级完成,1h 是给"进程慢但仍在跑"的宽松裕度)。`BG_AGENT_PARK_CLAIM_STALE_MS`。 */
     backgroundAgentParkClaimStaleMs: number;
+    /** [1522] MED2:agent_roster 的 TTL 清理窗(core RB-23②③ 派给部署的半场——task-scoped 具名 spawn
+     *  每 run 一新行,无清理=线性无界)。按行的 recorded_at_ms(最后 upsert 触碰)删;SQL twins 扩展面,
+     *  File/Memory 店 core 自带 maxAgeMs。Default 30 days, floor 1m。`ROSTER_RETENTION_MS`。 */
     rosterRetentionMs: number;
+    /** 修8(三路复审 absorb-2):periodic scratchpad sweep TTL — the reaper removes per-session scratchpad dirs
+     *  ([820]③ ensureScratchpadDir) whose mtime is older than this (env-facts.ts `sweepStaleScratchpads`; the E21
+     *  session-DELETE purge is the primary lifecycle, this sweep is the orphan backstop). Default 7 days, floor 1m
+     *  when enabled; `SCRATCHPAD_SWEEP_TTL_MS=0`(or negative)disables the sweep entirely. */
     scratchpadSweepTtlMs: number;
+    /** RFC B5 (ENV-SELECT-AND-REGION-SOURCE 抽象点②): the deployment-region package-source selector injected into
+     *  every sandbox (`SEMA_PKG_SOURCE=cn|global|custom` — the image's pkg-source.sh hook materializes apt/pip/uv/
+     *  npm sources at start). 🆕 Default `global` (clay 拍 2026-07-13 全部以海外为准 — official endpoints ride
+     *  env-first onto EXISTING images, no rebake); CN deployments set `SANDBOX_PKG_SOURCE=cn`; `none` = inject
+     *  nothing (the pre-2026-07-13 unset behavior — byte-identical sandbox). Operator env `SANDBOX_PKG_SOURCE`;
+     *  per-region via the registry effective-config (shell B3) later. */
     sandboxPkgSource?: string;
+    /** Auto-generate a session title at first submit (one cheap-model call per
+     *  session, write-once; the user rename layer is BFF-side). Default ON; `SESSION_AUTO_TITLE=false` opts out. */
     sessionAutoTitle: boolean;
+    /** RFC A2 (clay 拍 A 切片先行): mount the model-facing `SelectEnvironment` tool (spec.tools, 判定②(a)) when
+     *  the per-task image chain is live (k8s + image catalog). Default ON; `SELECT_ENVIRONMENT_TOOL=false` opts out. */
     selectEnvironmentTool: boolean;
+    /** RFC A1: inject structured sandbox envFacts into the task (`TaskSpec.envFacts` — core 1.240.0 whitelist
+     *  field; rendered as the `# Environment` block, sanitized+bounded core-side). Default ON —
+     *  facts only ride when the deployment actually knows them (image binding/pkgSource/egress), absent = block
+     *  unchanged. `SANDBOX_ENV_FACTS=false` opts out. */
     envFactsEnabled: boolean;
+    /** ③ sensitive-path write DENY set (core 1.295 `createSensitivePathPolicy`, composed into the fs-write gate
+     *  fold on host-semantics lanes — task-settings.ts). The PATTERN SET is core's call (RECOMMENDED_SENSITIVE_PATTERNS
+     *  — .env/.ssh/keys/.git hooks+config/cloud creds/histories, rationale documented core-side); the server only
+     *  passes it through. `SENSITIVE_WRITE_PATTERNS` (comma-separated): explicitly set = FULL REPLACEMENT of the
+     *  recommended set (not a merge); `off` or an empty value = disabled (empty array); unset = core's recommended
+     *  set. Deny composes deny-wins, so a session exemption / acceptEdits auto-allow never crosses it. */
     sensitiveWritePatterns: string[];
+    /** [1557]§四 opt-in (cli[1555]② finding, core[1556] suggested mechanism): CC manual-family permission modes
+     *  (default/auto/acceptEdits) gate every fs WRITE hand tool (Write/Edit/NotebookEdit) but never touched Bash —
+     *  a model can `echo -n '…' > file` straight past the write-approval card. `MANUAL_MODE_SHELL_GATE` opts a
+     *  deployment into ALSO tightening `TaskSpec.shellGate` on those same modes (core `bashReversibilityProbe`
+     *  under `"classify"` only asks on constructively-irreversible commands — shell redirects etc.; plain reads
+     *  auto-allow). Absent/unset = `undefined` = **zero behavior change** (this is a tighten-ONLY opt-in, never a
+     *  default — a deployment must explicitly choose it); `"always"` = CC-strict parity (every Bash asks). Any
+     *  other value (incl. `"off"`) is treated as unset — this knob has no "off" value to opt BACK OUT with once a
+     *  session's baseline already tightened elsewhere (tightenTaskSpec would reject that as a loosen anyway). */
     manualModeShellGate?: "always" | "classify";
+    /** [803]④ defer face (EXPERIMENTAL, default OFF): mark the default scenario's LONG-TAIL first-party tools
+     *  (today = SelectEnvironment only) `defer:true` (core tool-disclosure: the model sees a placeholder until it
+     *  ToolSearch-loads the schema). Assessment says the win is marginal for us (spec.tools total ≈4.2k tokens, of
+     *  which Agent + the Task quartet ≈3.2k are CC-core posture = must stay inline; the deferrable tail is
+     *  ≈200-500 tokens/turn) and SendUserFile is deliberately NOT in the defer set (proactive-delivery tool —
+     *  hiding it behind ToolSearch suppresses exactly the spontaneous use it exists for). MCP tools are ALWAYS
+     *  auto-deferred by core regardless of this flag. `TOOL_DEFER_LONGTAIL=true` opts in. */
     toolDeferLongtail: boolean;
+    /** LSP code-intelligence tool (design/64 §13.1): mount core's `lsp` tool, routed to an E2B LSP sidecar. Requires
+     *  REMOTE_EXEC=e2b. Default OFF (the on-the-fly language-server install is heavy until an E2B template bakes it).
+     *  `LSP_ENABLED=true`. */
     lspEnabled: boolean;
+    /** TOC local LSP (core 1.190 `NodeLspManager`, host lane only): mount core's `lsp` tool over LOCAL `child_process`
+     *  language servers (CC `services/lsp` parity). Unlike the sandbox lane it needs NO baked template — just the
+     *  server binary on PATH, and it DEGRADES gracefully (ENOENT → grep/read) + spawns lazily/cached, so it is DEFAULT
+     *  ON for the host lane (CC-parity); set `LSP_HOST_ENABLED=false` to opt out. (`REMOTE_EXEC=host` only — ssh/adb/
+     *  local-docker can't reach a local child process to the right filesystem.)
+     *  design/158 B4 (lens4 N7): this lane used to share `LSP_ENABLED` with `lspEnabled` above — one env name driving
+     *  two OPPOSITE defaults. It now has its own knob; `LSP_ENABLED=false` remains a back-compat host opt-out (with a
+     *  boot notice naming the replacement) and `LSP_HOST_ENABLED` wins whenever it is set. */
     lspHostEnabled: boolean;
+    /** Graceful drain: how long SIGTERM waits for in-flight turns (live streams + bg/resume legs on this
+     *  instance) to finish before the hard shutdown. During drain, new billable submissions get 503+Retry-After and
+     *  /health carries `draining:true`. Default 10min (an interactive turn is minutes, not seconds — a
+     *  10s hard-cut would kill long turns); floor 10s. Env: DRAIN_GRACE_MS. SIGINT (Ctrl-C dev
+     *  ergonomics) and a SECOND SIGTERM skip the drain and hard-stop immediately. */
     drainGraceMs: number;
+    /** B3 (shell [771]②): SIGHUP idle window. SIGHUP means "the process-group owner's terminal went away" — but
+     *  under the shared-engine shape (several shell sessions on one config, engine rides the FIRST shell's process
+     *  group per the T11 anti-orphan call) other live sessions may still be using this engine, so an unconditional
+     *  drain kills a peer mid-turn (499) and 503s new submits. Instead SIGHUP arms an idle watch: shut down only
+     *  after `inflight()` (bg/resume legs + live streams) has been 0 for this long, WITHOUT flipping `draining`
+     *  (peers stay fully served). A true orphan (last window closed) self-terminates when the window expires —
+     *  T11 stands, just bounded instead of immediate. A SECOND SIGHUP (or SIGTERM) escalates to the normal drain
+     *  path. Default 120s, floor 5s. Env: SIGHUP_IDLE_GRACE_MS. */
     sighupIdleGraceMs: number;
+    /** E23 (shell-host contract): inbound MCP elicitation HITL. When enabled, the service mounts `RunnerDeps.onElicit` + the
+     *  `POST /v1/elicitations/:id/respond` route so an opted-in MCP server (`McpServerSpec.elicitation`, itself default
+     *  OFF) can ask the END USER for input mid-tool-call. LIVE-ONLY (no durable suspend; lost on crash/replica-change).
+     *  DEFAULT OFF (fail-closed): absent ⇒ `onElicit` is not wired ⇒ core advertises NO elicitation capability to any
+     *  server (doubly fail-closed with the per-server opt-in). `MCP_ELICITATION_ENABLED=true`. The throttle is the
+     *  deployment's job (core caps nothing) — bound concurrency/total/burst/TTL so an over-eager server can't flood. */
     mcpElicitation: {
         enabled: boolean;
         throttle: ElicitationThrottle;
     };
+    /** §4④: AskUserQuestion LIVE-stream HITL — mount the QuestionCoordinator on `RunnerDeps.onQuestion` + the
+     *  `POST /v1/questions/:id/respond` route so the agent's AskUserQuestion tool routes to a live human over the run's
+     *  stream (the durable-suspend leg is wired separately). A CC cap → posture-gated (single-user turnkey →
+     *  ON; multi-tenant opt-in); `ASK_QUESTION_ENABLED=true/false` overrides. */
     askQuestionEnabled: boolean;
+    /** [816]/[820]② live tool-approval HITL — mount the ToolApprovalCoordinator on `RunnerDeps.onAsk` + the
+     *  `POST /v1/tool-approvals/:id/respond` route so a policy `ask` (the fs-write gate, ask-lists, non-durable safety
+     *  asks) routes to the live human as the CC three-choice card on the run's stream (core 1.290 sync-ask leg). A CC
+     *  cap → posture-gated like askQuestion (single-user turnkey → ON; multi-tenant opt-in);
+     *  `TOOL_APPROVAL_ENABLED=true/false` overrides. Absent ⇒ core's headless auto-deny stands ([819]⑤ fail-closed). */
     toolApprovalEnabled: boolean;
+    /** [824]① (clay A 案 = workflow 权限全面 CC parity): workflow 子 agent 的默认权限基线与主 LLM 同权(base `{}`)。
+     *  安全论证:主 LLM 与子 agent 同 root 同信任域,主 LLM 本就能写这棵树([816] ask 门照管),单独钳子 agent 的
+     *  安全增益≈0(只防绕路不防直路的门不是边界);实测产品代价=[814]A 死锁。`WORKFLOW_AGENTS_READONLY=true` =
+     *  TOB 保守部署的可选旋钮:workflow 子 agent 基线加 handsReadOnly(1.190 前的旧默认)。默认 off。 */
     workflowAgentsReadOnly: boolean;
+    /** Sandbox-image-pool BAKE job API (IMAGE-API-DESIGN.md §P2): enable /v1/images/bakes* (operator-submit + the
+     *  bake-runner claim/ingest control plane). Requires a TiDB pool (the durable bake row/event/lease tables) AND
+     *  a NON-EMPTY `operatorPrincipals` (boot-asserted — never a world-writable build-host-RCE door). Default OFF.
+     *  `IMAGE_BAKES_ENABLED=true`. */
     imageBakes: ImageBakeConfig;
+    /** prove-before-scale stopgap: log every tool call (pre+post, incl. resumed legs) for diagnosis. `TOOL_TRACE=true`. Default OFF. */
     toolTrace: boolean;
+    /** Task Trace API (S1): persist the agent's reasoning/thinking into the durable run event log (for the CC-style
+     *  trace UI). Default ON; `TRACE_THINKING=false` disables capture for sensitive deployments. Redacted on persist. */
     traceThinking: boolean;
+    /** Structured log level. */
     logLevel: "debug" | "info" | "warn" | "error";
+    /** Per-principal request cap per minute on task/run endpoints. 0 disables. */
     rateLimitPerMin: number;
+    /** Operator CEILING on per-task cost (USD) / tokens (1.37 budget gate). A request may ask for a
+     *  LOWER limit but is capped to this; 0/unset = no ceiling. The review gateway sets these to stop a
+     *  single task from burning the shared cloud key. Enforced by core (failed + errorCode budget.*). */
     maxTaskCostUsd: number;
     maxTaskTokens: number;
+    /** Per-principal CUMULATIVE cost ceiling (USD) within a rolling window — blocks a tenant's NEXT task
+     *  once their accumulated spend crosses it. 0/unset = no per-principal quota. */
     maxPrincipalCostUsd: number;
+    /** Rolling window (seconds) for the per-principal cost quota. Default 86400 (1 day). */
     costQuotaWindowSec: number;
+    /** Degradation to a cheaper model `to` (a catalog name) instead of hard-failing (core 1.39/1.40):
+     *  - **prospective** (1.40, `atCostFraction`): near-budget — at `atCostFraction × maxCostUsd` switch at
+     *    the turn boundary (needs a per-task cost ceiling).
+     *  - **reactive** (1.39, `reactive`): brain-level — on `rate_limit` / `breaker_open` from the primary,
+     *    serve `to` instead (a degrading brain wrapped OUTERMOST). `downgradeOn` picks the triggers.
+     *  Unset (`MODEL_DEGRADE_TO` absent) = disabled. NOTE: pick a `to` whose gateway/account is NOT the one
+     *  being rate-limited, else reactive degrade hits the same limit. */
     degrade?: {
         to: string;
         atCostFraction: number;
@@ -267,26 +769,59 @@ export interface ServiceConfig {
         downgradeOn?: ("rate_limit" | "breaker_open")[];
         toSupportsImages: boolean;
     };
+    /** Quality-gate cascade ladder (core 1.45 `runCascade`, opt-in via `cascade:true`): catalog model
+     *  names cheapest→strongest. A task runs on the cheap rung; if it doesn't pass the gate (default =
+     *  `status==="completed"`, i.e. the cheap model failed) it escalates to the next. Empty/unset =
+     *  cascade unavailable. e.g. MODEL_CASCADE_LADDER=deepseek-flash,deepseek-pro. ⚠️ each rung is a COLD
+     *  re-run (write tools execute again) — use it for read-only / idempotent tasks. */
     cascadeLadder: string[];
+    /** Optional OTLP/HTTP metrics export (1.37 observability). When the endpoint is set, the metric
+     *  registry is periodically pushed to an OTel collector; unset = disabled (zero overhead). */
     otel?: {
         endpoint: string;
         intervalMs: number;
         serviceName: string;
         headers: Record<string, string>;
     };
+    /** Expire pending approvals older than this (seconds). 0 disables the reaper. */
     approvalTimeoutSec: number;
+    /** Background reaper interval (seconds) for stale runs / expired approvals / rate windows. */
     reapIntervalSec: number;
+    /** TTL (seconds) for offloaded tool results in the durable store. Must comfortably exceed a run's
+     *  recoverable window (a resumed run may re-fetch an old ref after a cross-replica wake); a completed
+     *  run only needs the preview. Reaped by the background reaper. Default 86400 (24h). */
     toolResultTtlSec: number;
+    /** A `running` run whose heartbeat is older than this is treated as stalled/dead. The running
+     *  instance heartbeats every 30s, so this only needs to exceed a couple of heartbeat intervals
+     *  (default 120s) — it is NOT tied to event cadence (a quiet-but-alive subagent still heartbeats). */
     runStaleSec: number;
+    /** §4 staged-import 的**每会话租约**判定为陈旧的秒数(默认 600)。Phase A 遇到超过这个时长没有活动的租约就
+     *  **接管**它 —— 这是「客户端在 Phase A 与 Phase B 之间崩掉」的自愈通道(此前那种会话到进程重启前永远
+     *  推不上云,而且没有任何客户端可调的释放动作)。租约按 entries 上传腿的活动刷新,所以大会话不会被误判。
+     *  设 0 = 关掉接管(退回旧行为:只能靠重启释放)。 */
     syncImportLeaseStaleSec: number;
+    /** Git host API base (e.g. https://git.example.com) for the read-only repo tools (code-review). */
     gitApiBaseUrl?: string;
+    /** Read-only Git host token (server-side only; never reaches the model). */
     gitApiToken?: string;
+    /** S3-TOB 设计 §1.3:memory 持久面方言(env MEMORY_ENGINE_BACKEND,缺省 file)。boot-only。 */
     memoryEngineBackend: "file" | "pg" | "tidb";
+    /** CC `workflowSizeGuideline` (advisory, injected into the Workflow tool card via
+     *  core `RunnerDeps.workflowLimits.sizeGuideline`). env WORKFLOW_SIZE_GUIDELINE; unset = absent =
+     *  byte-compat (core treats missing/unrestricted identically). boot-only (per-task card snapshot). */
     workflowSizeGuideline?: "small" | "medium" | "large" | "unrestricted";
+    /** Scenario used when a request omits `scenario`. NOTE: per-principal scenario governance does
+     *  NOT live on config — the ruling `{scenario, allowlist}` arrives per-request via center's caps view
+     *  (runtime-caps-resolver.scenarioRuling), single semantic source in center; raw assignments never hit a wire. */
     defaultScenario: string;
+    /** Directory of baked-in skill Markdown files, loaded once at startup. */
     skillsDir: string;
+    /** OA backend base URL for the `oa` scenario tools (read /api/v1, write /api/assets). */
     oaApiBaseUrl?: string;
+    /** Shared trust token forwarded to OA (= OA AGENT_SERVICE_TOKEN); OA enforces per-principal RBAC. */
     oaServiceToken?: string;
+    /** `oa` 场景的"开 Gitea issue"工具配置(OA AI 请求#5)；仅当 OA_ISSUE_TOKEN 配置时启用。token 来自 env，不入模型/日志。
+     *  上线建议：OA_ISSUE_TOKEN 用**最小权限**(仅 issue:write 的 scope)，别用全权 token。 */
     oaIssue?: {
         baseUrl: string;
         owner: string;
@@ -294,13 +829,24 @@ export interface ServiceConfig {
         token: string;
         defaultLabels?: number[];
     };
+    /** Central sema registry (sema-registry). When set, the service pulls the effective config
+     *  on boot (and refreshes) and applies it OVER the env defaults — env is the fallback. Logical config
+     *  only (model roster/roles/teams); secrets/gateways stay in this service's env.
+     *  `dryRun` (SEMA_REGISTRY_DRY_RUN=true, legacy CONFIG_CENTER_DRY_RUN): pull + LOG what the registry would change vs the env-derived
+     *  config, but do NOT apply it — a safe-rollout verification step before flipping to live.
+     *  `worker` (SEMA_REGISTRY_WORKER=<name>, legacy CONFIG_CENTER_WORKER; injected per-worker by the reconciler): scopes the pull to
+     *  that worker's roster via `/effective?worker=<name>`. Unset → the global roster (backward compatible). */
     configCenter?: {
         baseUrl: string;
         token: string;
         dryRun: boolean;
         worker?: string;
     };
+    /** Dual-mode config SOURCE (DUAL-MODE-DESIGN §4): "remote" (sema-registry HTTP) | "local" (.env + config.d
+     *  via @sema-agent/registry-core FileConfigStore) | unset → remote if SEMA_REGISTRY_URL (legacy CONFIG_CENTER_URL) is set, else pure-env.
+     *  Env: CONFIG_PROVIDER. The same resolver/EffectiveConfig either way (can't drift). */
     configProvider?: string;
+    /** Root dir holding `config.d/<domain>.json` for the local config source. Env: CONFIG_LOCAL_DIR. */
     configLocalDir?: string;
 }
 //# sourceMappingURL=config-types.d.ts.map