@sema-agent/server 1.322.0 → 2.0.0

package/dist/config.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CODE_AGENT_PROMPT, formatUserScope, isThinkingLevel, RECOMMENDED_SENSITIVE_PATTERNS } from "@sema-agent/core";
 import { ROSTER_PRIMARY_ROLES, ROSTER_CHEAP_ROLES } from "@sema-agent/registry-core";
-import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
+import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js"; // design/158 A4: the parser leaf — NOT security.js (base config layer must not value-import the 55KiB auth module)
 import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
 function csv(name) {
     return (process.env[name] ?? "")
@@ -12,6 +12,11 @@ function csv(name) {
         .filter(Boolean);
 }
 const AUTONOMY_MODES = ["read-only", "ask", "plan", "auto"];
+/** Parse the AUTONOMY env into a validated autonomy mode. Unset/empty → undefined (unmanaged → no extra
+ *  tightening). An UNKNOWN value FAILS at startup rather than silently becoming a no-op (a typo'd `AUTONOMY=readonly`
+ *  must not silently leave a deployment ungoverned — fail-loud, same discipline as numEnv). Exported so the HOT
+ *  config overlay (sema-registry.ts `applyRuntimeHot`) can re-derive the ENV BASELINE to revert to when center
+ *  stops managing `autonomy` (a stale center override must not stick — see applyRuntimeHot). */
 export function parseAutonomy(raw) {
     const v = raw?.trim();
     if (!v)
@@ -21,6 +26,9 @@ export function parseAutonomy(raw) {
     }
     return v;
 }
+/** Resolve a CSV of env-var NAMES into a {NAME: value} map from THIS process's env (out-of-band secret
+ *  forwarding into a sandbox). A name with no value set is skipped (not forwarded as undefined). The values
+ *  are secrets — they live only in the returned map (in-memory), never logged. */
 function resolveEnvForward(csvNames) {
     const out = {};
     for (const name of csvNames.split(",").map((s) => s.trim()).filter(Boolean)) {
@@ -39,14 +47,21 @@ function env(name, fallback) {
     }
     return v;
 }
+/** 出厂 skill 目录的缺省 = 包内 `skills/`(相对本模块解析),不是 cwd 相对的裸 "skills"。
+ *  真 bug(live 战役 2026-07-15 抓获):npm 全局装的 CLE 从用户 cwd 起引擎,裸 "skills" 解析到
+ *  cwd/skills(不存在)⇒ skills:0,所有烤入 skill 在 npm 分发面全空转(bench 日志 skills:0 即此)。
+ *  dist/config.js 与 skills/ 同在包根下的 ../skills;src 跑测试时 ../skills 同样是仓根 skills(一致)。
+ *  SKILLS_DIR 显式设仍覆盖此缺省;Docker(WORKDIR 包根+COPY skills)解析到 /app/skills 不破。 */
 function defaultSkillsDir() {
     try {
         return fileURLToPath(new URL("../skills", import.meta.url));
     }
     catch {
-        return "skills";
+        return "skills"; // import.meta 不可用的兜底(不应发生在 ESM 构建里)
     }
 }
+/** Two-name env with the first set winning (MYSQL_* preferred over the TIDB_* back-compat alias); throws
+ *  when neither is set and no fallback is given — same fail-loud contract as `env`. */
 function env2(primary, alias, fallback) {
     const v = process.env[primary] || process.env[alias];
     if (v === undefined || v === "") {
@@ -56,6 +71,8 @@ function env2(primary, alias, fallback) {
     }
     return v;
 }
+/** Numeric env with validation: a non-numeric value FAILS at startup instead of silently becoming `NaN`
+ *  (which e.g. slips past the `runStaleSec` liveness guard and silently disables the reaper). */
 function numEnv(name, fallback) {
     const raw = env(name, fallback);
     const n = Number(raw);
@@ -63,25 +80,51 @@ function numEnv(name, fallback) {
         throw new Error(`env ${name}="${raw}" must be a number`);
     return n;
 }
+/** Numeric env with a [min,max] bound (BL-17): an out-of-range value FAILS at startup instead of being
+ *  silently clamped/applied (e.g. a multi-hour MCP_ELICITATION_TTL_MS would silently never expire). */
 function numEnvBounded(name, fallback, min, max) {
     const n = numEnv(name, fallback);
     if (n < min || n > max)
         throw new Error(`env ${name}=${n} must be in [${min}, ${max}]`);
     return n;
 }
+/** Optional FAIL-SAFE numeric env for an OPTIONAL feature knob: a non-numeric / non-positive value yields `undefined`
+ *  (the caller falls back to its own default) rather than NaN OR a hard startup throw. Used for SESSION_SNAPSHOT_TTL_SEC
+ *  (finding 20): a typo like "600s" must NOT sign every presigned URL with X-Amz-Expires=NaN (total snapshot outage),
+ *  but ALSO must not crash boot of an unrelated subsystem — degrade to the MinioBlobBackend default. */
+/** S20 (SILENT-FALLBACK P1): soft-knob parse rejects, collected here because config parsing runs BEFORE the
+ *  logger exists. main.ts drains this once after createLogger and warns per entry ("configured X=raw is
+ *  invalid, using the default"). Module-level on purpose; drain clears it (repeat loadConfig in tests is fine). */
 const CONFIG_WARNINGS = [];
 export function drainConfigWarnings() {
     return CONFIG_WARNINGS.splice(0, CONFIG_WARNINGS.length);
 }
+/** Boot NOTICES ([792]④): non-error decisions loadConfig makes that the operator should see once (e.g. the
+ *  MODEL_PROVIDER inference below). Same pre-logger collection pattern as CONFIG_WARNINGS, but each entry
+ *  carries its own event name + fields (the warnings drain has one fixed "invalid, using default" message
+ *  which would misdescribe an inference). main.ts drains + logs right after createLogger. */
 const CONFIG_NOTICES = [];
 export function drainConfigNotices() {
     return CONFIG_NOTICES.splice(0, CONFIG_NOTICES.length);
 }
+/** F10 (codex audit): drain + log BOTH pre-logger diagnostic collectors (S20 soft-knob warnings + [792]④ boot
+ *  notices) in one place. EVERY entrypoint that calls loadConfig() then builds a logger must call this right
+ *  after (main.ts, run-local.ts) — a new entry that forgets it would silently drop operator-facing diagnostics
+ *  (run-local historically did exactly that), so the drain lives beside the collectors, not in one entrypoint. */
 export function logConfigDiagnostics(logger) {
     for (const w of drainConfigWarnings())
         logger.warn("config_env_invalid_using_default", { env: w.env, raw: w.raw });
     for (const n of drainConfigNotices())
         logger.warn(n.event, n.fields);
+    // design/158 N9 (polarity self-report): a `*_ENABLED` suffix does NOT carry its default — the repo grew four
+    // dialects for it (opt-in / opt-out / posture tri-state / negative name). Rather than force operators to read
+    // config.ts to learn what a knob does when unset, boolEnv-parsed knobs register themselves and we print one
+    // debug line per knob: name → polarity → effective value → where that value came from. `debug` is optional so
+    // an older embedder-supplied logger shape (warn-only) still compiles and still gets the warnings above.
+    // 复审 2026-07-29 #6 — the table covers a LOAD, not the catalog: five boolEnv calls sit inside conditional
+    // config shapes (E2B_ALLOW_NET only when set; K8S_INSECURE_TLS / DOCKER_DROP_CAPS only under their provider
+    // branch; MODEL_DEGRADE_REACTIVE / MODEL_DEGRADE_TO_VISION only when MODEL_DEGRADE_TO is set) and register
+    // only when that shape is active — absence of a row means "not a live knob in this config", not "off".
     if (logger.debug) {
         for (const k of configKnobTable()) {
             logger.debug("config_knob_polarity", {
@@ -94,6 +137,11 @@ export function logConfigDiagnostics(logger) {
         }
     }
 }
+/** F8 (codex audit): first NON-EMPTY env among aliased names — "" = unset, the same convention `env()` uses.
+ *  A plain `??` chain treats an EMPTY first choice as SET and shadows a configured fallback (e.g.
+ *  `ANTHROPIC_BASEURL=""` from a compose `${VAR:-}` template hiding a real `ANTHROPIC_BASE_URL`, or an empty
+ *  `ANTHROPIC_API_KEY` suppressing the whole route despite a valid `ANTHROPIC_AUTH_TOKEN`). Shared by the
+ *  MODEL_PROVIDER inference AND the anthropic route assembly so the two predicates can never drift. */
 function firstSetEnv(...names) {
     for (const n of names) {
         const v = process.env[n];
@@ -108,13 +156,18 @@ function optFinitePositiveEnv(name) {
         return undefined;
     const n = Number(raw);
     if (!(Number.isFinite(n) && n > 0)) {
-        CONFIG_WARNINGS.push({ env: name, raw });
+        CONFIG_WARNINGS.push({ env: name, raw }); // S20: previously a silent swallow — caller quietly used the default
         return undefined;
     }
     return n;
 }
+/** Keyed by canonical name so a knob read twice in one load (e.g. DURABLE_APPROVAL, once for the D-G boot
+ *  invariant and once for the returned field) registers one row, not two. Reset per `loadConfig()`. */
 const CONFIG_KNOBS = new Map();
+/** Deprecated aliases already announced for this load — the lazily-read twins (HOST_BG/HOST_EXEC_SPOOL) resolve
+ *  again on every use, and an operator does not need the same deprecation line once per command. */
 const KNOB_DEPRECATIONS_SEEN = new Set();
+/** The registered boolean knobs, sorted by name — the data behind `logConfigDiagnostics`'s polarity table. */
 export function configKnobTable() {
     return [...CONFIG_KNOBS.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -126,6 +179,7 @@ function boolEnv(name, def) {
     let value = def;
     let source = "default";
     if (raw !== undefined && raw !== "") {
+        // "" = unset, the same convention `env()`/`firstSetEnv()` use (a compose `${VAR:-}` template passes empty through).
         if (raw === "true") {
             value = true;
             source = "env";
@@ -135,12 +189,30 @@ function boolEnv(name, def) {
             source = "env";
         }
         else if (!CONFIG_KNOBS.has(name)) {
+            // Previously a silent default at every hand-written site. Guarded on first registration because a few
+            // knobs are legitimately read twice in one load (IMAGE_BAKES_ENABLED by its two boot invariants and then
+            // by the returned field; DURABLE_APPROVAL by the D-G gate and then the field) — one typo, one warning.
             CONFIG_WARNINGS.push({ env: name, raw });
         }
     }
     registerKnob({ name, polarity: def ? "opt-out" : "opt-in", value, source });
     return value;
 }
+/** design/158 N8 (D-family) — a knob whose CANONICAL name is positive (`X_ENABLED`, default ON) but which keeps
+ *  its retired negative name (`X_DISABLED`) working for one deprecation window.
+ *
+ *  Why the flip at all: `X_DISABLED !== "true"` is a double negative at the read site, so the four knobs that
+ *  used it (`PROJECT_MEMORY`, `CONFIG_LKG`, `HOST_BG`, `HOST_EXEC_SPOOL`) could not be read for their default
+ *  without inverting twice in your head, and `projectMemoryDisabled` was the ONE negative boolean on a
+ *  `ServiceConfig` that otherwise carries 16 positive `*Enabled`/`*Allowed` fields.
+ *
+ *  Resolution order (new name wins, so there is never an ambiguous both-set state):
+ *   1. `X_ENABLED` set to a literal ⇒ that.
+ *   2. `X_ENABLED` set to a non-literal ⇒ default + warning (the legacy name is NOT consulted — a typo in the
+ *      new name must not silently hand control back to the deprecated one).
+ *   3. `X_ENABLED` unset ∧ `X_DISABLED` set ⇒ the legacy site's exact contract, `X_DISABLED !== "true"`, plus a
+ *      one-shot deprecation notice naming the replacement.
+ *   4. neither ⇒ default. */
 export function boolEnvWithLegacyNegated(name, legacyNegatedName, def) {
     const raw = process.env[name];
     const legacy = process.env[legacyNegatedName];
@@ -152,13 +224,16 @@ export function boolEnvWithLegacyNegated(name, legacyNegatedName, def) {
     }
     else if (raw !== undefined && raw !== "") {
         if (!CONFIG_KNOBS.has(name)) {
+            // Same first-registration guard as boolEnv — the three consumers of this helper are the LAZILY re-read
+            // ones (remote-env-host reads per exec/probe), so an unguarded push would grow CONFIG_WARNINGS for the
+            // whole process lifetime on a single operator typo (复审 2026-07-29 #1).
             CONFIG_WARNINGS.push({ env: name, raw });
         }
         value = def;
         source = "default";
     }
     else if (legacy !== undefined && legacy !== "") {
-        value = legacy !== "true";
+        value = legacy !== "true"; // verbatim legacy contract: only the literal "true" disabled the feature
         source = "legacy-env";
         if (!KNOB_DEPRECATIONS_SEEN.has(legacyNegatedName)) {
             KNOB_DEPRECATIONS_SEEN.add(legacyNegatedName);
@@ -175,33 +250,55 @@ export function boolEnvWithLegacyNegated(name, legacyNegatedName, def) {
     registerKnob({ name, polarity: def ? "opt-out" : "opt-in", value, source, legacyName: legacyNegatedName });
     return value;
 }
+/** LKG (last-known-good) persistence of the remote effective-config fetch. Read LAZILY at both main.ts sites
+ *  rather than lifted onto `ServiceConfig`, so this stays a pure env knob; `loadConfig` pre-registers it (below)
+ *  so its polarity row and any deprecation notice appear at boot with everything else. */
 export const configLkgEnabled = () => boolEnvWithLegacyNegated("CONFIG_LKG_ENABLED", "CONFIG_LKG_DISABLED", true);
+/** The `host` exec lane's background-shell capability kill switch (read per capability probe in remote-env-host.ts). */
 export const hostBackgroundShellEnabled = () => boolEnvWithLegacyNegated("HOST_BG_ENABLED", "HOST_BG_DISABLED", true);
+/** The `host` exec lane's spool-file stdio form; false ⇒ the pre-1.226 pipe fallback (read per exec). */
 export const hostExecSpoolEnabled = () => boolEnvWithLegacyNegated("HOST_EXEC_SPOOL_ENABLED", "HOST_EXEC_SPOOL_DISABLED", true);
+/** Enum env with validation: a typo (e.g. SESSION_BACKEND=Tidb) FAILS at startup instead of being silently
+ *  cast to the union type and degrading to the default backend (dropping the persistence the operator asked for). */
 function enumEnv(name, fallback, allowed) {
     const v = (process.env[name] ?? fallback);
     if (!allowed.includes(v))
         throw new Error(`env ${name}="${v}" must be one of: ${allowed.join(", ")}`);
     return v;
 }
+/** A single HTTP header-name env: it is both read as a request header AND interpolated into the CORS
+ *  `access-control-allow-headers` list, so a value with a comma/space would split that list (and isn't a
+ *  valid header name anyway). Reject anything but header-token chars at startup (council). */
 function headerNameEnv(name, fallback) {
     const v = env(name, fallback);
     if (!/^[A-Za-z0-9_-]+$/.test(v))
         throw new Error(`env ${name}="${v}" must be a single header name ([A-Za-z0-9_-]+)`);
     return v;
 }
+/**
+ * Accept an SSH private key in whatever single-line form a secret store can hold. A PEM key is multi-line, but
+ * sema-registry's `POST /api/config/secrets` rejects newlines — so let the value arrive base64-encoded (the
+ * recommended self-serve form) or with escaped `\n`, and reconstruct the real PEM here for ssh2.
+ */
 function normalizeSshPrivateKey(raw) {
     const v = raw.trim();
     if (v.includes("BEGIN ") && v.includes("PRIVATE KEY")) {
-        return v.includes("\n") ? raw : v.replace(/\\n/g, "\n");
+        return v.includes("\n") ? raw : v.replace(/\\n/g, "\n"); // already PEM (real newlines) or escaped-\n single line
     }
     try {
-        return Buffer.from(v, "base64").toString("utf8");
+        return Buffer.from(v, "base64").toString("utf8"); // base64-of-PEM (newline-free → secrets-API friendly)
     }
     catch {
         return raw;
     }
 }
+/**
+ * Build `Model.extraBody` (core 1.60 generation-tuning passthrough) from env, or undefined when nothing
+ * is set (so a deployment that sets none is byte-for-byte unaffected). MODEL_EXTRA_BODY (raw JSON) is the
+ * general escape hatch; MODEL_FREQUENCY_PENALTY / MODEL_PRESENCE_PENALTY are typed conveniences merged on
+ * top (they win over the same key in MODEL_EXTRA_BODY). Throws on malformed JSON — fail loud at boot, not
+ * a silently-ignored tuning knob.
+ */
 function buildExtraBody() {
     const body = {};
     const raw = process.env.MODEL_EXTRA_BODY;
@@ -226,6 +323,10 @@ function buildExtraBody() {
         body.presence_penalty = Number(pp);
     return Object.keys(body).length > 0 ? body : undefined;
 }
+/** [818]① 1M dual-window derivation (core 1.289 `Model.autoCompactTokens`): an EXPLICIT positive value wins
+ *  (a center roster may declare its own); else contextWindow>=1e6 derives the CC-aligned 967000; else the field
+ *  is REMOVED (a spread-inherited value from a bigger-window base model would mis-trigger a small window).
+ *  Shared by the env lane (main + cheap models) and the center lane (sema-registry toModel). */
 export function applyAutoCompactWindow(m, explicit) {
     const target = m;
     if (explicit !== undefined && Number.isFinite(explicit) && explicit > 0) {
@@ -238,14 +339,27 @@ export function applyAutoCompactWindow(m, explicit) {
         delete target.autoCompactTokens;
 }
 export function loadConfig() {
-    CONFIG_WARNINGS.length = 0;
+    CONFIG_WARNINGS.length = 0; // repeated loadConfig() calls (test setup) must not accumulate stale warnings
     CONFIG_NOTICES.length = 0;
-    CONFIG_KNOBS.clear();
+    CONFIG_KNOBS.clear(); // the polarity table describes THIS load, never a previous one's env
     KNOB_DEPRECATIONS_SEEN.clear();
+    // npm 卫生纪律:默认值不烤内网坐标 — localhost 占位(公开分发正确缺省);真网关一律显式 env。
     const gatewayBaseUrl = env("MODEL_GATEWAY_BASEURL", "http://127.0.0.1:8000/v1");
     const modelId = env("MODEL_ID", "Qwen3.5-35B");
+    // Posture gate: single-user turnkey (`REQUIRE_PRINCIPAL !== "true"` = one trusted super-admin on their own
+    // box/tenant, CC's trust model) ⇒ the CC capability set defaults ON, each composed with its infra prereq; multi-tenant
+    // (requirePrincipal) stays opt-in (gated + secured). This is the SAME discriminator LSP's host-default-ON uses,
+    // generalized into one posture switch (the PM's "not per-flag" ask). In `postureOn`, an explicit `X_ENABLED=true/false`
+    // ALWAYS wins; else the default = single-user ∧ infra-ready. 🔒 Multi-tenant (prod) is UNAFFECTED (postureOn → false).
+    // Parsed ONCE here (design/158 B4) instead of re-comparing `process.env.REQUIRE_PRINCIPAL` at the four sites
+    // that needed it — two of which spelled it `!== "true"` and two `=== "true"`, i.e. the same knob read in both
+    // polarities within one function. `boolEnv(x, false)` is value-identical to the old `=== "true"`.
     const requirePrincipal = boolEnv("REQUIRE_PRINCIPAL", false);
     const singleUserTurnkey = !requirePrincipal;
+    // `postureOn` takes the NAME (not the pre-read value) so the knob can register itself in the polarity table —
+    // the posture family is precisely the one whose default is NOT readable from its name, so leaving it out of the
+    // self-report would omit the worst offenders. Its tri-state semantics are unchanged: an explicit literal wins,
+    // anything else (including a typo — deliberately NOT warned here, unlike boolEnv) falls to the posture default.
     const postureOn = (name, infraReady = true) => {
         const envVal = process.env[name];
         const explicit = envVal === "true" ? true : envVal === "false" ? false : undefined;
@@ -253,7 +367,24 @@ export function loadConfig() {
         registerKnob({ name, polarity: "posture", value, source: explicit === undefined ? "posture" : "env" });
         return value;
     };
+    // `local` (clay 2026-06-25 seamless local↔cloud) = the DB-less in-memory/file StoreBackend, so a locally-run HTTP
+    // service serves the same contract a cloud worker does. It has no SQL host/coords (createStoreBackend builds it
+    // without tidb/pg), so it's always "reachable". (Parsed FIRST so the session/memory posture defaults below can
+    // key off the chosen engine.) Wording (clay 2026-07-06): canonical value `mysql` = any MySQL-protocol server
+    // (MySQL / TiDB / MariaDB); `tidb` accepted as a back-compat alias. TiDB stays fully supported and is the
+    // recommended MySQL-protocol engine when semantic memory is on (native VECTOR(dim) recall).
+    // clay 拍(2026-07-27,[1845] 桌面撞 501 案后):**裸 boot 默认 durable(local file 店)**。
+    // 旧默认「纯内存」让每个宿主(cli fixture/桌面/web BFF)都要手工记得 DB_BACKEND=local,漏设 =
+    // 「跑完的任务重启就丢 + durable runs 面 501」——单机是主流形,直觉预期是留得住。三态:
+    //  - 未设 ⇒ local(单用户形;多租户例外见下)。默认推导的 local 在 main.ts 侧 mkdir/ensure 失败
+    //    时**降级 memory + warn + gauge**(auto-DB 不可达先例),显式 DB_BACKEND=local 才 fail-loud。
+    //  - DB_BACKEND=memory ⇒ 显式纯内存 opt-out(CI/临时 server「不留盘上残余」的出口)。
+    //  - 多租户裸 boot(REQUIRE_PRINCIPAL=true 且未设)⇒ 保持 memory + notice:local 与多租户互斥
+    //    (main.ts 硬拒,owner map 无租户隔离),默认不得把多租户裸 boot 变成拒启。
     const dbBackendSet = !!process.env.DB_BACKEND;
+    // 「裸 boot」判定必须**无任何 SQL 信号**才成立——SESSION_BACKEND=mysql/auto 或 TIDB/MYSQL/PG coords
+    // 在场时,dbBackend 的旧默认 "mysql" 是**引擎选择器**(auto 探测/coords 构建都 key 它),默认切
+    // local 会把这些既有形错切到文件店(回归钉在 config-coverage)。
     const sqlSignal = (!!process.env.SESSION_BACKEND && process.env.SESSION_BACKEND !== "memory") ||
         !!(process.env.TIDB_HOST || process.env.MYSQL_HOST || process.env.PG_HOST);
     const bareBoot = !dbBackendSet && !sqlSignal;
@@ -268,21 +399,48 @@ export function loadConfig() {
             },
         });
     }
+    // Asymmetry收编 (clay 2026-07-06, overseas-pilot pit #1): an EXPLICIT `DB_BACKEND=mysql/tidb/pg` is the operator
+    // asking for a durable SQL deployment — default sessions onto it (fail-fast, same as an explicit
+    // SESSION_BACKEND=mysql) instead of silently keeping the in-memory default ("DB_BACKEND=pg engaged nothing,
+    // session:memory, PG 0 tables"). DB_BACKEND=local keeps its own coercion in main.ts (it needs the built
+    // backend); an UNSET DB_BACKEND keeps the memory default (no surprise DB requirement on a bare boot).
+    // `mysql` is accepted as an alias of the internal durable label `tidb` (see ServiceConfig.sessionBackend).
     const sqlEngineExplicit = !!process.env.DB_BACKEND && dbBackend !== "local" && dbBackend !== "memory";
     const sessionBackendRaw = enumEnv("SESSION_BACKEND", sqlEngineExplicit ? "mysql" : "memory", ["memory", "mysql", "tidb", "auto"]);
     const sessionBackend = sessionBackendRaw === "mysql" ? "tidb" : sessionBackendRaw;
+    // design/138 S1 (clay 2026-07-08): long-term memory = the injection-first file-based memory ENGINE
+    // (core RunnerDeps.memoryBackend), default ON with MEMORY_ENGINE=off as the explicit kill-switch.
+    // The legacy MEMORY_BACKEND/EMBEDDING_* store plane was dropped without migration (those env vars are
+    // no longer read). Single-user gating lives in main.ts (the engine is never wired multi-tenant).
     const memoryEngineEnabled = process.env.MEMORY_ENGINE !== "off";
+    // S3-TOB(边界重切后的 backend 选择,设计 §1.3):记忆持久面方言。缺省 file=现状零变化;
+    // pg/tidb=DB 真身(零卷主档)——多租户点亮的唯一门(显式 opt-in,复审 F5:绝不静默翻转)。
     const memoryEngineBackendRaw = process.env.MEMORY_ENGINE_BACKEND ?? "file";
     if (!["file", "pg", "tidb"].includes(memoryEngineBackendRaw)) {
         throw new Error(`MEMORY_ENGINE_BACKEND must be file|pg|tidb, got "${memoryEngineBackendRaw}"`);
     }
     const memoryEngineBackend = memoryEngineBackendRaw;
+    // workflowSizeGuideline: CC normalizes unknown→unrestricted (lenient), but an env knob typo
+    // silently degrading to "no guidance" is the half-config trap — fail-loud here (memoryEngineBackend
+    // posture; the ADVISORY nature is core's concern, the env spelling is ours).
     const workflowSizeGuidelineRaw = process.env.WORKFLOW_SIZE_GUIDELINE;
     if (workflowSizeGuidelineRaw !== undefined && !["small", "medium", "large", "unrestricted"].includes(workflowSizeGuidelineRaw)) {
         throw new Error(`WORKFLOW_SIZE_GUIDELINE must be small|medium|large|unrestricted, got "${workflowSizeGuidelineRaw}"`);
     }
     const workflowSizeGuideline = workflowSizeGuidelineRaw;
+    // Single-user memory scope (hoisted from the config literal so the sync-scope default below can consume it):
+    // explicit MEMORY_SCOPE always wins; default "local" only when the engine is on AND single-user (see the
+    // literal-site comment on why multi-tenant/engine-off must stay undefined = memory dark).
     const memoryScope = process.env.MEMORY_SCOPE ?? (memoryEngineEnabled && !requirePrincipal ? "local" : undefined);
+    // 142-S2.5-W1: TOC 同步 client 腿的三键(file memory 形态专用)。MEMORY_SYNC_URL 设了=开;
+    // 缺省 undefined=纯本地现状零变化。半配置 fail-loud(memoryEngineBackend 同款姿势,绝不静默降级):
+    //  - URL 有 TOKEN 无 ⇒ throw(中心同步面要 Bearer,缺 token 的“开了但永远 401”是半配置陷阱);
+    //  - TOKEN/SCOPE 有 URL 无 ⇒ throw(operator 显然想开同步,静默不跑=同款陷阱,对称拒启);
+    //  - DB backend(pg/tidb)配了任意同步键 ⇒ throw(中心侧自己就是 POST /v1/memory/sync/:scope 的权威,
+    //    不该再跑 client 腿——两个半场叠在一个进程是拓扑错误)。
+    // scope 缺省 = formatUserScope(memoryScope)(中心侧 owner 门的 user 盘键铸法);memoryScope 本身已是
+    // v2 typed key(user:/org:/proj:/userproj:,只可能来自 operator 显式 MEMORY_SCOPE)则原样直通——
+    // 再包一层会铸出 `user:user%3A...` 双包键(诚实偏离,报告记档)。
     const memorySyncUrl = process.env.MEMORY_SYNC_URL || undefined;
     const memorySyncToken = process.env.MEMORY_SYNC_TOKEN || undefined;
     const memorySyncScopeRaw = process.env.MEMORY_SYNC_SCOPE || undefined;
@@ -306,11 +464,32 @@ export function loadConfig() {
         }
         memorySync = { url: memorySyncUrl, token: memorySyncToken, scope, ...((v) => (v !== undefined && Number.isInteger(v) && v >= 1 ? { maxPushEntries: v } : {}))(process.env.MEMORY_SYNC_MAX_PUSH_ENTRIES !== undefined ? Number(process.env.MEMORY_SYNC_MAX_PUSH_ENTRIES) : undefined), ...((v) => (v !== undefined && Number.isInteger(v) && v >= 1 ? { maxPullEntries: v } : {}))(process.env.MEMORY_SYNC_MAX_PULL_ENTRIES !== undefined ? Number(process.env.MEMORY_SYNC_MAX_PULL_ENTRIES) : undefined) };
     }
+    // P0.5 variant-2: the file-backed `local` backend's data root. SAME resolution main.ts:102 (localRoot =
+    // CONFIG_LOCAL_DIR ?? AGENT_DATA_DIR ?? ~/.ai-agent) + run-local.ts:198, so the HTTP service + a run-local on one
+    // box open ONE boot-locked data dir. `LOCAL_DATA_ROOT` is an additional highest-priority override (the explicit
+    // "the local backend's data lives HERE" knob). Only the `local` backend consumes it (createStoreBackend), but it's
+    // always resolved (cheap, env-deterministic).
     const localDataRoot = process.env.LOCAL_DATA_ROOT || process.env.CONFIG_LOCAL_DIR || process.env.AGENT_DATA_DIR || join(homedir(), ".ai-agent");
+    // `auto` builds the DB coords only when a host is actually configured — otherwise it stays memory with no
+    // probe. (Explicit mysql always builds them so a missing host fails loudly.) `needsDb` is engine-agnostic;
+    // the connection coords are built for whichever engine `dbBackend` selects (MYSQL_* preferred, TIDB_* alias).
     const dbHostSet = dbBackend === "pg" ? !!process.env.PG_HOST : !!(process.env.MYSQL_HOST || process.env.TIDB_HOST);
     const needsTidb = sessionBackend === "tidb" || (sessionBackend === "auto" && dbHostSet);
     const needsDb = needsTidb;
-    const explicitProvider = process.env.MODEL_PROVIDER;
+    // Model.api must reflect the brain that actually serves it (routing is by provider): an "anthropic"
+    // provider runs the Anthropic brain, whose usage reports `input` EXCLUDING cached tokens. core ≥1.22
+    // normalizes the cache-hit-rate denominator per api family — a wrong api makes promptTokens too small
+    // and cacheHitRate exceed 100%. (Brains select by provider, not api, so this only fixes accounting.)
+    //
+    // Default inference ([792]④, core ruling 2026-07-14): an EXPLICIT MODEL_PROVIDER always wins (unchanged).
+    // When it is unset but the operator explicitly configured an Anthropic-protocol base URL AND a matching
+    // credential (the EXACT same `firstSetEnv` predicates the `anthropic` route assembly below uses — F8:
+    // non-empty selection, so an EMPTY first alias can't shadow a set fallback), the default is "anthropic" +
+    // a one-line boot notice — a clean-machine user pointing ANTHROPIC_BASE_URL at an Anthropic-compatible
+    // upstream must not have the model silently routed to the (unconfigured) openai gateway. Base URL alone or
+    // credential alone does NOT infer (a bare ANTHROPIC_API_KEY historically only assembles the cloud route for
+    // registry-declared anthropic models); neither present ⇒ "gateway", byte-identical to before.
+    const explicitProvider = process.env.MODEL_PROVIDER; // env() semantics: "" = unset
     const inferredAnthropicBaseUrl = firstSetEnv("ANTHROPIC_BASEURL", "ANTHROPIC_BASE_URL");
     const inferredAnthropicCred = firstSetEnv("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN");
     const provider = (() => {
@@ -329,6 +508,12 @@ export function loadConfig() {
         }
         return "gateway";
     })();
+    // Generation-tuning passthrough (core 1.60 `Model.extraBody`, merged via applyExtraBody — brain-owned
+    // keys like temperature/max_tokens ALWAYS win, core warns on collision; unset → request unchanged).
+    // frequency/presence penalty are the common case (suppress degenerate looping at the source — the
+    // prevention to core's degenerate-repetition safety net); MODEL_EXTRA_BODY is the JSON escape hatch
+    // (top_k, logit_bias, …). MUST be STATIC (stable key order per cache namespace, else the prefix cache
+    // breaks — design/9/31), so it's built once here from fixed env, never per-task.
     const extraBody = buildExtraBody();
     const thinkingDefault = (() => { const v = process.env.MODEL_DEFAULT_THINKING; return v && isThinkingLevel(v) && v !== "off" ? v : undefined; })();
     const effortLevels = (process.env.MODEL_REASONING_EFFORT_LEVELS ?? "").split(",").map((s) => s.trim()).filter((s) => isThinkingLevel(s) && s !== "off");
@@ -337,9 +522,23 @@ export function loadConfig() {
         name: modelId,
         api: provider === "anthropic" ? "anthropic-messages" : "openai-completions",
         provider,
+        // Empty so the URL is owned by the BRAIN layer: each composed brain (gateway / failover fallback /
+        // Anthropic route) supplies its own baseUrl, and the brain resolves `model.baseUrl || config.baseUrl`.
+        // A non-empty value here would override every brain to one URL — breaking failover AND the Anthropic
+        // route (it would POST to the vLLM gateway). See design/15.
         baseUrl: "",
         reasoning: env("MODEL_REASONING", "true") === "true",
+        // vision precheck: the modality list drives BOTH the `model_no_vision` 422 (main.ts resolveSpec,
+        // when body.images hits a text-only model) AND the vision flag on GET /v1/models. The env-lane default model
+        // declares vision via MODEL_VISION — DEFAULT "true" keeps the historical image-capable behavior, so set
+        // MODEL_VISION=false for a text-only model (e.g. deepseek) to make the precheck actually fire instead of letting
+        // images透传 to an opaque downstream-gateway 400. (The centralized sema-registry lane derives input from its own
+        // per-model vision flag — see sema-registry.ts.)
         input: env("MODEL_VISION", "true") === "true" ? ["text", "image"] : ["text"],
+        // Per-1M-token USD pricing (core `modelCostToPricing`: input→inputPer1M, …). Default 0 keeps the
+        // historical behavior (spend reads $0) — set MODEL_COST_* on a deploy to make `model_cost_micro_usd`
+        // + the Fleet card's costUsd real. Numbers are the gateway's contract price (e.g. the review gateway's
+        // deepseek-pro), owned by the operator — the center never stores them (design/15: secrets+billing in env).
         cost: {
             input: Number(env("MODEL_COST_INPUT", "0")),
             output: Number(env("MODEL_COST_OUTPUT", "0")),
@@ -347,73 +546,139 @@ export function loadConfig() {
             cacheWrite: Number(env("MODEL_COST_CACHE_WRITE", "0")),
         },
         contextWindow: Number(env("MODEL_CONTEXT_WINDOW", "262144")),
+        // [854]③a: env 车道缺省 4096 → 32000。4096 对 reasoning 模型太小(一次完整思考+答案都放不下,长输出
+        // 任务被腰斩;上游同类缺省 32000)。per-model clamp:缺省值不越过本 entry 自己声明的 contextWindow
+        // (操作员配了小窗口模型时,缺省输出上限不得超过窗口本身 —— env 车道 model entry 就在此装配,唯一可用
+        // 约束即 MODEL_CONTEXT_WINDOW)。显式 MODEL_MAX_TOKENS 一如既往原样生效(显式配置=操作员意图,不 clamp);
+        // catalog(config.d/models.json)与 center 车道不动(那是显式配置,BL-8 继承链读的是这里的最终值)。
         maxTokens: process.env.MODEL_MAX_TOKENS !== undefined && process.env.MODEL_MAX_TOKENS !== ""
             ? Number(env("MODEL_MAX_TOKENS"))
             : Math.min(32000, Number(env("MODEL_CONTEXT_WINDOW", "262144"))),
+        // design/123 D2 (core 1.226): structural token-estimate coefficient (chars ≈ 1 token) feeding every
+        // non-usage-anchored estimate in core (compaction trigger fallback, clearStale/trim defenses, cut-point
+        // accounting). UNSET → omit = core default 4 (byte-compatible chars/4 heuristic). CJK-heavy models
+        // (deepseek on Chinese tasks) should set 2–3 — chars/4 underestimates Chinese by 60–75%, letting the
+        // request-layer defenses pass over-window requests. optFinitePositiveEnv: a typo'd value degrades to
+        // the safe core default rather than zeroing every structural estimate (soft knob, no fail-loud boot).
         ...(optFinitePositiveEnv("MODEL_CHARS_PER_TOKEN") !== undefined ? { charsPerToken: optFinitePositiveEnv("MODEL_CHARS_PER_TOKEN") } : {}),
+        // Cache family = the BRAIN's usage semantics (design/18): the Anthropic brain reports `input`
+        // EXCLUDING cached, the openai gateway brain INCLUDES it. Declare it EXPLICITLY (core 1.23
+        // `model.params.promptCacheFamily`) instead of leaving core to INFER it from `model.api` — cleaner,
+        // and `api` stays free to mean only "wire format". core warns + clamps if it's wrong (1.23).
         params: { promptCacheFamily: provider === "anthropic" ? "input-excludes-cached" : "input-includes-cached" },
+        // design/111 L2②: defaultThinking = this model's DEFAULT tier (resolution chain `spec.thinking ?? role.thinking ??
+        // model.defaultThinking`, prepare-task). reasoningEffortLevels (openai endpoints only — Anthropic budget honors the
+        // full range) DECLARES which tiers the endpoint accepts so a higher requested tier clamps DOWN instead of 422'ing.
         ...(thinkingDefault ? { defaultThinking: thinkingDefault } : {}),
         ...(effortLevels.length > 0 && provider !== "anthropic" ? { compat: { reasoningEffortLevels: effortLevels } } : {}),
         ...(extraBody ? { extraBody } : {}),
     };
+    // 1.24 role map: a catalog + role→model so subsystems resolve a ROLE (cost tiering) instead of a hard
+    // model name. An optional cheap model on the SAME gateway (MODEL_CHEAP_ID — just a different id) serves
+    // the `subagent`+`summarize` roles, so council lenses & compaction run cheap while the lead/arbiter/team
+    // stay on the main model. Unset MODEL_CHEAP_ID → every role resolves to the main model (unchanged).
     const cheapId = process.env.MODEL_CHEAP_ID;
     const cheapModel = cheapId
         ? {
             ...model,
             id: cheapId,
             name: cheapId,
+            // vision precheck (adversarial-review finding): the cheap model must declare its OWN vision
+            // capability. Spreading `...model` inherits the MAIN model's `input` modality, so a vision-capable main +
+            // text-only cheap (e.g. MODEL_CHEAP_ID=deepseek for subagent/summarize) would advertise vision on /v1/models
+            // AND defeat the precheck (config.models[cheapId] is user-pickable via body.model) — the SAME dead-code-on-a-lane
+            // class clay caught on the env main model. MODEL_CHEAP_VISION declares it (strict "true"); UNSET → inherit the
+            // main model's input (prior behavior, no change — the documented "same gateway, just a different id" case).
             input: process.env.MODEL_CHEAP_VISION === undefined
                 ? model.input
                 : process.env.MODEL_CHEAP_VISION === "true"
                     ? ["text", "image"]
                     : ["text"],
+            // Own pricing: pricing is keyed by model id (budget.buildPricing), so without this the cheap model
+            // inherits the MAIN model's `cost` and subagent/summarize spend (council lenses, compaction) is
+            // metered at the PRO per-token price → cost metric + per-principal quota over-count. Set
+            // MODEL_CHEAP_COST_* to the real cheap price; unset → inherit the main cost (prior behavior, no change).
             cost: {
                 input: Number(process.env.MODEL_CHEAP_COST_INPUT ?? model.cost.input),
                 output: Number(process.env.MODEL_CHEAP_COST_OUTPUT ?? model.cost.output),
                 cacheRead: Number(process.env.MODEL_CHEAP_COST_CACHE_READ ?? model.cost.cacheRead),
                 cacheWrite: Number(process.env.MODEL_CHEAP_COST_CACHE_WRITE ?? model.cost.cacheWrite),
             },
+            // systematic-audit: the cheap model also inherited the MAIN model's contextWindow/maxTokens/reasoning verbatim
+            // via the `...model` spread — wrong if MODEL_CHEAP_ID points at a model with different limits/capability. Declare
+            // them per cheap (MODEL_CHEAP_*); UNSET → inherit main (the documented "same gateway, just a different id" case).
             contextWindow: process.env.MODEL_CHEAP_CONTEXT_WINDOW ? Number(process.env.MODEL_CHEAP_CONTEXT_WINDOW) : model.contextWindow,
             maxTokens: process.env.MODEL_CHEAP_MAX_TOKENS ? Number(process.env.MODEL_CHEAP_MAX_TOKENS) : model.maxTokens,
+            // design/123 D2: charsPerToken per cheap slot — the spread inherits the MAIN model's coefficient,
+            // wrong when the cheap slot is a different tokenizer family (e.g. CJK-dense deepseek cheap under an
+            // anthropic main). MODEL_CHEAP_CHARS_PER_TOKEN overrides; UNSET → inherit main (same knob family).
             ...(optFinitePositiveEnv("MODEL_CHEAP_CHARS_PER_TOKEN") !== undefined ? { charsPerToken: optFinitePositiveEnv("MODEL_CHEAP_CHARS_PER_TOKEN") } : {}),
             reasoning: process.env.MODEL_CHEAP_REASONING === undefined ? model.reasoning : process.env.MODEL_CHEAP_REASONING === "true",
         }
         : undefined;
+    // [818]① 1M dual-window (core 1.289 `Model.autoCompactTokens`, additive): a 1M-window model gets
+    // autoCompactTokens=967000 (CC's 1M special-case = the autocompact window is 1M-33000; core then triggers at
+    // 967k-33k=934k with the guard on the PHYSICAL window — the exact CC alignment core recommends embedders set).
+    // Static catalog audit for this batch: ZERO baked 1M entries exist (env lane defaults 262144; center lane
+    // inherits/declares per roster) — so this is a DERIVATION on the declared window, not a data edit: any
+    // deployment that sets MODEL_CONTEXT_WINDOW>=1e6 (or a center roster with a 1M contextWindow —
+    // sema-registry.ts applies the same helper) gets the field automatically. <1M ⇒ field ABSENT (core's plain
+    // W-33000/0.7W geometry already matches CC there).
     applyAutoCompactWindow(model);
     if (cheapModel)
-        applyAutoCompactWindow(cheapModel);
+        applyAutoCompactWindow(cheapModel); // the ...model spread must not leak the MAIN window's field onto a smaller cheap window
     const models = { default: model, [model.id]: model };
     if (cheapModel)
         models[cheapModel.id] = cheapModel;
     const cheapRef = cheapModel ? cheapModel.id : "default";
+    // M1(接入审计 2026-07-08):core verify 契约(verify.d.ts)把「verifier 必须异于 implementer」定为
+    // 🔴 部署契约——verifier 落 default(=implementer)时对抗验证者自评自批,去相关性名存实亡。
+    // `MODEL_VERIFIER=<catalog 模型 id>` 真兑现旧注释的 "operator can override"(此前只有注释没有机制);
+    // 值必须命中 catalog,typo 回落 default 并由 main.ts boot warn 曝光(连同"单模型部署未配 verifier"一起)。
     const verifierEnv = process.env.MODEL_VERIFIER;
     const verifierRef = verifierEnv && models[verifierEnv] ? verifierEnv : "default";
+    // rosterMarkerRoles 收敛(0.7 worker.model 真删同车):role→tier 的名单语义
+    // 单一来源 = registry-core 的 roster 标记常量(0.6.3 契约:ROSTER_PRIMARY_ROLES=["default","team","synthesize"],
+    // ROSTER_CHEAP_ROLES=["subagent","summarize"])——service 不再自带第二份「哪些 role 吃 cheap/primary」清单
+    // (双源并存期空转结束)。值仍指我方 catalog ref(cheap 槽未配 ⇒ cheapRef="default" 全落主模型,行为不变);
+    // `verifier` 是 service 专有 role(core verify 契约),不在 roster 标记语义内,保留显式。
     const roles = {
-        verifier: verifierRef,
+        verifier: verifierRef, // adversarial verification gate (1.44) — MODEL_VERIFIER 指异构模型,未设=default(见 boot warn)
     };
     for (const r of ROSTER_PRIMARY_ROLES)
         roles[r] = "default";
     for (const r of ROSTER_CHEAP_ROLES)
         roles[r] = cheapRef;
+    // Developer-mode role preset (core 1.43, opt-in, default-neutral): attach the de-branded
+    // CODE_AGENT_PROMPT to the named roles via RoleSpec.systemPrompt — those roles run a coding prompt
+    // (when the task doesn't supply its own systemPrompt) while every other role keeps the neutral
+    // default. `MODEL_CODE_ROLES` unset → no change. e.g. MODEL_CODE_ROLES=default,subagent.
     for (const r of csv("MODEL_CODE_ROLES")) {
         const role = r;
         const cur = roles[role];
         if (cur === undefined)
-            continue;
+            continue; // only decorate roles we actually define
+        // our role targets are model-name strings; keep an object target's fields if config ever sets one.
         roles[role] =
             typeof cur === "string"
                 ? { model: cur, systemPrompt: CODE_AGENT_PROMPT }
                 : { ...cur, systemPrompt: CODE_AGENT_PROMPT };
     }
+    // design/80 D-G: the direct-connect approval door anchors (all must be present to ACTIVATE; fail-closed).
     const directApprovalDoor = boolEnv("DIRECT_APPROVAL_DOOR", false);
     const principalJwtPubkeys = parsePrincipalJwks(process.env.PRINCIPAL_JWT_PUBKEYS);
     const principalJwtIss = process.env.PRINCIPAL_JWT_ISS || undefined;
     const principalJwtAud = process.env.PRINCIPAL_JWT_AUD || undefined;
-    const principalJwtMaxTtlSec = Math.max(0, numEnv("PRINCIPAL_JWT_MAX_TTL_SEC", "120"));
+    const principalJwtMaxTtlSec = Math.max(0, numEnv("PRINCIPAL_JWT_MAX_TTL_SEC", "120")); // 0 = no cap; default ≤120s
     const dgHmacKeys = parseApprovalHmacKeys(process.env.APPROVAL_HMAC_KEYS);
     const dgOperators = csv("OPERATOR_PRINCIPALS");
+    // 🔴 the direct-door crypto gate lives ONLY in the durable (checkpointStore) /decide branch — so DURABLE_APPROVAL
+    // is a HARD precondition. Without it, checkpointStore is undefined, that branch is skipped, and the LEGACY
+    // approvalStore /decide (trusted-header, NO crypto) becomes the live path = a full bypass (adversarial CRITICAL).
     const dgDurable = boolEnv("DURABLE_APPROVAL", false);
     const directDoorActive = directApprovalDoor && dgDurable && dgHmacKeys.length > 0 && principalJwtPubkeys.length > 0 && !!principalJwtIss && !!principalJwtAud;
+    // 🔴 boot invariant (D-G §3): a half-configured direct door is the WORST state (looks on, verifies nothing) — and
+    // an empty OPERATOR_PRINCIPALS makes isOperator() true-for-all (= cross-tenant escalation). Refuse to start.
     if (directApprovalDoor) {
         const missing = [];
         if (!dgDurable)
@@ -428,12 +693,17 @@ export function loadConfig() {
             missing.push("PRINCIPAL_JWT_AUD");
         if (dgOperators.length === 0)
             missing.push("OPERATOR_PRINCIPALS (else isOperator is true-for-all)");
+        // 🔴 F-fix (dim-6): a direct door is inherently MULTI-TENANT (per-task verified JWT principal). Without
+        // REQUIRE_PRINCIPAL=true an absent/invalid principal falls through as ANONYMOUS and the owner/quota checks
+        // degrade to the spoofable header for null-owner rows — refuse a direct door that doesn't require a principal.
         if (!requirePrincipal)
             missing.push("REQUIRE_PRINCIPAL=true (a direct door is multi-tenant; without it an absent principal is anonymous and the spoofable header governs owner/quota checks)");
         if (missing.length) {
             throw new Error(`DIRECT_APPROVAL_DOOR=true but D-G anchors are missing: ${missing.join(", ")} — refusing to start a half-open direct door (design/80 D-G boot invariant)`);
         }
     }
+    // Per-system service credentials (token → system name). Parsed HERE (not just in the return object) so the
+    // bake boot invariant below can assert the runner-credential→runnerPrincipal mapping exists.
     const authTokens = Object.fromEntries((process.env.SERVICE_AUTH_TOKENS ?? "")
         .split(",")
         .map((s) => s.trim())
@@ -441,16 +711,34 @@ export function loadConfig() {
         .map((s) => [s.slice(0, s.indexOf("=")).trim(), s.slice(s.indexOf("=") + 1).trim()])
         .filter(([tok, sys]) => tok.length > 0 && sys.length > 0));
     const bakeRunnerPrincipal = env("BAKE_RUNNER_PRINCIPAL", "system:bake-runner");
+    // 🔴 boot invariant (IMAGE-API-DESIGN.md §P2.4a): the bake door is build-host-RCE-capable, and isOperator([],p)
+    // is true-for-all — so enabling bakes with an empty OPERATOR_PRINCIPALS = a WORLD-WRITABLE RCE door. Refuse to
+    // start (never a half-open bake door). The explicit-operator gate in server.ts is the runtime twin of this.
     if (boolEnv("IMAGE_BAKES_ENABLED", false) && dgOperators.length === 0) {
         throw new Error("IMAGE_BAKES_ENABLED=true but OPERATOR_PRINCIPALS is empty — the bake door runs build.sh on the privileged build host; an empty operator set makes isOperator() true-for-all (world-writable RCE). Set OPERATOR_PRINCIPALS or disable bakes (IMAGE-API-DESIGN.md §P2.4a boot invariant)");
     }
+    // 🔴 boot invariant (IMAGE-API-DESIGN.md §P2.12 / H1): the bake-runner identity is DERIVED from its bearer
+    // credential (token-derived `source`), never a self-asserted header — so a SERVICE_AUTH_TOKENS entry whose
+    // system == BAKE_RUNNER_PRINCIPAL MUST exist, else the runner can never satisfy isRunner and the entire
+    // claim/ingest/heartbeat pipeline is silently dead. Refuse to start a bake door with no runner credential.
     if (boolEnv("IMAGE_BAKES_ENABLED", false) && !Object.values(authTokens).includes(bakeRunnerPrincipal)) {
         throw new Error(`IMAGE_BAKES_ENABLED=true but no SERVICE_AUTH_TOKENS entry maps to the runner principal '${bakeRunnerPrincipal}' — the bake-runner authenticates by its credential (token-derived source), so a '<BAKE_RUNNER_TOKEN>=${bakeRunnerPrincipal}' SERVICE_AUTH_TOKENS entry is required or claim/ingest/heartbeat all 403 (IMAGE-API-DESIGN.md §P2.12 boot invariant)`);
     }
+    // ── design/158 B4 ② — the four knobs whose canonical name went from negative to positive. Only the first
+    // lands on `ServiceConfig`; the other three are read lazily at their use sites (main.ts's LKG gate,
+    // remote-env-host's capability probe and exec path) but are resolved HERE too so that their polarity row and
+    // any legacy-alias deprecation notice are emitted once, at boot, with every other config diagnostic — an
+    // operator must not have to trigger a background shell before being told the name they set is retired.
     const projectMemoryEnabled = boolEnvWithLegacyNegated("PROJECT_MEMORY_ENABLED", "PROJECT_MEMORY_DISABLED", true);
     configLkgEnabled();
     hostBackgroundShellEnabled();
     hostExecSpoolEnabled();
+    // ── design/158 B4 ③ — LSP: one knob per lane. `LSP_ENABLED` used to drive BOTH the sandbox lane (opt-in,
+    // default OFF — it needs a baked `sema-code-lsp` template) and the host lane (opt-out, default ON — it needs
+    // nothing and degrades to grep/read), i.e. one env name with two OPPOSITE defaults and no way to silence the
+    // host lane without also naming the sandbox knob. `LSP_HOST_ENABLED` now owns the host lane; an explicit
+    // `LSP_ENABLED=false` keeps working as a host opt-out (it was the only one operators ever had) with a notice
+    // naming the replacement, and `LSP_HOST_ENABLED` always wins when set.
     const lspHostEnabled = (() => {
         const explicitHost = process.env.LSP_HOST_ENABLED;
         if (explicitHost === undefined || explicitHost === "") {
@@ -470,6 +758,12 @@ export function loadConfig() {
         gatewayBaseUrl,
         gatewayApiKey: process.env.MODEL_API_KEY,
         gatewayFallbackUrls: csv("MODEL_GATEWAY_FALLBACK_URLS"),
+        // Anthropic-compatible-ecosystem env compat (2026-07-03): the route now assembles when EITHER credential
+        // is present — `ANTHROPIC_API_KEY` (x-api-key) or `ANTHROPIC_AUTH_TOKEN` (Authorization: Bearer; many such
+        // providers accept only this). AUTH_TOKEN wins when both are set. Base URL reads the widely-adopted
+        // standard name `ANTHROPIC_BASE_URL` too — the explicit sema name (no underscore) wins on a conflict.
+        // F8: alias selection via `firstSetEnv` ("" = unset) — the SAME helper the provider inference above
+        // consumes, so an empty first alias can neither suppress the route nor shadow the fallback base URL.
         anthropic: firstSetEnv("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN")
             ? {
                 apiKey: firstSetEnv("ANTHROPIC_API_KEY"),
@@ -481,8 +775,16 @@ export function loadConfig() {
             }
             : undefined,
         resilience: {
+            // BEHAVIOR CHANGE ([880] stall-watchdog audit): connect/firstToken default ON. core's idle
+            // timer only arms AFTER the first token (bumpIdle lives in sawContentToken), so with these
+            // two off a stream that opens but never emits hangs unbounded — the one true blind spot the
+            // fleet audit found. Values follow the [880] recommendation; =0 restores off.
             connectTimeoutMs: Number(env("MODEL_CONNECT_TIMEOUT_MS", "30000")),
             firstTokenTimeoutMs: Number(env("MODEL_FIRST_TOKEN_TIMEOUT_MS", "120000")),
+            // BEHAVIOR CHANGE (CC 196 parity): mid-stream stall watchdog default ON at 5min —
+            // after output starts, 5min of zero deltas cancels the stream as a retryable [network] failure
+            // (retry/failover recovers; without it a hung gateway pins the turn until the user Escapes).
+            // MODEL_IDLE_TIMEOUT_MS=0 restores off.
             idleTimeoutMs: Number(env("MODEL_IDLE_TIMEOUT_MS", "300000")),
             circuitBreaker: boolEnv("MODEL_CIRCUIT_BREAKER", false),
             failureThreshold: Number(env("MODEL_CB_FAILURE_THRESHOLD", "5")),
@@ -490,21 +792,27 @@ export function loadConfig() {
         },
         model,
         models,
-        modelApiKeyEnv: {},
-        modelApiKeys: {},
-        modelQuotaWeights: {},
-        tiers: {},
-        projects: {},
+        modelApiKeyEnv: {}, // env path has a single gateway key; sema-registry populates per-model overrides
+        modelApiKeys: {}, // sealed-box 解封产物(内存-only 明文):env lane 恒空;applyEffective 解封填充
+        modelQuotaWeights: {}, // weight-at-burn 表:env lane 恒空(weight=1 兜底);registry apply 填充
+        tiers: {}, // 档位表:env lane 恒空(INERT);applyEffective 从 models.tierGroups 解析填充(保引用)
+        projects: {}, // 142-S4 项目登记簿:env lane 恒空(INERT);applyEffective 从 projects 域填充(保引用)
         roles,
         sessionBackend,
         sessionCacheTtlSec: Number(env("SESSION_CACHE_TTL_SEC", "300")),
-        rewindSnapshotMaxMb: optFinitePositiveEnv("REWIND_SNAPSHOT_MAX_MB"),
+        rewindSnapshotMaxMb: optFinitePositiveEnv("REWIND_SNAPSHOT_MAX_MB"), // soft knob (S20: bad value warns + default)
         memoryEngineEnabled,
         memoryEngineDir: process.env.MEMORY_ENGINE_DIR || undefined,
-        memoryEngineRemoteLaneAllowed: process.env.MEMORY_ENGINE_REMOTE_LANE === "allow",
+        memoryEngineRemoteLaneAllowed: process.env.MEMORY_ENGINE_REMOTE_LANE === "allow", // N0: fail-closed default
+        // A single-user deployment has no principal, so `memoryScopeFor` falls back to `config.memoryScope` — and if
+        // THAT were unset the resolved scope would be undefined ⇒ resolveSpec builds NO `spec.memory` ⇒ the memory
+        // engine never materializes (the "wired-not-triggered" gap a §4 real test hit on the legacy plane).
+        // Default it to "local" for single-user (REQUIRE_PRINCIPAL !== "true") so TOC local memory works out-of-the-box
+        // (CC-parity). Multi-tenant memory is DARK by design (design/138 S1: the file basement has no tenant isolation —
+        // memoryScopeFor returns undefined there). An explicit MEMORY_SCOPE always wins.
         memoryEngineBackend,
         ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}),
-        memoryScope,
+        memoryScope, // hoisted above (the 142-S2.5-W1 sync-scope default consumes it)
         ...(memorySync ? { memorySync } : {}),
         remoteExec: process.env.REMOTE_EXEC === "e2b" && process.env.E2B_API_KEY
             ? {
@@ -512,26 +820,45 @@ export function loadConfig() {
                 apiKey: process.env.E2B_API_KEY,
                 ...(process.env.E2B_TEMPLATE ? { template: process.env.E2B_TEMPLATE } : {}),
                 ...(process.env.E2B_TIMEOUT_MS ? { timeoutMs: Number(process.env.E2B_TIMEOUT_MS) } : {}),
+                // Idle/liveness bound for a command (default 120s, the hang-fix). A long SILENT build —
+                // gradle's first dependency download produces no output for minutes (gate#2 P1 finding) — looks
+                // like a hang and gets killed; raise this for workers that run such tools. Agents should still
+                // prefer background+poll, but this is the operator escape hatch.
                 ...(process.env.E2B_LIVENESS_MS ? { livenessMs: Number(process.env.E2B_LIVENESS_MS) } : {}),
                 ...(process.env.E2B_ALLOW_NET ? { allowInternetAccess: boolEnv("E2B_ALLOW_NET", true) } : {}),
+                // Out-of-band secret/config env injected sandbox-wide (OA Phase-B, design/48 §5 gap 7):
+                // E2B_SANDBOX_ENV is a CSV of THIS worker's OWN env-var NAMES to forward into the sandbox under the
+                // same name (name-only config keeps the secret in the worker's env, never in the spec/center). e.g.
+                // `E2B_SANDBOX_ENV=GIT_TOKEN` → the agent's git can auth via $GIT_TOKEN (GIT_ASKPASS / credential
+                // helper) without the token ever entering the prompt, the command string, or the durable event log.
                 ...(process.env.E2B_SANDBOX_ENV ? { sandboxEnv: resolveEnvForward(process.env.E2B_SANDBOX_ENV) } : {}),
+                // [1452]/[1454] CWD-A:workspace 根显式可配(其余四车道 *_MOUNT_PATH 早有;e2b 此前配置层
+                // 不可达,恒 /home/user)。exec/spawnBackground/fs 三腿同源消费(remote-env-e2b this.cwd)。
+                // ⚠️ 变更纪律(codex 终审 high):resume 契约只回传 snapshotId,恢复的沙箱以**当前**配置值为
+                // cwd——改此值前先 drain 挂起中的 e2b 任务,否则 resumed 任务的 exec 落新根而产物在旧根
+                // (根修=core resumeVM 契约带回 WorkspaceHandle.mountPath,已转 core)。
                 ...(process.env.E2B_MOUNT_PATH ? { mountPath: process.env.E2B_MOUNT_PATH } : {}),
             }
-            :
+            : // Kata pod sandbox on our k3s: image required; auth explicit (K8S_API_URL/K8S_TOKEN) or in-cluster SA.
                 process.env.REMOTE_EXEC === "k8s" && process.env.K8S_SANDBOX_IMAGE
                     ? {
                         provider: "k8s",
                         image: process.env.K8S_SANDBOX_IMAGE,
                         ...(process.env.K8S_API_URL ? { apiUrl: process.env.K8S_API_URL } : {}),
                         ...(process.env.K8S_TOKEN ? { token: process.env.K8S_TOKEN } : {}),
+                        // base64 to survive sema-registry's no-newline secrets API (same constraint as SSH_PRIVATE_KEY).
                         ...(process.env.K8S_CA_CERT_B64 ? { caCert: Buffer.from(process.env.K8S_CA_CERT_B64, "base64").toString("utf8") } : {}),
                         ...(boolEnv("K8S_INSECURE_TLS", false) ? { insecureTls: true } : {}),
                         ...(process.env.K8S_NAMESPACE ? { namespace: process.env.K8S_NAMESPACE } : {}),
                         ...(process.env.K8S_RUNTIME_CLASS != null ? { runtimeClass: process.env.K8S_RUNTIME_CLASS } : {}),
                         ...(process.env.K8S_MOUNT_PATH ? { mountPath: process.env.K8S_MOUNT_PATH } : {}),
                         ...(process.env.K8S_TIMEOUT_MS ? { timeoutMs: Number(process.env.K8S_TIMEOUT_MS) } : {}),
+                        // Resource profile knob (resources are profile data, not mechanism — center/service
+                        // config, never wire-hardcoded). Found live: 25-module gradle integration OOM'd the 2Gi default.
                         ...(process.env.K8S_MEMORY ? { memory: process.env.K8S_MEMORY } : {}),
                         ...(process.env.K8S_CPU ? { cpu: process.env.K8S_CPU } : {}),
+                        // Workspace-durable suspend/resume: adapter-held MinIO creds (secret minio-agent-worker);
+                        // the sandbox only ever sees a presigned URL. All three keys required to enable — else suspendable:false.
                         ...(process.env.MINIO_ENDPOINT && process.env.MINIO_ACCESS_KEY && process.env.MINIO_SECRET_KEY
                             ? {
                                 s3Snapshot: {
@@ -546,7 +873,7 @@ export function loadConfig() {
                             }
                             : {}),
                     }
-                    :
+                    : // design/61: SSH → a real host. Key from the adapter-held secret env SSH_PRIVATE_KEY (never the workspace).
                         process.env.REMOTE_EXEC === "ssh" && process.env.SSH_HOST && process.env.SSH_USER && process.env.SSH_PRIVATE_KEY
                             ? {
                                 provider: "ssh",
@@ -556,7 +883,7 @@ export function loadConfig() {
                                 ...(process.env.SSH_PORT ? { port: Number(process.env.SSH_PORT) } : {}),
                                 ...(process.env.SSH_MOUNT_PATH ? { mountPath: process.env.SSH_MOUNT_PATH } : {}),
                             }
-                            :
+                            : // design/61: ADB → a real device (serial or host:port). adb binary must be on PATH in the image.
                                 process.env.REMOTE_EXEC === "adb" && process.env.ADB_SERIAL
                                     ? {
                                         provider: "adb",
@@ -564,14 +891,18 @@ export function loadConfig() {
                                         ...(process.env.ADB_PATH ? { adbPath: process.env.ADB_PATH } : {}),
                                         ...(process.env.ADB_MOUNT_PATH ? { mountPath: process.env.ADB_MOUNT_PATH } : {}),
                                     }
-                                    :
+                                    : // DUAL-MODE §5: `host` = run on THIS machine, no container (the TOC default). No required env.
                                         process.env.REMOTE_EXEC === "host"
                                             ? {
                                                 provider: "host",
                                                 ...(process.env.HOST_WORKSPACE_BASE ? { workspaceBase: process.env.HOST_WORKSPACE_BASE } : {}),
                                                 ...(process.env.HOST_COMMAND_TIMEOUT_MS ? { commandTimeoutMs: Number(process.env.HOST_COMMAND_TIMEOUT_MS) } : {}),
                                             }
-                                            :
+                                            : // DUAL-MODE §5: `local-docker` = a per-task container on THIS machine's docker daemon (isolation:true,
+                                                // suspendable:false). DOCKER_IMAGE is REQUIRED — no docker.io default (domestic-images iron rule); a
+                                                // deployment points it at the docker.io/claybobby public pool or an in-network mirror (SWR
+                                                // deprecated). Secrets are env-NAMEs the worker resolves from its
+                                                // own process.env (DOCKER_SANDBOX_ENV, a CSV of NAMEs) — never the values in the spec/center.
                                                 process.env.REMOTE_EXEC === "local-docker" && process.env.DOCKER_IMAGE
                                                     ? {
                                                         provider: "local-docker",
@@ -589,10 +920,17 @@ export function loadConfig() {
                                                         ...(process.env.DOCKER_COMMAND_TIMEOUT_MS ? { commandTimeoutMs: Number(process.env.DOCKER_COMMAND_TIMEOUT_MS) } : {}),
                                                         ...(process.env.DOCKER_SANDBOX_ENV ? { env: resolveEnvForward(process.env.DOCKER_SANDBOX_ENV) } : {}),
                                                     }
-                                                    :
+                                                    : // TOC first-run default: in LOCAL config mode (CONFIG_PROVIDER=local — the
+                                                        // single-machine source) with no explicit REMOTE_EXEC, default to the `host` lane so "fill .env
+                                                        // and run" works without the user setting REMOTE_EXEC. Fleet/remote (CONFIG_PROVIDER≠local) keeps
+                                                        // the in-process stub default (REMOTE_EXEC unset = OA/review posture) — unchanged.
                                                         process.env.CONFIG_PROVIDER === "local"
                                                             ? { provider: "host" }
                                                             : undefined,
+        // SVC-3 git-worktree isolation: opt-in, operator-supplied ONLY. WORKTREE_REPO_ROOT is the trusted base
+        // repo; WORKTREE_ALLOWED_ROOTS (CSV) is the defence-in-depth allowlist (default = [repoRoot]);
+        // WORKTREE_BASE_COMMIT pins the worktree ref (default core HEAD). Enabled only when both the flag and the
+        // repo root are present — a half-set config stays OFF (no silent default repo).
         worktreeIsolation: boolEnv("WORKTREE_ISOLATION_ENABLED", false) && process.env.WORKTREE_REPO_ROOT
             ? {
                 repoRoot: process.env.WORKTREE_REPO_ROOT,
@@ -608,6 +946,7 @@ export function loadConfig() {
         tidb: needsDb && dbBackend === "mysql"
             ? {
                 host: env2("MYSQL_HOST", "TIDB_HOST"),
+                // default port follows the env family in use: MYSQL_HOST → 3306 (stock MySQL), TIDB_HOST → 4000 (TiDB)
                 port: Number(env2("MYSQL_PORT", "TIDB_PORT", process.env.MYSQL_HOST ? "3306" : "4000")),
                 user: env2("MYSQL_USER", "TIDB_USER"),
                 password: env2("MYSQL_PASSWORD", "TIDB_PASSWORD", ""),
@@ -627,7 +966,13 @@ export function loadConfig() {
                 connectionLimit: process.env.PG_POOL_SIZE ? Number(process.env.PG_POOL_SIZE) : undefined,
             }
             : undefined,
+        // S9 deeper fix: per-query DB timeout (see the interface doc). Soft knob — a typo degrades to the default
+        // posture (pool-wide off / counter-family 30s) with an S20 boot warning, never NaN into a driver timer.
         dbQueryTimeoutMs: optFinitePositiveEnv("DB_QUERY_TIMEOUT_MS"),
+        // E19/2c snapshot-BLOB object-store offload (clay 2026-06-26). Reuses the SAME adapter-held MinIO creds as the k8s
+        // workspace-snapshot lane (secret minio-agent-worker); all three keys required to enable, else the file-snapshot
+        // stores keep the SQL `snapshot_blob` default (byte-identical to today). Bucket = SESSION_SNAPSHOT_BUCKET (default
+        // "session-snapshots"); keyPrefix optional (default "blobs/" in MinioBlobBackend).
         snapshotBlobStore: process.env.MINIO_ENDPOINT && process.env.MINIO_ACCESS_KEY && process.env.MINIO_SECRET_KEY
             ? {
                 endpoint: process.env.MINIO_ENDPOINT,
@@ -636,15 +981,25 @@ export function loadConfig() {
                 secretKey: process.env.MINIO_SECRET_KEY,
                 ...(process.env.MINIO_REGION ? { region: process.env.MINIO_REGION } : {}),
                 ...(process.env.SESSION_SNAPSHOT_PREFIX ? { keyPrefix: process.env.SESSION_SNAPSHOT_PREFIX } : {}),
+                // Fail-SAFE parse (finding 20): a non-numeric/non-positive value → omit (the MinioBlobBackend default 3600s
+                // applies), never NaN (which would sign every URL with X-Amz-Expires=NaN → total snapshot outage).
                 ...((ttl) => (ttl !== undefined ? { presignTtlSec: ttl } : {}))(optFinitePositiveEnv("SESSION_SNAPSHOT_TTL_SEC")),
             }
             : undefined,
+        // (a+c)(clay 2026-07-27)snapshot_blob 包墙修复两旋钮——语义见 ServiceConfig 字段注释。
         snapshotBlobSqlMaxBytes: optFinitePositiveEnv("SNAPSHOT_BLOB_SQL_MAX_BYTES"),
         snapshotBlobAllowSql: boolEnv("SNAPSHOT_BLOB_ALLOW_SQL_BYTES", false),
+        // plugins 域 clone host 白名单(契约 [1361]①;缺省 github.com,逗号扩 https 镜像域)。
         pluginsAllowHosts: (process.env.PLUGINS_ALLOW_HOSTS ?? "github.com").split(",").map((h) => h.trim()).filter(Boolean),
+        // 绑址([1934]):BIND_HOST 优先,HOST 兼容(cli/桌面传的就是它);空串=未设。
         bindHost: process.env.BIND_HOST || process.env.HOST || undefined,
+        // D-1 孤儿对象 GC grace(复审 F10;0=关掉本腿,负/坏值走默认)。
         attachmentOrphanGraceMs: ((v) => (v !== undefined && Number.isFinite(v) && v >= 0 ? v : 3_600_000))(process.env.ATTACHMENT_ORPHAN_GRACE_MS !== undefined ? Number(process.env.ATTACHMENT_ORPHAN_GRACE_MS) : undefined),
+        // workspace 浏览面(#3,[1894]①)单文件读上限。
         workspaceFileMaxBytes: optFinitePositiveEnv("WORKSPACE_FILE_MAX_BYTES") ?? 8 * 1024 * 1024,
+        // SendUserFile 双轨公网直链(同三键开闸;S3_ENDPOINT 兼容位=外接 S3 场景内网/公网同址)。
+        // `||` 非 `??`(配置面自查 2026-07-14):env 惯例(env() helper 同款)空串=未设——`?? ` 会让
+        // 一个显式置空的 MINIO_ENDPOINT/S3_PUBLIC_ENDPOINT 把后备名吞掉(compose `${X:-}` 透传空串是常态)。
         sendUserFile: (process.env.MINIO_ENDPOINT || process.env.S3_ENDPOINT) && process.env.MINIO_ACCESS_KEY && process.env.MINIO_SECRET_KEY
             ? {
                 endpoint: (process.env.MINIO_ENDPOINT || process.env.S3_ENDPOINT),
@@ -658,6 +1013,7 @@ export function loadConfig() {
                 accessKey: process.env.MINIO_ACCESS_KEY,
                 secretKey: process.env.MINIO_SECRET_KEY,
                 ...(process.env.MINIO_REGION ? { region: process.env.MINIO_REGION } : {}),
+                // fail-SAFE:非法值回落 0(永久轨缺省),不 NaN 进签名。
                 defaultTtlSec: ((v) => (v !== undefined && Number.isInteger(v) && v >= 0 ? v : 0))(process.env.SEND_USER_FILE_URL_TTL !== undefined ? Number(process.env.SEND_USER_FILE_URL_TTL) : undefined),
             }
             : undefined,
@@ -674,6 +1030,8 @@ export function loadConfig() {
         attachmentUnboundTtlMs: Math.max(60_000, numEnv("ATTACHMENT_UNBOUND_TTL_MS", String(24 * 3600 * 1000))),
         principalHeader: headerNameEnv("PRINCIPAL_HEADER", "x-agent-principal"),
         requirePrincipal,
+        // Runtime governance second baton (center §10): AUTONOMY env for the env/local path; sema-registry overlays
+        // it (applyRuntimeHot). commandPolicy is structured config — sema-registry-only (no flat env scalar form).
         autonomy: parseAutonomy(process.env.AUTONOMY),
         approvalRequire: csv("APPROVAL_REQUIRE"),
         operatorPrincipals: csv("OPERATOR_PRINCIPALS"),
@@ -682,10 +1040,10 @@ export function loadConfig() {
         approvalPollMs: Number(env("APPROVAL_POLL_MS", "1500")),
         durableApproval: boolEnv("DURABLE_APPROVAL", false),
         resourceSuspend: boolEnv("RESOURCE_SUSPEND", false),
-        resourceSuspendTtlSec: Math.max(0, numEnv("RESOURCE_SUSPEND_TTL_SEC", "0")),
-        approvalAutoBudget: Math.min(10000, Math.max(0, numEnv("APPROVAL_AUTO_BUDGET", "0"))),
+        resourceSuspendTtlSec: Math.max(0, numEnv("RESOURCE_SUSPEND_TTL_SEC", "0")), // 0 ⇒ core default (30d)
+        approvalAutoBudget: Math.min(10000, Math.max(0, numEnv("APPROVAL_AUTO_BUDGET", "0"))), // clamp [0,10000]; 0 = off
         approvalNeverAuto: csv("APPROVAL_NEVER_AUTO"),
-        approvalHmacKeys: dgHmacKeys,
+        approvalHmacKeys: dgHmacKeys, // D-G: WIRED (see the field's JSDoc); empty ⇒ inactive, not unimplemented
         directApprovalDoor,
         principalJwtPubkeys,
         principalJwtIss,
@@ -699,33 +1057,39 @@ export function loadConfig() {
         },
         leaderEnabled: boolEnv("LEADER_ENABLED", false),
         leaderFanoutEnabled: boolEnv("LEADER_FANOUT_ENABLED", true),
-        routerEnabled: boolEnv("ROUTER_ENABLED", false),
-        selfOrchestrationEnabled: postureOn("SELF_ORCHESTRATION_ENABLED"),
-        forkEnabled: postureOn("FORK_ENABLED"),
-        experimentalObserverAgents: boolEnv("EXPERIMENTAL_OBSERVER_AGENTS", false),
-        schedulerEnabled: postureOn("SCHEDULER_ENABLED"),
-        projectMemoryEnabled,
-        planModeEnabled: boolEnv("PLAN_MODE_ENABLED", true),
+        routerEnabled: boolEnv("ROUTER_ENABLED", false), // A value router; default OFF (ship dark, enable after live validation)
+        selfOrchestrationEnabled: postureOn("SELF_ORCHESTRATION_ENABLED"), // posture: single-user turnkey → ON (CC local trust; sandboxed vm); multi-tenant opt-in (RCE-ish, gated)
+        forkEnabled: postureOn("FORK_ENABLED"), // §4 CC /fork posture: single-user turnkey → default-ON for the LLM; multi-tenant honored only with a per-principal entitlement resolver (core enforces allowFork, registry-core 0.1.47; enableForkFromBody)
+        experimentalObserverAgents: boolEnv("EXPERIMENTAL_OBSERVER_AGENTS", false), // observer 开闸线:显式 "true" 才开(实验面,core ships dark——非 postureOn);多租户只认 center caps,env 被忽略(applyObserverEnvOptIn boot warn)
+        schedulerEnabled: postureOn("SCHEDULER_ENABLED"), // R7 自唤醒 posture: single-user turnkey → ON (CC self-wake); multi-tenant routes to center (opt-in)
+        projectMemoryEnabled, // design/113 C4 opt-out, flipped positive in design/158 B4 (legacy PROJECT_MEMORY_DISABLED still honored)
+        planModeEnabled: boolEnv("PLAN_MODE_ENABLED", true), // EnterPlanMode (core 1.167) model-driven plan; 🆕 default ON (resident — clay), PLAN_MODE_ENABLED=false opts out
         ...(process.env.SCHEDULER_STORE_PATH ? { schedulerStorePath: process.env.SCHEDULER_STORE_PATH } : {}),
-        configBootFetchBudgetMs: Math.max(0, numEnv("CONFIG_BOOT_FETCH_BUDGET_MS", "1500")),
-        schedulerSessionWakeup: boolEnv("SCHEDULER_SESSION_WAKEUP", true),
+        configBootFetchBudgetMs: Math.max(0, numEnv("CONFIG_BOOT_FETCH_BUDGET_MS", "1500")), // boot 首拉抢答窗;过窗转后台补齐(clay 2026-07-17:本地 5s 启动=黑洞中心同步等待)
+        schedulerSessionWakeup: boolEnv("SCHEDULER_SESSION_WAKEUP", true), // [1009]② host-signal: default ON, the spawning shell opts a daemon-less engine out (PLAN_MODE_ENABLED 同形解析)
         selfOrchestrationModels: csv("SELF_ORCHESTRATION_MODELS"),
         selfOrchestrationWorkerIsolation: boolEnv("SELF_ORCHESTRATION_WORKER_ISOLATION", false),
-        workflowRunStoreBackend: enumEnv("WORKFLOW_RUN_STORE", "auto", ["auto", "file", "memory"]),
-        workflowOrphanGraceMs: Math.max(60_000, numEnv("WORKFLOW_ORPHAN_GRACE_MS", String(24 * 60 * 60 * 1000))),
-        workflowJournalRetentionMs: Math.max(60_000, numEnv("WORKFLOW_JOURNAL_RETENTION_MS", String(7 * 24 * 60 * 60 * 1000))),
-        workflowRunRetentionMs: Math.max(60_000, numEnv("WORKFLOW_RUN_RETENTION_MS", String(30 * 24 * 60 * 60 * 1000))),
-        backgroundAgentRetentionMs: Math.max(60_000, numEnv("BG_AGENT_RETENTION_MS", String(7 * 24 * 60 * 60 * 1000))),
-        backgroundAgentStaleRunningMs: Math.max(10 * 60_000, numEnv("BG_AGENT_STALE_RUNNING_MS", String(15 * 60_000))),
-        backgroundAgentParkClaimStaleMs: Math.max(60_000, numEnv("BG_AGENT_PARK_CLAIM_STALE_MS", String(60 * 60_000))),
-        rosterRetentionMs: Math.max(60_000, numEnv("ROSTER_RETENTION_MS", String(30 * 24 * 60 * 60 * 1000))),
+        workflowRunStoreBackend: enumEnv("WORKFLOW_RUN_STORE", "auto", ["auto", "file", "memory"]), // SVC-1 + P1: auto = SQL backend when present (cross-replica), else File
+        workflowOrphanGraceMs: Math.max(60_000, numEnv("WORKFLOW_ORPHAN_GRACE_MS", String(24 * 60 * 60 * 1000))), // SVC-1: 24h default, floor 1m
+        workflowJournalRetentionMs: Math.max(60_000, numEnv("WORKFLOW_JOURNAL_RETENTION_MS", String(7 * 24 * 60 * 60 * 1000))), // SVC-2: 7d default, floor 1m
+        workflowRunRetentionMs: Math.max(60_000, numEnv("WORKFLOW_RUN_RETENTION_MS", String(30 * 24 * 60 * 60 * 1000))), // 30d default, floor 1m; SQL twins only
+        backgroundAgentRetentionMs: Math.max(60_000, numEnv("BG_AGENT_RETENTION_MS", String(7 * 24 * 60 * 60 * 1000))), // core 1.364: 7d default, floor 1m
+        backgroundAgentStaleRunningMs: Math.max(10 * 60_000, numEnv("BG_AGENT_STALE_RUNNING_MS", String(15 * 60_000))), // core 契约 ≥10min 硬钳(60s 写者心跳)
+        backgroundAgentParkClaimStaleMs: Math.max(60_000, numEnv("BG_AGENT_PARK_CLAIM_STALE_MS", String(60 * 60_000))), // [1575] F1 修:default 1h,floor 1m(零/负值都不该让整块清算失活)
+        rosterRetentionMs: Math.max(60_000, numEnv("ROSTER_RETENTION_MS", String(30 * 24 * 60 * 60 * 1000))), // [1522] MED2: 30d default, floor 1m; SQL twins only
+        // 修8: scratchpad sweep TTL — 0(or negative)= disabled; enabled values floor at 1m (a sub-minute TTL would
+        // race in-flight tasks' scratchpad writes for no operational gain).
         scratchpadSweepTtlMs: ((n) => (n <= 0 ? 0 : Math.max(60_000, n)))(numEnv("SCRATCHPAD_SWEEP_TTL_MS", String(7 * 24 * 60 * 60 * 1000))),
+        // RFC B5 region package-source selector — 🆕 default `global` (clay 拍 2026-07-13 海外为准:官方源 env-first
+        // 对存量镜像即生效);国内部署显式 SANDBOX_PKG_SOURCE=cn;`none` = 完全不注入(旧 unset 行为,字节级不变)。
         ...(process.env.SANDBOX_PKG_SOURCE !== "none"
             ? { sandboxPkgSource: process.env.SANDBOX_PKG_SOURCE || "global" }
             : {}),
-        sessionAutoTitle: boolEnv("SESSION_AUTO_TITLE", true),
-        selectEnvironmentTool: boolEnv("SELECT_ENVIRONMENT_TOOL", true),
-        envFactsEnabled: boolEnv("SANDBOX_ENV_FACTS", true),
+        sessionAutoTitle: boolEnv("SESSION_AUTO_TITLE", true), // session auto-title: default ON (one cheap call per session)
+        selectEnvironmentTool: boolEnv("SELECT_ENVIRONMENT_TOOL", true), // RFC A2: default ON (mount additionally gated on k8s+catalog)
+        envFactsEnabled: boolEnv("SANDBOX_ENV_FACTS", true), // RFC A1: default ON (core 1.240.0 TaskSpec.envFacts; no-facts = no field)
+        // ③ sensitive-path write deny set: unset = core's recommended set; explicit value = full replacement
+        // (comma-separated); "off"/empty = disabled. Set curation is core's (成文 core-side); server passes through.
         sensitiveWritePatterns: ((raw) => {
             if (raw === undefined)
                 return [...RECOMMENDED_SENSITIVE_PATTERNS];
@@ -734,16 +1098,18 @@ export function loadConfig() {
                 return [];
             return trimmed.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
         })(process.env.SENSITIVE_WRITE_PATTERNS),
+        // [1557]§四: opt-in only — any value other than the two real gate shapes (incl. "off"/unset) stays undefined
+        // (no field on the config object at all), so the fs-write gate wiring never even considers it.
         ...(process.env.MANUAL_MODE_SHELL_GATE === "always" || process.env.MANUAL_MODE_SHELL_GATE === "classify"
             ? { manualModeShellGate: process.env.MANUAL_MODE_SHELL_GATE }
             : {}),
-        toolDeferLongtail: boolEnv("TOOL_DEFER_LONGTAIL", false),
-        lspEnabled: boolEnv("LSP_ENABLED", false),
-        lspHostEnabled,
-        drainGraceMs: Math.max(10_000, numEnv("DRAIN_GRACE_MS", String(10 * 60 * 1000))),
-        sighupIdleGraceMs: Math.max(5_000, numEnv("SIGHUP_IDLE_GRACE_MS", String(120_000))),
+        toolDeferLongtail: boolEnv("TOOL_DEFER_LONGTAIL", false), // [803]④ defer face: EXPERIMENTAL, default OFF
+        lspEnabled: boolEnv("LSP_ENABLED", false), // sandbox lane: opt-in (needs a baked sema-code-lsp template)
+        lspHostEnabled, // host lane: LSP_HOST_ENABLED, DEFAULT ON (CC-parity, degrades gracefully) — see the derivation above
+        drainGraceMs: Math.max(10_000, numEnv("DRAIN_GRACE_MS", String(10 * 60 * 1000))), // SIGTERM drain window, default 10min, floor 10s
+        sighupIdleGraceMs: Math.max(5_000, numEnv("SIGHUP_IDLE_GRACE_MS", String(120_000))), // B3: SIGHUP idle-shutdown window, default 2min, floor 5s
         mcpElicitation: {
-            enabled: boolEnv("MCP_ELICITATION_ENABLED", false),
+            enabled: boolEnv("MCP_ELICITATION_ENABLED", false), // E23 inbound elicitation; default OFF (fail-closed)
             throttle: {
                 maxConcurrentPerRun: numEnvBounded("MCP_ELICITATION_MAX_CONCURRENT", String(DEFAULT_ELICITATION_THROTTLE.maxConcurrentPerRun), 1, 64),
                 maxTotalPerRun: numEnvBounded("MCP_ELICITATION_MAX_TOTAL", String(DEFAULT_ELICITATION_THROTTLE.maxTotalPerRun), 1, 10_000),
@@ -751,9 +1117,9 @@ export function loadConfig() {
                 ttlMs: numEnvBounded("MCP_ELICITATION_TTL_MS", String(DEFAULT_ELICITATION_THROTTLE.ttlMs), 1_000, 3_600_000),
             },
         },
-        askQuestionEnabled: postureOn("ASK_QUESTION_ENABLED"),
-        toolApprovalEnabled: postureOn("TOOL_APPROVAL_ENABLED"),
-        workflowAgentsReadOnly: boolEnv("WORKFLOW_AGENTS_READONLY", false),
+        askQuestionEnabled: postureOn("ASK_QUESTION_ENABLED"), // §4④ AskUserQuestion live HITL; posture-gated (single-user → ON)
+        toolApprovalEnabled: postureOn("TOOL_APPROVAL_ENABLED"), // [816]/[820]② live tool-approval HITL; posture-gated (single-user → ON), mirrors askQuestion
+        workflowAgentsReadOnly: boolEnv("WORKFLOW_AGENTS_READONLY", false), // [824]① TOB 保守旋钮:默认 off = workflow 子 agent 同权(CC parity)
         imageBakes: {
             enabled: boolEnv("IMAGE_BAKES_ENABLED", false),
             runnerPrincipal: bakeRunnerPrincipal,
@@ -766,8 +1132,10 @@ export function loadConfig() {
             submitRateWindowSec: Math.max(1, numEnv("BAKE_SUBMIT_RATE_WINDOW_SEC", "60")),
         },
         toolTrace: boolEnv("TOOL_TRACE", false),
-        traceThinking: boolEnv("TRACE_THINKING", true),
+        traceThinking: boolEnv("TRACE_THINKING", true), // default ON (clay)
         logLevel: env("LOG_LEVEL", "info"),
+        // BL-9: numEnv (not bare Number) — a non-numeric typo FAILS at startup instead of becoming NaN, which would
+        // silently DISABLE the operator cost/rate ceiling (every `> ceiling` comparison against NaN is false).
         rateLimitPerMin: numEnv("RATE_LIMIT_RPM", "0"),
         maxTaskCostUsd: numEnv("MAX_TASK_COST_USD", "0"),
         maxTaskTokens: numEnv("MAX_TASK_TOKENS", "0"),
@@ -781,6 +1149,12 @@ export function loadConfig() {
                 downgradeOn: csv("MODEL_DEGRADE_ON").length
                     ? csv("MODEL_DEGRADE_ON")
                     : undefined,
+                // vision precheck (adversarial-review finding): the degrade TARGET is an external gateway
+                // model NOT in config.models, so resolveSpec's precheck (which only sees the picked model) can't see its
+                // vision capability — a vision-capable main + text-only degrade target would let images reach the text-only
+                // gateway as the opaque 400 the precheck prevents, AFTER admission, at runtime degrade. Declare it via
+                // MODEL_DEGRADE_TO_VISION (strict "true"). DEFAULT false = assume the cheaper degrade target is text-only
+                // (the common case, e.g. deepseek), so resolveSpec drops degrade for image-carrying tasks (main.ts).
                 toSupportsImages: boolEnv("MODEL_DEGRADE_TO_VISION", false),
             }
             : undefined,
@@ -789,12 +1163,16 @@ export function loadConfig() {
                 endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT.replace(/\/$/, ""),
                 intervalMs: Number(env("OTEL_EXPORT_INTERVAL_MS", "15000")),
                 serviceName: env("OTEL_SERVICE_NAME", "sema-server"),
+                // `OTEL_EXPORTER_OTLP_HEADERS` = comma-separated `k=v` pairs (e.g. an auth header).
                 headers: Object.fromEntries(csv("OTEL_EXPORTER_OTLP_HEADERS").map((kv) => {
                     const i = kv.indexOf("=");
                     return i === -1 ? [kv, ""] : [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
                 })),
             }
             : undefined,
+        // [875]a 成文:0(缺省)= durable HITL 无限期等人,时间型 reapSuspended 不跑;file/memory lane 的回收
+        // 探针只在 DURABLE_APPROVAL=true 时注入(无 durable 的部署两只 suspended 回收器恒 NO-OP,parked 行的
+        // 恢复把手 = POST /v1/runs/:id/cancel,[868]①)。checkpoint 过期驱动的那只不受本旋钮门控。
         approvalTimeoutSec: numEnv("APPROVAL_TIMEOUT_SEC", "0"),
         reapIntervalSec: numEnv("REAP_INTERVAL_SEC", "60"),
         runStaleSec: numEnv("REAP_RUN_STALE_SEC", "120"),
@@ -802,12 +1180,16 @@ export function loadConfig() {
         toolResultTtlSec: Number(env("TOOL_RESULT_TTL_SEC", "86400")),
         gitApiBaseUrl: process.env.GIT_API_BASEURL,
         gitApiToken: process.env.GIT_API_TOKEN,
+        // BEHAVIOR CHANGE([891] clay 硬裁定):出厂缺省场景 default→code(CC 编码 persona 蒸馏版)——
+        // 编码产品出厂态对标 CC 出厂态,通用域中性 persona 用 DEFAULT_SCENARIO=default 显式选回。
         defaultScenario: env("DEFAULT_SCENARIO", "code"),
         skillsDir: env("SKILLS_DIR", defaultSkillsDir()),
         oaApiBaseUrl: process.env.OA_API_BASEURL,
         oaServiceToken: process.env.OA_SERVICE_TOKEN,
+        // 开 issue 工具：默认开到 OA 系统仓(AI-Only/oa-asset-system)，写权限 token 走独立 env。
         oaIssue: process.env.OA_ISSUE_TOKEN
             ? {
+                // npm 卫生纪律:不再烤内网 git 主机缺省 — 开了 OA_ISSUE_TOKEN 就必须给 host(fail-loud)。
                 baseUrl: (() => {
                     const u = process.env.OA_ISSUE_BASEURL ?? process.env.GIT_API_BASEURL;
                     if (!u)
@@ -820,6 +1202,11 @@ export function loadConfig() {
                 defaultLabels: csv("OA_ISSUE_LABELS").map(Number).filter((n) => Number.isInteger(n)),
             }
             : undefined,
+        // sema-registry (control plane) URL/token/worker. The orchestrator renamed the worker-injected env from
+        // CONFIG_CENTER_* → SEMA_REGISTRY_* (the control-plane host was renamed to match); it dual-injects
+        // both names at the SAME value during the transition, so we DUAL-READ here — new name preferred, old name
+        // fallback — and keep working after the orchestrator drops the legacy CONFIG_CENTER_* names. Pure config
+        // plumbing: no API/auth/task-logic change.
         configCenter: (process.env.SEMA_REGISTRY_URL || process.env.CONFIG_CENTER_URL)
             ? {
                 baseUrl: process.env.SEMA_REGISTRY_URL || env("CONFIG_CENTER_URL"),
@@ -832,6 +1219,14 @@ export function loadConfig() {
         configLocalDir: process.env.CONFIG_LOCAL_DIR || undefined,
     };
 }
+/** 有效监听绑址([1934])。**显式 `BIND_HOST`/`HOST` 恒生效**(operator 保留在任何形下明示暴露的
+ *  权利);未显式时:**无鉴权写面 ⇒ 127.0.0.1**,其余 ⇒ undefined(Node 默认全接口,既有部署零影响)。
+ *
+ *  为什么缺省要自己收窄、而不是只加旋钮:桌面形的安全结论原本写着「safe ONLY because HOST is
+ *  pinned to 127.0.0.1」,而那个前提在本仓从未成立(HOST 零消费)——把一个没人实现的假设当防线,
+ *  是「沉默陷阱」。零凭证 + 全接口 + host lane(用户真机非沙箱)= 同网段任意执行,缺省必须安全。
+ *  "无鉴权写面" 的判据与 http 层 503 fail-closed 门同源:allowUnauthedWrites 且**完全没有**凭证
+ *  (半配=凭证必须使用,不算无鉴权)。 */
 export function resolveBindHost(config) {
     if (config.bindHost)
         return config.bindHost;