@sema-agent/server 1.323.0 → 2.0.0

package/dist/main.js

@@ -106,6 +106,8 @@ import { WorkflowAgentRegistry } from "./orchestration/workflow-agent-steer.js";
 import { SubagentSteerRegistry } from "./orchestration/subagent-steer.js";
 import { FleetEventBus, fleetBackgroundChildPublisher } from "./fleet/fleet-bus.js";
 import { createKeyResolver } from "./key-resolver.js";
+/** Service version for GET /v1/capabilities — read from the package.json shipped next to src/ in the
+ *  image (Dockerfile COPYs it). Best-effort: an unreadable file reports "unknown", never crashes boot. */
 function serviceVersion() {
     try {
         const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -115,37 +117,100 @@ function serviceVersion() {
         return "unknown";
     }
 }
+/**
+ * Service entrypoint. Wires the three planes:
+ *   Brain   = external LLM gateway (createBrain)
+ *   Session = pluggable store (TiDB durable event-log center, or in-memory)
+ *   Hands   = tools/MCP injected per request in resolveSpec (deployment-owned)
+ * Persistence (L1 sessions + L2 memory) lives in the external TiDB center; this container is stateless.
+ */
 async function main() {
     const config = loadConfig();
+    // Liveness invariant: the running instance refreshes updated_at every HEARTBEAT_MS; the reaper fails
+    // a run whose updated_at is older than runStaleSec. If the stale window were ≤ the heartbeat, the
+    // reaper would race a perfectly alive run. Fail fast on a misconfiguration instead of reaping live work.
     if (config.runStaleSec * 1000 <= HEARTBEAT_MS) {
         throw new Error(`REAP_RUN_STALE_SEC (${config.runStaleSec}s) must exceed the ${HEARTBEAT_MS / 1000}s liveness heartbeat`);
     }
     const logger = createLogger(config.logLevel);
     const metrics = createMetrics();
+    // S20 (SILENT-FALLBACK P1) + [792]④ boot notices: config parsing runs before the logger exists — drain both
+    // pre-logger collectors via the shared helper (F10: run-local uses the same one, so entrypoints can't drift).
     logConfigDiagnostics(logger);
+    // design/158 B4 交接小件:plugins 数值旋钮(HOST_BG_*/K8S_BG_*/E2B_*,模块级 import 时读)的非法
+    // 字面量告警——通道在 remote-shell.ts 自带(不造 plugins→config 依赖边),与上面同一 boot 诊断点排空。
     for (const w of drainNumEnvWarnings())
         logger.warn("config_env_invalid_using_default", { env: w.env, raw: w.raw });
+    // M1(接入审计 2026-07-08):core verify 契约=verifier 必须异于 implementer(去相关性是 🔴 部署契约)。
+    // verifier 角色落 "default" 时对抗验证者=实现者自评自批——比无验证更糟(假安全感)。曝光而非静默:
+    // 单模型部署配 MODEL_VERIFIER 指异构模型即消警(typo/不在 catalog 同样落到这里)。
     if ((config.roles?.verifier ?? "default") === "default") {
         logger.warn("verify_decorrelation_unavailable", {
             hint: "verifier role = default (= implementer) — adversarial verification grades its own work; set MODEL_VERIFIER=<catalog model id> to a heterogeneous model",
             ...(process.env.MODEL_VERIFIER ? { rejected: process.env.MODEL_VERIFIER, reason: "not in catalog" } : {}),
         });
     }
+    // S24: redaction rewrites by pattern; LOW: web-search non-array payloads by provider.
     setRedactionObserver((pattern, n) => metrics.inc("redactions_applied_total", { pattern }, n));
     setWebSearchBadPayloadObserver((provider) => {
         metrics.inc("web_search_bad_payload_total", { provider });
         logger.warn("web_search_non_array_payload", { provider });
     });
+    // Sema registry (sema-registry): pull the effective config on boot and apply it OVER the env
+    // defaults — env is the fallback. Unset or unreachable → keep the env-derived config. Applied BEFORE
+    // the Runner is built so models/roles/teams take effect. (Logical config only; secrets stay in env.)
     let ccEtag;
+    // Kept past the fetch so the deferred skills/mcp apply (which needs the live `skills` array + async
+    // content lazy-pull) can run right before buildScenarios, after applyEffective handled models/roles/teams.
+    // `effective` is the BOOT snapshot — the refresh loop never reassigns it, so restartReasons() compares each
+    // pull against what THIS process baked in (change-detection, not presence → no auto-restart loop).
     let effective;
+    // 提示词装配协议 §9.5-2 three-store split: `effective` above = the boot snapshot (diff baseline);
+    // `latestEffective` = the last candidate that passed validation AND was applied — the explicit
+    // last-known-good (LKG). A refresh candidate failing validation is REJECTED whole (§9.5-5): never
+    // applied, so the live config keeps serving this LKG instead of a domain falling to schema-default/
+    // empty. The third store (promptCandidate — a staged prompts-domain artifact awaiting activation)
+    // lands with the prompts domain itself; `lastRejectedCandidate` is its observability forerunner and
+    // the prompts-domain validation (core S1 schema) hooks into the same gate.
     let latestEffective;
     let lastRejectedCandidate;
+    // codex R10 (models-tiers 窗收口): the last EffectiveConfig whose MODEL PLANE (models/roles/tiers/default) was
+    // actually applied to the live config — undefined = env plane (no center plane applied yet). When the Runner is
+    // tier-frozen, a refresh whose plane differs from THIS is deferred to restart (applyEffective deferModelPlane),
+    // keeping admission and the Runner on one catalog generation through the restart window.
     let appliedPlaneEff;
+    // codex R18: the persistent "deferred WITHOUT next-boot handoff" state — the one-shot warn is not enough
+    // (the etag advances → later ticks 304 and never re-enter the defer branch). Set when a plane defers with no
+    // restart-surviving LKG; cleared when a plane finally applies or a forced restart reason ships. Surfaced on
+    // /health (modelPlaneDeferred) + re-warned every refresh tick (incl. 304s).
     let planeDeferredNoHandoff;
+    // codex R35: STICKY live-skill application debt — the boot-baked skill table never rebuilds inside this
+    // process, so once the live application is known incomplete the debt survives every refresh (a
+    // same-generation 200 recomputes reasons vs boot as [] and would otherwise silently clear the signal).
+    // Set at the boot writer (R34 arms); folded into every tick's reasons; only a restart resolves it.
     let bootSkillStale = false;
+    // Sema-registry restart signal: set by the refresh loop when a pull's restart-to-apply slices
+    // (skills/mcp/scenarios/runtime-gates) differ from boot; read by GET /health for orchestrator auto-restart.
     let pendingRestart;
+    // DUAL-MODE-DESIGN §4: the config SOURCE is a backend-selectable seam — remote (sema-registry HTTP, the fleet
+    // default) | local (.env + config.d via @sema-agent/registry-core FileConfigStore, the single-machine/TOC source).
+    // The provider exists when SEMA_REGISTRY_URL (legacy CONFIG_CENTER_URL) is set OR CONFIG_PROVIDER=local is explicit; neither = pure-env
+    // (byte-identical to before). The remote provider DELEGATES verbatim to fetchEffective, so the fleet path is
+    // unchanged; applyEffective consumes either source's EffectiveConfig identically (one resolver → no drift).
     const cc = config.configCenter;
+    // 🔴 ONE local root for BOTH the config provider (models/skills/mcp) AND the remoteExec loader (avoids a
+    // split-brain — createConfigProvider defaulted to process.cwd() while loadRemoteExec used
+    // AGENT_DATA_DIR, so config.d and remote-exec.json could resolve to DIFFERENT directories). run-local already
+    // computes this once; main.ts now does too. Used below for loadRemoteExec.
     const localRoot = config.configLocalDir ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent");
+    // Sealed-box key custody: ensure this host's X25519 keypair(s) under
+    // <localDataRoot>/sealed-key/ (dir 0700, files 0600; SEVERAL may coexist — rotation keeps old private
+    // keys decrypting old ciphertexts) BEFORE the first effective pull, so a roster carrying
+    // `sealedApiKey` unseals on the boot apply. The public-key report is best-effort fire-and-forget:
+    // the center's execution-keys face is admin-gated and a worker only holds the pull token, so without
+    // an operator-provided SEMA_REGISTRY_ADMIN_TOKEN it prints the full public key for manual
+    // registration instead (honest posture — see reportExecutionPublicKey). Store failure is non-fatal:
+    // sealed models then warn per-model in applyEffective (fail-loud, never a silent apiKeyEnv fallback).
     let sealedKeys;
     try {
         sealedKeys = await ensureSealedKeyStore(join(config.localDataRoot ?? localRoot, "sealed-key"), logger);
@@ -167,6 +232,9 @@ async function main() {
             ...(config.configProvider === "local" ? { localDir: localRoot } : {}),
         })
         : undefined;
+    // boot ready 门 latch:仅「远程 registry 部署(非 dryRun)+ 无显式 env MODEL_ID」时等 roster——
+    // 首次 effective 落 ≥1 enabled 模型即翻 true(one-way)。其余姿势(env 模型在/local provider/dryRun/纯 env)
+    // 恒 ready=现有部署零影响。E3 废除 workers.model 后,fleet worker 的占位模型窗口由此门 fail-closed。
     const modelReadyState = { ready: !(cc && !cc.dryRun) || Boolean(process.env.MODEL_ID) };
     const markRosterLanded = (eff) => {
         if (!modelReadyState.ready && (eff.models?.models ?? []).some((m) => m.enabled !== false)) {
@@ -174,7 +242,14 @@ async function main() {
             logger.info("model_roster_landed", { note: "ready gate open — billable submissions accepted" });
         }
     };
+    // center prompts ref([1057]/[1062] 投影腿):**热采用,新任务边界生效**——core 1.316([1068] 裁 a/
+    // [1070]d)把 provider 声明纳入 epoch artifactDigest:声明变=digest 变=下任务边界自动重 pin,进行中
+    // 会话由 session epoch pin 保稳,resume 记账诚实(1.222 的 restart-to-apply 是 core 件落地前的正确
+    // 过渡姿势,[1068]① 官方确认后随 1.316 采用降级为热生效——与 center「发布=新任务生效」产品语义对齐)。
+    // 判形通过才采用(形校验=防 core-assemble-THROW 底线,非语义复检 [1057]①f);坏形=warn+沿用旧包。
     let centerPrompts;
+    /** codex-3 F1:一次失败的 catalog 过渡的目标面(undefined 目标=欠 disable)。etag 已推进时 provider
+     *  304 短路 adopt——本 marker 让每个 refresh 拍(含 304 拍)独立重试,直到过渡落地。 */
     let pendingCatalogFaces;
     const retryPendingCatalog = async (phase) => {
         if (!pendingCatalogFaces)
@@ -185,8 +260,25 @@ async function main() {
             pendingCatalogFaces = undefined;
         }
     };
+    // e/b(catalog 轴消费面,[1236]① seam):core 的 CenterPromptSource——server 只给根路径,core 文件形
+    // 自管 `<root>/prompt-epoch/{artifacts,source-state.json}`;boot restore=磁盘 LKG(离线重启 candidate
+    // 存续/disabled 不复活,状态机全在 core)。RunnerDeps.promptSource 挂它;adopt 时经 applyCatalogToSource
+    // 推进两态过渡。restore 失败=warn(candidate 缺席,catalog 轴等下一次 adopt;declaration 轴/内置照跑)。
     const promptEpochDir = join(config.localDataRoot ?? localRoot, "prompt-epoch");
+    // codex-3 F2:effective 拉取是 worker 轴的(config LKG 同理 worker-keyed)——同根多 worker 进程共享
+    // content-addressed artifacts/(by-digest,天然安全),但 **candidate 状态必须按 worker 分箱**:共写一份
+    // source-state.json 会让 A 的撤下压掉 B 的 candidate、restart 恢复到别人 worker 的 catalog(错 worker
+    // 的系统提示词跑任务)。encodeURIComponent 消毒(worker 名进路径)。
+    // codex-5:无撞形分箱——缺席=字面 "global",配置了 worker= "worker-<sha256 前 16>"(哈希后天然单
+    // 段/无 dot-segment/与 "global" 不可能同名;worker 名任意字节也安全)。
     const promptStateDir = join(promptEpochDir, "state", cc?.worker === undefined ? "global" : `worker-${createHash("sha256").update(cc.worker).digest("hex").slice(0, 16)}`);
+    // codex-6 F1:File 店构造同步 mkdir——只读/不可写数据根会把「可选的 catalog 特性」变成整服务 boot
+    // 失败。守护工厂:文件形失败 ⇒ warn + Memory 店兜底(candidate 不跨重启持久,catalog 采用仍工作;
+    // 内置/declaration 轴完全不受影响)。
+    // [985]b / [1285] — §9.4 by-digest 补拉组合店:local miss(本副本从未采用过该 candidate / 盘失)⇒
+    // 从 center 按 digest 补拉 envelope ⇒ core verifyPromptArtifact 全管线(canonical 复算;**且回验
+    // 「拿到的=要的」digest 逐位**,center 答非所问=丢弃)⇒ best-effort 回写盘(下次直命中)。pinned
+    // resume 的 fail-loud miss 自此只剩「center 也没有」的真缺席。仅 remote 治理形(cc.baseUrl)挂补拉。
     const withByDigestBackfill = (inner) => cc?.baseUrl ? withPromptArtifactBackfill(inner, (d) => fetchPromptArtifact(cc.baseUrl, cc.token, d), logger) : inner;
     const promptSource = (() => {
         try {
@@ -201,6 +293,10 @@ async function main() {
             return new CenterPromptSource({ store: withByDigestBackfill(new MemoryPromptArtifactStore()), stateStore: new MemoryPromptSourceStateStore(), engineVersion: CORE_ENGINE_VERSION });
         }
     })();
+    // codex-2 F4:只有「有配置源在治理且非 dry-run」才 restore 磁盘 candidate——provider-off/dry-run 姿势下
+    // 旧部署遗留的 active candidate 不得继续影响新任务(publish-gate-off/compare-only 语义)。不 restore 只
+    // 影响 candidate 面;pinned resume 的 by-digest 解析走 FilePromptArtifactStore.get(不依赖 restore),
+    // 旧会话恢复不受损。
     if (configProvider && !cc?.dryRun) {
         try {
             await promptSource.restore();
@@ -212,6 +308,8 @@ async function main() {
     const adoptCenterPrompts = async (eff, phase) => {
         const raw = eff?.prompts;
         if (raw === undefined) {
+            // fail-closed 语义([1057]①d):publish 闸关=key 整体不出现 ⇒ 收敛回内置提示词(不是「保持旧包」——
+            // 闸关是显式撤下,沿用旧包会让「关闸」失效)。
             if (centerPrompts)
                 logger.info("center_prompts_cleared", { phase, note: "effective carries no prompts key (publish gate off) — built-in providers resume" });
             const cleared = await applyCatalogToSource(promptSource, undefined, centerPrompts, logger, phase);
@@ -220,7 +318,7 @@ async function main() {
                 pendingCatalogFaces = undefined;
             }
             else {
-                pendingCatalogFaces = { target: undefined };
+                pendingCatalogFaces = { target: undefined }; // failed disable — retried by the refresh hook (codex-3 F1)
             }
             return;
         }
@@ -230,6 +328,7 @@ async function main() {
             return;
         }
         if (centerPrompts?.identity !== v.value.identity) {
+            // [985]a §3:axes 观测两轴共存窗;declaration 轴字段照旧,catalog 轴报 artifactDigest(内容身份)。
             logger.info("center_prompts_adopted", {
                 phase,
                 axes: v.value.axes,
@@ -241,6 +340,9 @@ async function main() {
             });
         }
         const transitioned = await applyCatalogToSource(promptSource, v.value, centerPrompts, logger, phase);
+        // codex-2 F2 + codex-3 F1:catalog 过渡失败 ⇒ 身份不推进(centerPrompts 保持 prev),且目标面记入
+        // pendingCatalogFaces——etag 会照常推进(其他域的采用不为 prompts 的盘错扣住),此后 provider 304
+        // 不再进本函数,重试由 refresh 拍上的 retryPendingCatalog 钩独立驱动(见 refresh 循环)。
         if (transitioned) {
             centerPrompts = v.value;
             pendingCatalogFaces = undefined;
@@ -249,15 +351,57 @@ async function main() {
             pendingCatalogFaces = { target: v.value };
         }
     };
+    // Boot-deferred pull (clay 2026-07-17): when the boot fetch outlives its budget, the SAME promise is
+    // stashed here and, once the refresh tick exists (defined further down), chained to trigger an immediate
+    // hot-apply on arrival — the server meanwhile starts on the env fallback in <1s instead of hanging up to
+    // ~8s on a black-holed center (真机实测 5.7s = the "local server takes 5s" report).
     let bootConfigPending;
+    // LKG 落盘(clay 拍 2026-07-18;config-lkg.ts 顶注=全案由):remote lane 的干净候选持久化——boot 的
+    // 第三级来源(中心 > 盘上 LKG > env)。`lkgBooted` 标志决定 deferred continuation 的形:LKG 起服=有
+    // 完整 boot 基线 → 到货走普通 refreshTick(候选门+hot+restartReasons 对 LKG 比较,通常零差异=无环);
+    // 无 LKG=env 起服 → 到货走「迟到 boot」路径(deferredBootApply)。
     const lkgEnabled = configProvider?.kind === "remote" && configLkgEnabled();
     const lkgPath = process.env.CONFIG_LKG_PATH ?? defaultLkgPath(cc?.worker);
+    // codex R17/R20: a successful LOCAL write proves nothing about the NEXT instance seeing it — a stateless pod
+    // replaces its filesystem on restart, so treating a pod-local rename as "handoff confirmed" re-opens the R16
+    // rolling-restart storm. Next-instance visibility is a DEPLOYMENT contract only the operator can assert, and
+    // ONLY via the explicit knob: CONFIG_LKG_DURABLE=true declares the LKG path rides restart-surviving storage
+    // (host disk / PVC / shared volume). CONFIG_LKG_PATH is strictly a LOCATION override (R20: it can point at an
+    // ephemeral container path — a location says nothing about durability). Unset ⇒ the models-tiers restart
+    // reason stays suppressed on a deferred plane (old generation keeps serving; /health modelPlaneDeferred +
+    // per-tick warn carry the state) while normal LKG writes continue (they still help same-instance restarts).
     const lkgSurvivesRestart = lkgEnabled && process.env.CONFIG_LKG_DURABLE === "true";
     let lkgBooted = false;
-    let bootLkgCandidate;
+    let bootLkgCandidate; // F7:skills 装载后才落盘
+    // F1+F2(LKG 复审):awaited 落盘 + skill 正文预热——refresh 只落 manifest 的话,重启后 LKG-boot 在
+    // 中心不可达时新 skill 正文缓存缺失=软跳过(静默缺 skill)。预热=枚举 enabled manifest,把缺盘的正文
+    // 拉齐进 content-addressed 缓存(失败=warn 软降级,与 boot 的 skill_failed 同语义等级——skill 拉取
+    // 失败从不升级为配置拒绝);await 保证 restart 信号可见前 LKG+正文已落盘。
+    /** Returns TRUE iff the candidate is durably persisted for the NEXT boot (codex R16: the FORCED models-tiers
+     *  restart reason must never fire without a confirmed handoff — LKG disabled/unwritable + over-budget boot
+     *  pulls would otherwise turn the deferral into a rolling-restart storm: every restarted process boots the env
+     *  plane again, defers again, re-signals). Change-DETECTED reasons still ride regardless (their loop is the
+     *  pre-existing, documented no-LKG residual). */
+    // codex R37 loop-breaker proof: TRUE iff the LAST persistLkgDurable call hash-verified EVERY enabled skill
+    // body on disk. This is the "a restart can actually repair the live skill table" proof the NON-durable lane
+    // requires before publishing a skills restart — a successful manifest pull only proves the CONFIG endpoint
+    // works, not the SEPARATE body fetches; signaling on manifest-success alone lets a persistent body failure
+    // (404 / hash mismatch / timeout) restart-storm a stateless deployment (every replacement process fails the
+    // same body, signals again, is restarted again). With the proof, a storm cannot form: a boot that fails the
+    // body lacks the proof and only retains visible debt (no signal) until a later verify succeeds.
     let lastPrewarmBodiesVerified = false;
     const persistLkgDurable = async (effectiveObj, etag) => {
         lastPrewarmBodiesVerified = false;
+        // codex R21: the LOCAL provider's candidate IS the next-boot source (config.d on the same disk boot reads
+        // BEFORE Runner construction) — the handoff is inherent, no LKG needed. Without this arm a polled config.d
+        // edit that defers the plane (tier activation / tier-frozen change) could never authorize its own restart
+        // (lkgEnabled is remote-only, so even CONFIG_LKG_DURABLE couldn't help) — stuck in modelPlaneDeferred forever.
+        // codex R28 requalified: this TRUE covers the MODEL PLANE (what the deferral gate adjudicates). Skills are
+        // NOT part of the local handoff because the local lane does not consume a center-style skills domain AT ALL
+        // yet — the only boot consumer (applyCenterSkills) requires config.configCenter (remote HTTP), absent on
+        // CONFIG_PROVIDER=local; bodies live inline in config.d (LocalConfigProvider.fetchSkillContent) but no boot
+        // path reads them. Pre-existing local-lane gap (predates this train, nothing lost across restart that was
+        // ever applied); wiring boot skills through the ConfigProvider seam is the tracked follow-up (board).
         if (configProvider?.kind === "local")
             return true;
         if (!lkgEnabled)
@@ -266,6 +410,15 @@ async function main() {
             if (effectiveObj.skills && config.configCenter) {
                 await applyCenterSkills([], effectiveObj.skills, config.configCenter.baseUrl, config.configCenter.token, logger, undefined, defaultSkillCacheDir());
             }
+            // codex R25/R26: skill BODIES are part of the handoff contract, and completeness gates PUBLICATION —
+            // applyCenterSkills swallows fetch/cache-write failures, so awaiting it proves nothing; verify every
+            // ENABLED manifest hash on disk (content-true) BEFORE the atomic LKG replace (R26: verifying after left
+            // an incomplete candidate as the boot-visible LKG — any crash/manual restart with the center down then
+            // boots that manifest, silently skips the uncached skills, and never re-signals because the manifest is
+            // the new boot baseline). On any miss/corruption the PREVIOUS good LKG stays in place; the per-tick
+            // retained-candidate retry re-attempts prewarm + verify + publish.
+            // Residual seam (honest, partial): the skill cache roots at SEMA_CONFIG_DIR while lkgPath can point
+            // elsewhere — CONFIG_LKG_DURABLE's contract requires BOTH on restart-surviving storage.
             const enabledSkills = (effectiveObj.skills?.skills ?? []).filter((m) => m.enabled !== false);
             const cacheDir = defaultSkillCacheDir();
             for (const m of enabledSkills) {
@@ -284,8 +437,11 @@ async function main() {
                     return false;
                 }
             }
-            lastPrewarmBodiesVerified = true;
+            lastPrewarmBodiesVerified = true; // every enabled body verified on disk — the repair proof stands even if the LKG write below fails
             await saveLkg(lkgPath, cc?.worker, effectiveObj, etag);
+            // codex R17: TRUE = next-BOOT visibility, not merely a successful local rename — gated on the operator's
+            // restart-surviving-storage declaration (lkgSurvivesRestart above). A stateless pod's local write still
+            // helps same-instance restarts but must not authorize a forced restart.
             return lkgSurvivesRestart;
         }
         catch (err) {
@@ -294,7 +450,9 @@ async function main() {
         }
     };
     if (configProvider) {
-        const dryRun = cc?.dryRun ?? false;
+        const dryRun = cc?.dryRun ?? false; // dry-run posture is remote-only (a local source has nothing to compare against)
+        // LKG 读腿(boot 超窗与硬失败两个入口共用):盘上有验证过的干净候选 → 当 boot 配置整套应用
+        // (skills/mcp 进 buildScenarios——这正是 env 兜底给不了的),etag 落位 → refresh 首拍 304 或正常增量。
         const bootFromLkg = async (why) => {
             if (!lkgEnabled || dryRun)
                 return null;
@@ -312,7 +470,7 @@ async function main() {
             await adoptCenterPrompts(lkgR.effective, "boot-lkg");
             markRosterLanded(lkgR.effective);
             effective = lkgR.effective;
-            appliedPlaneEff = lkgR.effective;
+            appliedPlaneEff = lkgR.effective; // model plane applied pre-Runner — this IS the Runner's generation
             latestEffective = lkgR.effective;
             if (lkgR.etag !== undefined)
                 ccEtag = lkgR.etag;
@@ -325,7 +483,7 @@ async function main() {
             let lkgFallback = null;
             if (raced === BOOT_FETCH_DEFERRED) {
                 bootConfigPending = bootFetch;
-                bootFetch.catch(() => { });
+                bootFetch.catch(() => { }); // settled in the background — failure handling lives on the refresh cadence
                 lkgFallback = await bootFromLkg("boot fetch deferred (budget exceeded)");
                 lkgBooted = lkgFallback !== null;
                 logger.warn("config_boot_fetch_deferred", {
@@ -337,6 +495,9 @@ async function main() {
                         : "center slow/unreachable and no usable LKG — serving on the env fallback; the pull continues in the background (late-boot adoption on arrival). Raise CONFIG_BOOT_FETCH_BUDGET_MS to block boot instead.",
                 });
             }
+            // F4(LKG 复审):LKG 载荷的 apply 用专属 catch——走主分支会让 applyEffective 半程炸落到外层
+            // catch 的「config_source_unreachable_using_env」误导日志(中心明明只是慢)。坏 LKG=点名+env 兜底
+            // (in-place mutate 的混态风险与 live 坏载荷同级,浅域判形在 loadLkg 已挡结构性坏形)。
             if (raced === BOOT_FETCH_DEFERRED && lkgFallback) {
                 try {
                     await bootApplyLkgInline(lkgFallback);
@@ -348,26 +509,41 @@ async function main() {
             }
             const r = raced === BOOT_FETCH_DEFERRED ? null : raced;
             if (r) {
+                // [898] tolerant read(registry-core 0.10.12,local lane):catalog 域坏文件不再连坐整包回落 env——
+                // 坏域按 default 落+per-domain warn 点名(文件路径在 error 文案里),好域照常生效。gate 域坏文件
+                // tolerant 仍 throw(READ 容错不放宽 gate fail-loud)⇒ 走下面既有整包 catch。
+                // §9.5-5 boot 与 refresh 的分工(codex F1:重启不得洗白坏候选):boot 照旧 tolerant APPLY(无 LKG
+                // 可保,带着好域起服务),但一个带错误的候选 ①不推进 ccEtag——refresh 首 poll 拿到同一棵树,候选门
+                // 当场整拒并持续 warn 到修复;②不写入 latestEffective——LKG 永远只指向完全干净的候选,拒绝日志的
+                // lkgVersion 也诚实(boot 带错=「(env)」)。markRosterLanded 保留:models 域自身干净才可能开门
+                // (坏 models 域 tolerant 落空=enabled 0=门不动),其他域的错误不构成扣住就绪门的理由。
                 const bootPromptsRaw = r.effective.prompts;
                 const bootPromptsOk = bootPromptsRaw === undefined || validatePromptsDomain(bootPromptsRaw).ok;
+                // 坏 prompts 面同 domainErrors 计入 not-clean(F6 boot 半场):etag 不进 → refresh 首拍同树整拒持续
+                // warn;LKG 不指向带坏 prompts 的候选。adoptCenterPrompts 自身会拒采用+点名。
                 const bootClean = (r.domainErrors ?? []).length === 0 && bootPromptsOk;
                 if (bootClean)
                     ccEtag = r.etag;
                 for (const de of r.domainErrors ?? [])
                     logger.warn("config_domain_invalid", { domain: de.domain, error: de.error, note: "tolerated at BOOT (corrupt file → schema defaults; dangling ref → reported as-is); the refresh path rejects such a candidate whole and keeps the LKG (§9.5-5)" });
                 if (dryRun) {
-                    logEffectiveDiff(config, r.effective, logger);
+                    logEffectiveDiff(config, r.effective, logger); // compare-only: log the would-be changes, keep env
                 }
                 else {
-                    applyEffective(config, r.effective, logger, { sealedKeys });
-                    await adoptCenterPrompts(r.effective, "boot");
-                    markRosterLanded(r.effective);
-                    effective = r.effective;
-                    appliedPlaneEff = r.effective;
+                    applyEffective(config, r.effective, logger, { sealedKeys }); // sealedKeys: unseal sealedApiKey → in-memory key pipeline
+                    await adoptCenterPrompts(r.effective, "boot"); // [1057] additive prompts key(判形采用;缺席=内置)
+                    markRosterLanded(r.effective); // boot pull 即落 roster 的常态:门在启动窗内就打开
+                    effective = r.effective; // skills/mcp applied below, before buildScenarios (restart-to-apply)
+                    appliedPlaneEff = r.effective; // model plane applied pre-Runner — this IS the Runner's generation
                     if (bootClean)
-                        latestEffective = r.effective;
+                        latestEffective = r.effective; // LKG seed (§9.5-2): only a fully clean candidate may become the LKG
+                    // F7(LKG 复审三轮):boot 写点**延后**到 center skills 装载(applyCenterSkills+盘缓存)之后——
+                    // 先落 LKG 会让「新 skill 的 manifest 可见但正文没进缓存」窗口存在(此窗内崩+中心断=离线 boot
+                    // 静默缺 skill)。这里只记 candidate,真正落盘在 skills 装载后(main 后段)。
                     if (bootClean && !lkgBooted)
                         bootLkgCandidate = { effective: r.effective, etag: r.etag };
+                    // [875]b:带上模型数与(local lane)真实目录来源——复验实录:CONFIG_LOCAL_DIR 误配(只设
+                    // LOCAL_DATA_ROOT)时 config.d 静默读不到、0 模型且无告警,排障只能靠猜。
                     const cfgModels = (r.effective.models?.models ?? []).filter((m) => m.enabled !== false).length;
                     const cfgDir = configProvider.kind === "local" ? { dir: configProvider.root } : {};
                     logger.info("config_loaded", { source: configProvider.kind, version: r.effective.version, worker: cc?.worker ?? "(global)", models: cfgModels, ...cfgDir });
@@ -378,6 +554,7 @@ async function main() {
         }
         catch (err) {
             logger.warn("config_source_unreachable_using_env", { source: configProvider.kind, err: String(err) });
+            // 硬失败(fast-fail RST 等,非超窗)同样值得 LKG:上一进程的干净候选好过纯 env。
             const lkgFallback = await bootFromLkg(`boot fetch failed: ${String(err).slice(0, 120)}`);
             if (lkgFallback) {
                 lkgBooted = true;
@@ -393,10 +570,21 @@ async function main() {
     }
     if (!modelReadyState.ready)
         logger.warn("model_roster_pending", { note: "registry deployment without an env model and no roster yet — billable submissions 503 until the first effective pull lands models" });
+    // DUAL-MODE §4/§5 (center #1): in LOCAL config mode, source remoteExec from the SHARED
+    // `config.d/remote-exec.json` via the registry `loadRemoteExec` — the SAME file + zod validation that the
+    // client's `agent-cli config` writes, so client doctor and the engine read one source of truth (zero drift).
+    // Semantics (center, deliberate): file MISSING → undefined → keep the env/host default (config.ts already
+    // defaults host in local mode); file PRESENT → it wins; file empty/corrupt → the loader throws → fail-closed
+    // (an empty file silently falling back to host would be an isolation downgrade if the user meant local-docker).
     if (configProvider?.kind === "local") {
         try {
-            const fileRx = await loadRemoteExec(localRoot);
+            const fileRx = await loadRemoteExec(localRoot); // SAME root as the config provider above (no split-brain)
             if (fileRx) {
+                // 🔴 center contract: the package RemoteExecSpec is the CONTRACT form (env-NAME refs: apiKeyEnv/tokenEnv/…);
+                // our config.remoteExec is the RESOLVED form (values). `host` carries NO secrets so it maps 1:1 (contract
+                // `workdir` ≡ our `workspaceBase`). The ISOLATED lanes (e2b/k8s/ssh/adb) need a NAME→value resolution
+                // before use — a follow-on; until then they are sourced from REMOTE_EXEC env, so a file-source isolated
+                // arm is ignored (NOT cast verbatim — that would feed an env-NAME where a value is expected).
                 if (fileRx.provider === "host") {
                     config.remoteExec = {
                         provider: "host",
@@ -406,6 +594,10 @@ async function main() {
                     logger.info("remote_exec_from_file", { provider: "host", root: localRoot });
                 }
                 else if (fileRx.provider === "local-docker") {
+                    // local-docker carries NO secret env-NAMEs (image/memory/cpus/network/workdir/mountPath only), so it
+                    // maps 1:1 from the contract form — no NAME→value resolution needed (unlike e2b/k8s/ssh). The contract
+                    // `workdir` is the in-container workspace ROOT ≡ our `mountPath`. DOCKER_HOST/secret env stay in the
+                    // worker's .env (the adapter reads its own process.env via the env-forward, not the file).
                     config.remoteExec = {
                         provider: "local-docker",
                         image: fileRx.image,
@@ -423,20 +615,31 @@ async function main() {
         }
         catch (err) {
             logger.error("remote_exec_file_invalid", { root: localRoot, err: String(err) });
-            throw err;
+            throw err; // fail-closed (center semantics): a corrupt remote-exec.json must not boot a wrong/weaker lane
         }
     }
+    // One shared SQL store backend for L1 + L2 (TiDB/MySQL or PostgreSQL per DB_BACKEND). Owned here.
     let backend;
-    let storeBackendDegraded = false;
+    let storeBackendDegraded = false; // S5: auto-probe degraded this replica to in-memory (surfaced via gauge + /health)
+    // `auto` probes a configured DB and degrades to in-memory if it's unreachable (local/intranet binaries:
+    // "use my DB if I can reach it, else memory"). Explicit `tidb` fails fast instead — silently dropping
+    // persistence the operator asked for would lose runs. (`tidb` here = "the SQL DB"; DB_BACKEND picks the engine.)
     const wantDb = config.sessionBackend === "tidb" ||
-        config.dbBackend === "local" ||
+        config.dbBackend === "local" || // local (clay 2026-06-25): always build the DB-less in-memory/file StoreBackend
         (config.sessionBackend === "auto" && !!(config.tidb || config.pg));
     if (wantDb) {
+        // 构造 + ensureSchema 同罩一层降级臂(2026-07-28 修):原先 try 只罩 ensureSchema,而 local 形真正
+        // 会抛的是构造里的 mkdir + 数据根 BootLock ——「裸 boot 不得拒启」那条口径对 local 从未生效过。
+        // 降级/fail-loud 的判据与理由见 openStoreBackendWithFallback 顶注。
         const opened = await openStoreBackendWithFallback(config, logger);
         backend = opened.backend;
         storeBackendDegraded = opened.degraded;
     }
+    // S5 review LOW-1: always render the series (0 = healthy) — gauge absence is indistinguishable from
+    // "old build without this metric", which breaks `== 0`-style alert rules.
     metrics.setGauge("store_backend_degraded", storeBackendDegraded ? 1 : 0);
+    // S21 (SILENT-FALLBACK P1): MINIO_* partially set silently falls back to SQL-blob snapshots. Warn on the
+    // partial config and always render which backend blobs actually use.
     {
         const minioReq = ["MINIO_ENDPOINT", "MINIO_ACCESS_KEY", "MINIO_SECRET_KEY"];
         const present = minioReq.filter((v) => (process.env[v] ?? "") !== "");
@@ -445,14 +648,34 @@ async function main() {
         }
         metrics.setGauge("snapshot_blob_backend", 1, { backend: config.snapshotBlobStore ? "minio" : "sql" });
     }
+    // Resolve `auto` to the concrete backend the rest of the wiring understands (createSessionStore,
+    // runStore, the startup summary). A DB-backed L2 with no backend degrades to in-memory the same way.
     if (config.sessionBackend === "auto")
         config.sessionBackend = backend ? "tidb" : "memory";
+    // local backend: route the session store through backend.session() (LocalSessionStore — the §0.5 OwnerAware twin),
+    // NOT the bare TtlSessionStore the "memory" path returns; "tidb" here means "the backend's durable store" generically.
     if (config.dbBackend === "local" && backend)
         config.sessionBackend = "tidb";
+    // Long-term memory (design/138 S1, clay 2026-07-08): the injection-first file-based memory ENGINE is the
+    // only memory plane — `RunnerDeps.memoryBackend` is core's switch (materialize → session file ops →
+    // harvest; no remember/recall tools). SINGLE-USER TURNKEY ONLY: the file basement has no tenant
+    // isolation, so a multi-tenant deployment (requirePrincipal) gets `undefined` = memory dark, fail-closed
+    // (memoryEngineBackendFor + memoryScopeFor enforce the same gate). The legacy MemoryStore plane
+    // (MEMORY_BACKEND/EMBEDDING_*) was dropped without migration; `scripts/drop-memory-tables.sql` drops the table.
+    // S3-TOB(设计 §1.3,后经改判与边界重切):backend 选择器——file=现状(单用户/host);pg|tidb=
+    // DB durable 真身(零卷主档:memory/ 文件面=materialize 的 ephemeral 工作副本,harvest 回 DB=持久化
+    // 时点)。DB backend 是多租户点亮的唯一门(显式 opt-in);选了 DB 但池不可用/方言不匹配=fail-loud 拒启
+    // (no-stopgap:绝不静默降 File/dark)。
     let memoryEngine;
+    // 142-S2.5:per-(scope,peer) 同步游标面(sync_cursors)——POST /v1/memory/sync/:scope 的持久化半场。
+    // 只在 DB memory plane 上点亮(file 形态路由 501,不接);与 entry plane 同池同方言。
     let memorySyncCursors;
     if (config.memoryEngineBackend !== "file" && config.memoryEngineEnabled) {
         const dialect = config.memoryEngineBackend;
+        // 142-S5.1 production history sink: every applied patch appends one
+        // agent_memory_engine_history row via the backend's optional history opts. The wrapper's ONLY
+        // job is the metrics leg — count lost rows BEFORE rethrowing (the backend swallows + warns with
+        // its own cumulative count; the audit line's breakage must itself be auditable).
         const countedHistorySink = (store) => ({
             appendHistory: async (rows) => {
                 try {
@@ -471,9 +694,11 @@ async function main() {
             const q = async (text, params) => { const r = await pool.query(text, params); return { rows: r.rows }; };
             await ensurePgMemoryEngineSchema(q);
             await ensurePgMemoryHistorySchema(q);
-            await ensurePgMemorySyncSchema(q);
+            await ensurePgMemorySyncSchema(q); // 142-S2.5: sync_cursors(+push_queue)同池 ensure,幂等
             memorySyncCursors = new PgMemorySyncStore(q);
             const pgMem = new PgMemoryEngineBackend(q, { history: countedHistorySink(new PgMemoryHistoryStore(q)) });
+            // 工作面根:DB 形态下 memory/ 目录=per-worker ephemeral 物化区(丢了重建,控制面同);
+            // 复用 localDataRoot 下独立子树,绝不与 File backend 的持久 memory/ 混写。
             memoryEngine = { backend: pgMem, root: join(config.localDataRoot ?? localRoot, "memory-work") };
         }
         else {
@@ -482,7 +707,7 @@ async function main() {
                 throw new Error("MEMORY_ENGINE_BACKEND=tidb requires DB_BACKEND=mysql/tidb — refusing to start half-configured");
             await ensureTiDBMemoryEngineSchema(pool);
             await ensureTiDBMemoryHistorySchema(pool);
-            await ensureTiDBMemorySyncSchema(pool);
+            await ensureTiDBMemorySyncSchema(pool); // 142-S2.5: sync_cursors(+push_queue)同池 ensure,幂等
             memorySyncCursors = new TiDBMemorySyncStore(pool);
             memoryEngine = { backend: new TiDBMemoryEngineBackend(pool, { history: countedHistorySink(new TiDBMemoryHistoryStore(pool)) }), root: join(config.localDataRoot ?? localRoot, "memory-work") };
         }
@@ -490,6 +715,10 @@ async function main() {
     }
     else {
         memoryEngine = memoryEngineBackendFor(config);
+        // [1845]②(cli 桌面撞坑;壳侧此前同坑已各自修过——两个宿主都踩=第三个宿主还会踩):操作员用
+        // LOCAL_DATA_ROOT 明确要了隔离数据根,MEMORY_ENGINE_DIR 却缺省 ⇒ file 形 memory engine 落 core
+        // 默认链(AGENT_DATA_DIR → ~/.ai-agent)= **静默共享全机 memory 库**。不改行为(单机用户可能就要
+        // 共享),只把「你现在在共享」说出来。
         if (memoryEngine && process.env.LOCAL_DATA_ROOT && !config.memoryEngineDir) {
             logger.warn("memory_engine_dir_defaulted", {
                 root: memoryEngine.root,
@@ -497,6 +726,10 @@ async function main() {
             });
         }
     }
+    // RosterStore(agent-team S1 server 半场,[1070]① 提货单;core 1.316 `RunnerDeps.rosterStore`):
+    // 具名子 agent 持久名册。形态跟 StoreBackend:tidb/pg=SQL twins(语义三条+真双库验证,
+    // roster-store-sql.ts 顶注);local=core FileRosterStore(dataRoot 下 roster.json,core 自带原子写/
+    // 损坏安全);无 backend(纯内存 dev)=不挂(core 用活注册表,跨 run 指针面自然缺席——诚实)。
     let rosterStore;
     {
         const mysqlPool = backend?.mysqlPool?.();
@@ -516,6 +749,15 @@ async function main() {
         if (rosterStore)
             logger.info("roster_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
     }
+    // BackgroundAgentStore(design/151 S1 server 半场,[1503] 提货单;core 1.364 durable background agents):
+    // 后台子代 `a*` 行的 durable 执行记录——settle 后转录 session 不再 eager release(TaskOutput/
+    // AgentTranscript 完成后照读全程),清理移交 reapDurableAgents(reaper 区)。形态跟 roster:
+    // tidb/pg=SQL twins(真双库验证,background-agent-store-sql.ts 顶注);local=core
+    // FileBackgroundAgentStore(dataRoot 下 background-agents/,core 自带 ledger+snapshot 原子写);
+    // 无 backend(纯内存 dev)=不挂(core 契约:store 不接线=pre-151 逐字节等价——单进程 live 注册表
+    // 已覆盖读面,诚实缺席)。⚠️ 同实例双点挂载:RunnerDeps.backgroundAgentStore(读半场)+
+    // ScenarioDeps→SubagentToolOptions.background.agentStore(写半场)都用这一个引用——engine 无法核对
+    // 配对,半接=静默死特性(RB-37①)。
     let backgroundAgentStore;
     {
         const mysqlPool = backend?.mysqlPool?.();
@@ -530,16 +772,28 @@ async function main() {
             backgroundAgentStore = new TiDBBackgroundAgentStore(mysqlPool);
         }
         else if (backend?.kind === "local") {
+            // core 1.368([1516]②)listScopes 落地:file 实现自带枚举——1.248 拍的「local+多租户 reap 缺口」
+            // warn-once 已撤(reaper 腿现在真枚举,不再假设单 scope)。
             backgroundAgentStore = new FileBackgroundAgentStore(config.localDataRoot ?? localRoot);
         }
         if (backgroundAgentStore)
             logger.info("background_agent_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
     }
+    // D-1 通用文件上传(clay 拍 2026-07-27):独立附件 store(不骑 snapshot blob 面——那套的 orphan GC
+    // 会把非 manifest 引用的 bytes 误收;生命周期也不同:附件跟 task/session 绑定)。形态跟 StoreBackend
+    // 三态:tidb/pg=SQL twins(真双库验证)、local=文件店;无 backend(纯内存 dev)=不挂 ⇒ 路由 501。
+    // 四半场:①上传/取回/删除(http/server.ts 路由)②提交时绑定+objective 告知+host lane 物化
+    // (resolveSpec 内,下方)③远程 lane env 建立时物化(executionEnvFactory 包装,下方)④生命周期
+    // (E21 purge 级联 + 未绑定 TTL reaper)。
     let taskAttachmentStore;
     {
         const mysqlPool = backend?.mysqlPool?.();
         const pgPool = backend?.pgPool?.();
         if (pgPool || mysqlPool) {
+            // clay 裁(2026-07-27):**云形态对象存储必配**——附件字节本体进 MinIO(SQL 只存 meta/门/生命周期)。
+            // 复用快照 lane 的同一 MinIO 部署配置(MINIO_ENDPOINT/ACCESS/SECRET,零重映射),但**附件专属
+            // keyPrefix**:对象键=sha256,与快照 blob 同 sha 不同生命周期,同名字空间会互删。未配 ⇒ 附件面
+            // 不接线(路由 501)+ error 级日志——这是部署配置错误,不静默降级回「字节进 DB」(该形已被裁掉)。
             const minio = config.snapshotBlobStore;
             if (!minio) {
                 logger.error("attachments_disabled_object_store_required", {
@@ -565,6 +819,11 @@ async function main() {
         if (taskAttachmentStore)
             logger.info("task_attachment_store_enabled", { backend: pgPool ? "pg+minio" : mysqlPool ? "tidb+minio" : "file", maxBytes: config.attachmentMaxBytes });
     }
+    // S3c(core 1.374 行为车,[1531]):teammate 信箱——SendMessage 对 SETTLED named teammate 的 tier-3
+    // 懒复活链(durable 行解析→claim-CAS→mailbox append→reviveSpawn→attach 屏障后 ack)。激活三件套=
+    // RunnerDeps.mailboxStore + backgroundAgentStore 同挂 + delegation 工具在场,三缺一=1.373 文本字节
+    // 不变(诚实拒)。形态同上:tidb/pg=SQL twins(mailbox-store-sql.ts,发车复审八修顶注);local=
+    // core FileMailboxStore;纯内存 dev=不挂。回执句族(details.error 枚举)wire 透传零改动。
     let mailboxStore;
     {
         const mysqlPool = backend?.mysqlPool?.();
@@ -583,23 +842,35 @@ async function main() {
         if (mailboxStore)
             logger.info("mailbox_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
     }
+    // 142-S5 §1.4: the per-scope export READ face lights up only on the DB memory plane (the multi-tenant
+    // truth lives in the scope-partitioned tables; the file posture exports by copying the memory dir, so
+    // the route 501s honestly there). History-table WRITE wiring: inside the backend construction above
+    // (S5.1, opts.history — the write point lives in the handed-over backend code).
     const memoryExportBackend = config.memoryEngineBackend !== "file" ? memoryEngine?.backend : undefined;
-    const memoryLane = memoryEngineRemoteLanePosture(config);
+    const memoryLane = memoryEngineRemoteLanePosture(config); // N0: worker/sandbox file-plane split posture
     if (config.memoryEngineBackend === "file" || !config.memoryEngineEnabled) {
         logger.info("memory_engine_enabled", memoryEngine
             ? { enabled: true, backend: "file", dir: memoryEngine.root }
             : {
                 enabled: false,
+                // 复审 F-11:按最终门结果报因,多租户 file=隔离判据,其余照旧。
                 reason: config.requirePrincipal === true ? "multi-tenant on the FILE backend (no tenant isolation; set MEMORY_ENGINE_BACKEND=pg|tidb to light up)"
                     : !config.memoryEngineEnabled ? "MEMORY_ENGINE=off"
                         : `remote exec lane "${memoryLane?.lane}" (worker/sandbox file planes split; MEMORY_ENGINE_REMOTE_LANE=allow overrides)`,
             });
     }
+    // N0 boot warn: loud in BOTH postures — "dark" so an upgrade that silently turns memory off is visible,
+    // "forced" so an operator override states what it depends on (harvest only sees the WORKER fs).
     if (memoryLane && config.memoryEngineEnabled && config.requirePrincipal !== true) {
         logger.warn("memory_engine_remote_lane", memoryLane.posture === "dark"
             ? { lane: memoryLane.lane, effect: "memory dark (fail-closed): the file engine works the worker's local fs while this lane routes model file tools to the sandbox fs — sandbox writes are never harvested. Set MEMORY_ENGINE_REMOTE_LANE=allow ONLY if both are one fs." }
             : { lane: memoryLane.lane, effect: "MEMORY_ENGINE_REMOTE_LANE=allow: memory engine ON over a remote lane — harvest only sees files landing on the WORKER fs; verify the lane really shares it." });
     }
+    // 142-S2.5-W1: TOC 同步 client 腿——只在 file memory 形态接线(loadConfig 已拒 DB backend
+    // 上的 MEMORY_SYNC_*,这条分支到不了)。boot 后 fire-and-forget 一轮(失败 warn 不阻断——纯本地现状
+    // 是安全降级面);之后 harvest 真有 patch 落地时再触发(onMemoryHarvestReport 站点,inflight 节流)。
+    // 引擎 dark(多租户/MEMORY_ENGINE=off/remote lane)⇒ 无本地盘可同步:warn 不 throw(dark 的三个成因
+    // 各有自己的 loud 日志在上方,这里补“sync 因此没跑”这半句,operator 可见不半配)。
     let memorySyncRunner;
     if (config.memorySync) {
         if (memoryEngine) {
@@ -609,6 +880,7 @@ async function main() {
                 memoryRoot: memoryEngine.root,
                 transport: createMemorySyncTransport({ url: config.memorySync.url, token: config.memorySync.token }),
                 log: logger,
+                // S2.5 分批(core 1.284):未设=不分批 wire 字节不变;设了=续轮 loop 至收敛(MAX_SYNC_ROUNDS 警戒)。
                 ...(config.memorySync.maxPushEntries !== undefined ? { maxPushEntries: config.memorySync.maxPushEntries } : {}),
                 ...(config.memorySync.maxPullEntries !== undefined ? { maxPullEntries: config.memorySync.maxPullEntries } : {}),
             });
@@ -619,11 +891,18 @@ async function main() {
             logger.warn("memory_sync_configured_but_memory_dark", { note: "MEMORY_SYNC_URL is set but the file memory engine is dark (multi-tenant / MEMORY_ENGINE=off / remote exec lane) — no sync rounds will run" });
         }
     }
-    const sessionStore = createSessionStore(config, backend, metrics);
+    const sessionStore = createSessionStore(config, backend, metrics); // S25: stale-affinity evict fingerprint
+    // S6 startup guard: multi-tenant isolation needs an owner-aware (TiDB) store. Refuse to start with
+    // REQUIRE_PRINCIPAL on an in-memory store that can't enforce session ownership.
     if (config.requirePrincipal && !sessionStore.ownerOf) {
         throw new Error("REQUIRE_PRINCIPAL=true needs an owner-aware session store (SESSION_BACKEND=tidb); " +
             "the in-memory store cannot enforce session ownership.");
     }
+    // The local in-memory backend HAS an ownerOf (LocalSessionStore), so the guard above passes — but its owner map is
+    // process-local + lost on restart, so it cannot DURABLY enforce multi-tenant ownership (post-restart a session id is
+    // re-claimable by whoever attaches first). Refuse REQUIRE_PRINCIPAL on it: a real multi-tenant
+    // boundary needs the durable DB backend; single-user local runs with REQUIRE_PRINCIPAL=false (the principal may
+    // still ride for memory-scoping). The file-backed follow-on (durable owners) can revisit this.
     if (config.requirePrincipal && backend?.kind === "local") {
         throw new Error("REQUIRE_PRINCIPAL=true is not supported on the local file backend (DB_BACKEND=local): session/run CONTENT is " +
             "durable there, but OWNER attribution is process-local and lost on restart (store-backend.ts §0.5 — durable " +
@@ -631,17 +910,27 @@ async function main() {
             "(DB_BACKEND=mysql|pg) for multi-tenant, or run local single-user with REQUIRE_PRINCIPAL=false (a BFF may " +
             "still inject x-agent-principal per request for memory scoping and audit attribution).");
     }
+    // (c)(clay 拍 a+c,2026-07-27)云形快照 blob 姿势门:mysql|pg 后端缺 MinIO ⇒ fail-loud(bytes-in-DB
+    // 撞包墙已两役实证);SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true 显式逃生(单机/测试台,吃 (a) 的 per-blob 帽)。
     if (backend)
         assertCloudSnapshotBlobPosture(backend.kind, config);
+    // Posture warning (audit B, security.ts): an owner-aware store without REQUIRE_PRINCIPAL means the
+    // principal layer is optional per request. Owned sessions are still protected (the authorizer rejects
+    // anonymous/mismatched attach), but new headerless submissions create anonymous sessions any token
+    // holder can attach to — a multi-tenant deployment should set REQUIRE_PRINCIPAL=true.
     if (!config.requirePrincipal && sessionStore.ownerOf) {
         logger.warn("principal_optional", {
             note: "owner-aware session store with REQUIRE_PRINCIPAL=false — owned sessions are protected, but headerless callers can create/share anonymous sessions; set REQUIRE_PRINCIPAL=true for multi-tenant",
         });
     }
     metrics.dynamicGauge("sessions_warm", "Sessions held in the warm cache", () => sessionStore.size);
+    // 1.38 cross-replica circuit-breaker state: shared via TiDB when a pool exists AND the breaker is
+    // enabled; otherwise core's per-process Map (single replica / no DB / breaker off). Refresh loop is
+    // unref'd so it never holds the process open.
     const breakerState = backend?.breaker && config.resilience.circuitBreaker
         ? backend
             .breaker((streak) => {
+            // LOW (SILENT-FALLBACK P1): cross-replica breaker write-through failures were a bare swallow.
             metrics.setGauge("counter_flush_fail_streak", streak, { table: "circuit_breaker", kind: "write_through" });
             if (streak > 0)
                 metrics.inc("breaker_writethrough_failed_total", { backend: backend.kind });
@@ -651,9 +940,15 @@ async function main() {
                 logger.info("breaker_writethrough_recovered", {});
         })
             .startRefresh()
-        : undefined;
+        : undefined; // local omits breaker() → core's per-process Map
     const brain = createBrain(config, { breakerState });
+    // ③ Cost + ④ trace + ⑤ budget (1.37): inject per-model pricing (authoritative costMicroUsd), bridge
+    //    core's content-free trace events to /metrics, and accumulate per-principal spend into the cost
+    //    quota (the tracer reads the principal ALS so council/team sub-task cost is attributed too).
     const pricing = buildPricing(config.models);
+    // S9 (SILENT-FALLBACK P0-e): write-behind flush/refresh failures previously vanished in a bare catch —
+    // the fleet silently degrades to per-replica counting (soft limits stop being fleet-wide). Every failure
+    // ticks the counter + streak gauge; warn once per episode (streak hits 3), info on the recovery edge.
     const counterDegradeHook = (info) => {
         metrics.setGauge("counter_flush_fail_streak", info.streak, { table: info.table, kind: info.kind });
         if (info.streak > 0)
@@ -663,33 +958,79 @@ async function main() {
         else if (info.streak === 0 && info.prevStreak >= 3)
             logger.info("counter_flush_recovered", { table: info.table, kind: info.kind, prevStreak: info.prevStreak });
     };
+    // Per-principal cumulative cost quota: TiDB-backed (cross-replica, atomic write-behind) when a pool
+    // exists, else in-memory per-replica (single-replica / no DB). Both satisfy QuotaTracker. (design/30 P0-1)
     const costQuota = config.maxPrincipalCostUsd > 0
-        ? backend?.costQuota
+        ? backend?.costQuota // local omits costQuota() → in-memory per-process CostQuota (single-replica)
             ? backend.costQuota(Math.round(config.maxPrincipalCostUsd * 1e6), config.costQuotaWindowSec * 1000, counterDegradeHook).startRefresh()
             : new CostQuota(Math.round(config.maxPrincipalCostUsd * 1e6), config.costQuotaWindowSec * 1000)
         : undefined;
+    // E8 (shell-host contract): per-task × per-model usage accumulator, fed by the tracer and drained by the durable run
+    // lifecycle into `model_usage` events (the `TaskStats.modelUsage` echo). One instance, shared tracer↔server.
     const modelUsageTracker = new ModelUsageTracker();
+    // [998]② web 观测切片 A 数据面:prompt.assembled 的 manifest 经 tracer 记录、由 durable run 生命周期
+    // drain 成 `prompt_assembled` 事件(turns/stream 可读)。与 modelUsageTracker 同款 register 篱笆/生命周期。
     const promptManifestTracker = new PromptManifestTracker();
+    // fleet 用量批报的 principal×model 窗口累计器 — 仅当 fleet 面可能启用(center lane 配置了)才建,
+    // 否则 tracer 走 undefined = 零行为(非 fleet 部署不多攒一份内存)。真正的启动门在 startFleetClientFromEnv。
     const fleetUsage = config.configCenter && process.env.FLEET_ADVERTISE_ADDRESS ? new FleetUsageAccumulator() : undefined;
+    // fleet lease 消费(worker 侧第三接线,D4 AP 模式):协商式 —— center lane 配齐即启(lease 是出站消费面,
+    // 不需要 FLEET_ADVERTISE_ADDRESS);非 lease-enforced principal 一次 409 负缓存后走既有本地 CostQuota,
+    // 单用户(无 principal)提交门早退 —— 两者零行为变化。
     const fleetLease = createFleetLeaseFromEnv(config, { logger, metrics });
+    // weight-at-burn 回调:读 config.modelQuotaWeights(registry hot-apply 的活表;env lane 空 ⇒ 1 兜底)。
     const tracer = createTracer(metrics, costQuota, modelUsageTracker, fleetUsage, fleetLease, (m) => config.modelQuotaWeights[m] ?? 1, promptManifestTracker);
+    // [1469] side-query 记账 seam:与 tracer 同一装配点、同一组 sink 实例(codex R3——sideQuery 不发
+    // brain.call,四路 sink 必须由 server 半场喂,两臂同语义见 createSideQueryAccountant 头注)。
     const sideQueryAccounting = createSideQueryAccountant(metrics, costQuota, fleetUsage, fleetLease, (m) => config.modelQuotaWeights[m] ?? 1);
-    const toolResultStore = backend?.toolResult ? backend.toolResult() : undefined;
+    // Durable offload store (core 1.47/1.49): large tool results survive a cross-replica wake. Without a
+    // pool, core's task-scoped in-memory default applies (graceful: cross-wake fetch misses → preview stands).
+    const toolResultStore = backend?.toolResult ? backend.toolResult() : undefined; // tidb/pg = SQL twins; local = core's FileToolResultStore (core 1.219 — restart-durable refs); no backend → core's in-memory default
+    // E6 durable SessionPolicyStore — operator-tightened per-session tool rules core reads at prepare-time (subtract-only).
+    // Present on every backend (incl local = core's InMemorySessionPolicyStore); undefined only on the env-only/no-backend
+    // worker → feature OFF (core reads no rules). Wired into the PRIMARY Runner below + the PUT/GET policy route + E21 purge.
     const sessionPolicyStore = backend ? backend.sessionPolicy() : undefined;
+    // E19 rewind-files — working-tree snapshot/restore keyed by entryId (the same anchor as E18), + the 2c artifact-transfer
+    // store. core AUTOMATICALLY snapshots each completed turn + restores on resumeAt when `spec.rewindFiles` is set, for ANY
+    // ExecutionEnv when this store is wired (gate-split 1.134.0 removed the isRemoteExecutionEnv skip → host/local-mode
+    // + e2b/k8s/ssh/adb/local-docker all active). Durable on tidb/pg (cross-replica + 2c), local = core's
+    // InMemoryFileSnapshotStore. Wired into the PRIMARY Runner + the `rewindFiles` cap + E21 purge.
     const fileSnapshotStore = backend ? backend.fileSnapshot() : undefined;
+    // [805]③a / [806]④: E19-fix observability — core 1.287 captureManifest TOLERATES enumerate→read-window
+    // vanished files (skip, not fail) and reports the count ONLY in its return value; the SQL twins expose it via
+    // this optional sink. Metric = the live face of "the fix is absorbing real races" (a warn would be noise — the
+    // skip is the CORRECT behavior). GAP (honest): the local lane uses core's own store, which drops the count
+    // internally — surfacing it there needs a core seam (noted on the board, not faked here).
     if (fileSnapshotStore && "onSkippedVanished" in fileSnapshotStore) {
         fileSnapshotStore.onSkippedVanished = (count) => metrics.inc("snapshot_skipped_vanished_total", {}, count);
     }
+    // design/48 v1b: deployment-level remote execution(部署级路由 + 懒汉连接). When
+    // REMOTE_EXEC=e2b, this deployment is a "code-agent worker" — each task's hand runs in a per-task E2B VM,
+    // provisioned lazily on first hand use (a plan-only task pays zero VM cost). Unset → in-process stub env.
+    // design/48 v1b + design/61: pick the remote-exec backend by provider (peer adapters). SSH/ADB target REAL
+    // systems (not isolated/suspendable) — the leader's autonomy + the design/37 gate + HITL run accordingly.
+    // §7 P0.5 per-task sandbox image: the trusted-control-plane bridge from resolveSpec (resolves the requested
+    // profile → digest with the caller's principal, fail-closed) to the k8s factory (applies it per-pod). See
+    // per-task-image.ts + resolveSpec below. Worker-global default image is the fallback when no profile is requested.
     const perTaskImage = new PerTaskImageRegistry();
+    // RFC A2: session-keyed environment selection (PROFILE intent, never a digest) written by the model-facing
+    // SelectEnvironment tool; resolveSpec re-resolves it FAIL-CLOSED per task (same re-admit as a body profile).
     const sessionEnvSelection = new SessionEnvironmentSelection();
+    // [#40 / TOC cwd seam] per-session launch dir → the host lane's agent workspace (resolveSpec registers it gated by
+    // cwdHonored; the host factory reads it by ctx.sessionId). Only ever written for the single-user host lane.
+    // BOUNDED (avoid unbounded growth over the persistent local engine's lifetime): an LRU cap; the shell
+    // re-sends cwd on every request, so evicting a stale session is harmless (it re-registers on next use).
     const MAX_CWD_SESSIONS = 4096;
     const perSessionCwd = new Map();
     const setSessionCwd = (sid, cwd) => {
-        perSessionCwd.delete(sid);
+        perSessionCwd.delete(sid); // re-insert at the tail = most-recently-used
         perSessionCwd.set(sid, cwd);
         if (perSessionCwd.size > MAX_CWD_SESSIONS)
-            perSessionCwd.delete(perSessionCwd.keys().next().value);
+            perSessionCwd.delete(perSessionCwd.keys().next().value); // evict oldest
     };
+    // [R-survey / TOC shellEnv seam, core PLAN批注] per-session `settings.env` → the host lane's agent shell env
+    // (resolveSpec registers it gated by cwdHonored — single-user host lane only; the host factory merges it by
+    // ctx.sessionId). design/107 "env = capability axis". Same LRU bound + re-send-on-every-request semantics as cwd.
     const perSessionShellEnv = new Map();
     const setSessionShellEnv = (sid, env) => {
         perSessionShellEnv.delete(sid);
@@ -698,6 +1039,8 @@ async function main() {
             perSessionShellEnv.delete(perSessionShellEnv.keys().next().value);
     };
     let executionEnvFactory;
+    // SVC-3 worktree isolation: the reaper (defined far below) reuses ONE long-lived git base env + repoRoot to
+    // `git worktree prune` crash-orphaned worktrees. Holders are populated when the wrapper is wired (host lane).
     let worktreeReap;
     if (config.remoteExec?.provider === "e2b") {
         executionEnvFactory = e2bExecutionEnvFactory({
@@ -706,7 +1049,11 @@ async function main() {
             ...(config.remoteExec.timeoutMs != null ? { timeoutMs: config.remoteExec.timeoutMs } : {}),
             ...(config.remoteExec.livenessMs != null ? { livenessMs: config.remoteExec.livenessMs } : {}),
             ...(config.remoteExec.allowInternetAccess != null ? { allowInternetAccess: config.remoteExec.allowInternetAccess } : {}),
+            // [1452]/[1454] CWD-A: workspace 根透传(E2B_MOUNT_PATH)——缺省仍 /home/user(adapter 默认)。
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
+            // RFC B5: region package-source env set rides the operator-trusted sandboxEnv — ENV-FIRST, the derived
+            // ecosystem overrides (pip/uv/npm/go/rustup/flutter/…) beat the image's baked CN ENV on existing images,
+            // no rebake needed. Explicit E2B_SANDBOX_ENV keys win over derived on collision (deliberate override).
             ...(() => {
                 const merged = { ...derivePkgSourceEnv(config.sandboxPkgSource, customPkgSourceFromEnv()), ...(config.remoteExec.sandboxEnv ?? {}) };
                 return Object.keys(merged).length > 0 ? { sandboxEnv: merged } : {};
@@ -726,14 +1073,26 @@ async function main() {
             ...(config.remoteExec.runtimeClass != null ? { runtimeClass: config.remoteExec.runtimeClass } : {}),
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
             ...(config.remoteExec.timeoutMs != null ? { timeoutMs: config.remoteExec.timeoutMs } : {}),
+            // Resource-profile knobs. config.ts reads K8S_MEMORY/K8S_CPU; this passthrough was
+            // missing, so the adapter silently stayed on its 2Gi default (Kata VM = default_memory 2G + limit 2G = 4G
+            // MemTotal — task02b run9/10 integration gradle OOM'd there even after the env was set).
             ...(config.remoteExec.memory ? { memory: config.remoteExec.memory } : {}),
             ...(config.remoteExec.cpu ? { cpu: config.remoteExec.cpu } : {}),
             ...(config.remoteExec.s3Snapshot ? { s3Snapshot: config.remoteExec.s3Snapshot } : {}),
+            // RFC B5: region package-source env set → pod container env (operator-trusted, never task-controlled).
+            // ENV-FIRST: pod env beats image ENV and reaches every exec — the derived ecosystem overrides switch
+            // region on existing images; the SEMA_PKG_SOURCE marker drives the in-image hook (file-bound pieces).
             ...(() => {
                 const derived = derivePkgSourceEnv(config.sandboxPkgSource, customPkgSourceFromEnv());
                 return Object.keys(derived).length > 0 ? { podEnv: derived } : {};
             })(),
         };
+        // §7 P0.5: per-pod image override. resolveSpec resolved the requested profile→digest (with the caller's
+        // principal, fail-closed) and registered it by sessionId — the ONLY identifier stable across the factory ctx
+        // on every path (adversarial-review round-2: /v1/runs mints its own durable taskId that CLOBBERS spec.taskId,
+        // so taskId-keying misses on the primary path; sessionId survives). get() is non-removing (the factory may be
+        // invoked >once per logical task). Absent ⇒ the worker-global k8sCfg.image. Building the factory per task is a
+        // cheap closure alloc; the ref is immutable (repo@digest). podSpecPatch can NOT carry the image (hard invariant).
         executionEnvFactory = (ctx) => k8sExecutionEnvFactory({ ...k8sCfg, image: perTaskImage.get(ctx.sessionId) ?? k8sCfg.image })(ctx);
     }
     else if (config.remoteExec?.provider === "ssh") {
@@ -753,10 +1112,20 @@ async function main() {
         });
     }
     else if (config.remoteExec?.provider === "host") {
+        // DUAL-MODE §5: the TOC `host` lane — run on THIS machine, no container (isolation=none). Fan-out still
+        // works (bounded by one box). Secrets are env-NAMEs the host resolves from its own process.env.
         {
+            // R7 self-wake: inject the self-wake SchedulerCapability backend on the single-user TOC host lane
+            // (opt-in SCHEDULER_ENABLED). `hasScheduler(env)` then mounts CronCreate/CronDelete/CronList(旧名 CronCancel、Sleep 已 design/136 撤除——L8 注释订正,且挂载在 core prepare-task 非 createHandsToolkit); the TOC shell
+            // daemon reads the SAME ~/.sema/scheduled_tasks.json store (registry-core /node binding) and fires due intents.
+            // Multi-tenant (requirePrincipal) routes scheduling to center, NOT this host daemon → gate it off there. ONE
+            // backend instance at boot → every host task shares the same store file.
             const hostScheduler = config.schedulerEnabled && config.requirePrincipal !== true
                 ? new FileSchedulerBackend({
                     ...(config.schedulerStorePath ? { storePath: config.schedulerStorePath } : {}),
+                    // [1009]② host-signal: the spawning shell knows whether a resident daemon will honor session
+                    // wakeups — SCHEDULER_SESSION_WAKEUP=false flips the capability off at CONSTRUCTION (instance-
+                    // lifetime snapshot, core TOCTOU 契约) so core's ScheduleWakeup refuses up front.
                     ...(config.schedulerSessionWakeup === false ? { caps: { supportsSessionWakeup: false } } : {}),
                 })
                 : undefined;
@@ -766,21 +1135,37 @@ async function main() {
                 ...(config.remoteExec.workspaceBase ? { workspaceBase: config.remoteExec.workspaceBase } : {}),
                 ...(config.remoteExec.commandTimeoutMs != null ? { commandTimeoutMs: config.remoteExec.commandTimeoutMs } : {}),
                 ...(hostScheduler ? { scheduler: hostScheduler } : {}),
+                // design/103 background shell: single-user host lane only (parity with scheduler/cwd). Multi-tenant host
+                // lane (which shouldn't exist — host runs on the worker's own box) → INERT (run_in_background/etc. don't mount).
                 backgroundShell: config.requirePrincipal !== true,
             };
+            // [#40 / TOC cwd seam] per-request workspace: if resolveSpec registered a caller `cwd` for this session (gated by
+            // cwdHonored — single-user host lane only), run the agent VERBATIM in that dir (persistent, never deleted — the
+            // user's project). Else the boot-time host config (ephemeral random subdir). Mirrors the k8s perTaskImage wrap.
+            // core 1.219 `ctx.parentCwd` (dogfood finding: sub-agents landed in an EMPTY sandbox): a DELEGATED child
+            // (workflow ctx.agent / Task tool) now roots at its PARENT's working dir — CC parity — via core's TRUSTED
+            // RunInternals channel. Precedence in effectiveHostWorkspace: session cwd → parentCwd (unless the child asked
+            // for isolation:"worktree" — that wrapper wins below) → ephemeral. Container lanes never consult this.
             executionEnvFactory = (ctx) => {
                 const cwd = effectiveHostWorkspace(perSessionCwd.get(ctx.sessionId), ctx);
                 const shellEnv = perSessionShellEnv.get(ctx.sessionId);
                 const env = hostExecutionEnvFactory({
                     ...hostCfg,
                     ...(cwd ? { workspaceDir: cwd } : {}),
-                    ...(shellEnv ? { env: shellEnv } : {}),
+                    ...(shellEnv ? { env: shellEnv } : {}), // R-survey: per-task shell env (merged UNDER per-command options.env by the host adapter)
                 })(ctx);
+                // core 1.191: an EPHEMERAL host workspace (no honored `cwd` → a per-task `sema-host-<id>` dir destroy()
+                // rm's) evicts its LSP servers at task-end so a busy server doesn't accumulate one heavy language server per
+                // task. cwdHonored (persistent project) is NOT evicted — its stable root stays warm across turns (CC-parity);
+                // worktree/fan-out is bounded by maxSessions=16. Only wraps when a NodeLspManager is actually active.
                 return lspManager && !cwd ? evictLspOnDestroy(env, lspManager) : env;
             };
         }
     }
     else if (config.remoteExec?.provider === "local-docker") {
+        // DUAL-MODE §5: the TOC `local-docker` lane — a per-task container on THIS machine's docker daemon
+        // (isolation:true, suspendable:false). The base image comes ENTIRELY from config (no docker.io default —
+        // domestic-images iron rule). Secrets are resolved env-NAME→value here (config.ts already did the forward).
         executionEnvFactory = localDockerExecutionEnvFactory({
             image: config.remoteExec.image,
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
@@ -793,10 +1178,24 @@ async function main() {
             ...(config.remoteExec.env ? { env: config.remoteExec.env } : {}),
         });
     }
+    // [848] remote scratchpad: decorate the REMOTE sandbox lanes (e2b/k8s/local-docker/ssh) so each env
+    // lazily `mkdir -p`s `/tmp/scratchpad/<sessionId>` on its FIRST exec — never at factory time (e2b is
+    // lazy-VM; a factory-time exec would force-boot the VM). adb is skipped (no standard /tmp on Android);
+    // host keeps its worker-local scratchpad (ensureScratchpadDir at the envFacts consumer). The envFacts
+    // advertisement below uses the SAME remoteScratchpadDirFor rule, so fact and mkdir can never disagree.
     if (executionEnvFactory && isRemoteScratchpadLane(config.remoteExec?.provider)) {
         executionEnvFactory = withRemoteScratchpad(executionEnvFactory, logger);
     }
+    // SVC-3 (design/97 CORE-6): wrap the factory with git-worktree isolation. When core marks an agent
+    // `isolation:"worktree"` (TRUSTED RunInternals — never a TaskSpec), the wrapper mints a per-agent detached
+    // worktree under the operator-trusted repoRoot; otherwise it passes the base env through untouched. v1
+    // covers the `host` lane (the TOC fan-out lane). Other lanes would need a worktree-ROOTED REMOTE env from
+    // `rootEnvAt` (a follow-on; a host/NodeExecutionEnv worktree is not durable-suspendable — see the plugin
+    // header) — they are left unwrapped here, isolation:"worktree" is then a no-op for them (the base env wins).
     if (config.worktreeIsolation && executionEnvFactory) {
+        // M4 (adversarial-review): a mis-wired WORKTREE_REPO_ROOT must fail LOUD at boot, not per-task at runtime. The
+        // root must exist AND be a git repo (`.git` dir or worktree-link file). On a bad root, log an error + LEAVE
+        // isolation OFF (the factory unwrapped) rather than wiring a factory that throws on every isolated agent.
         const wtRoot = config.worktreeIsolation.repoRoot;
         const wtValid = existsSync(wtRoot) && existsSync(join(wtRoot, ".git"));
         if (config.remoteExec?.provider === "host" && !wtValid) {
@@ -807,29 +1206,56 @@ async function main() {
             });
         }
         else if (config.remoteExec?.provider === "host") {
+            // The SHARED base env that runs `git worktree add/remove/prune` (cwd:repoRoot is passed explicitly by
+            // core on every git call, so this env's own root is irrelevant — it just needs `exec` + git on PATH).
+            // ONE long-lived env per deployment; the reaper reuses it. `inheritEnv:"all"` so the operator's git
+            // config/credentials are visible (this is the operator's own machine + own repo, the TOC posture).
+            // systematic-audit (gate-fail-direction): every worktree-lane RemoteHostExecutionEnv carries the SAME
+            // background-shell gate as the primary host factory (main.ts ~442) — not the env's `?? true` default. The
+            // git-base env is git-ops only (agents run on rootEnvAt below), but gating it keeps the policy uniform / future-proof.
             const gitBaseEnv = new RemoteHostExecutionEnv({ workspaceDir: config.worktreeIsolation.repoRoot, inheritEnv: "all", backgroundShell: config.requirePrincipal !== true });
             executionEnvFactory = withWorktreeIsolation(executionEnvFactory, {
                 repoRoot: config.worktreeIsolation.repoRoot,
                 ...(config.worktreeIsolation.allowedRoots ? { allowedRoots: config.worktreeIsolation.allowedRoots } : {}),
                 ...(config.worktreeIsolation.commit ? { commit: config.worktreeIsolation.commit } : {}),
                 baseEnvForGit: gitBaseEnv,
+                // Host-lane worktree-rooted env: a host adapter in PERSISTENT-DIR mode — its own destroy() does NOT
+                // rm the dir (so core's `git worktree remove` owns teardown), and it keeps the host adapter's secret
+                // scrub + timeout semantics (vs a bare NodeExecutionEnv). inheritEnv defaults to "scrub" (model-driven).
                 rootEnvAt: (dir) => {
                     const env = new RemoteHostExecutionEnv({ workspaceDir: dir, backgroundShell: config.requirePrincipal !== true });
+                    // A worktree root is per-agent + ephemeral (core's `git worktree remove` reclaims it at
+                    // task-end), so evict its LSP servers DETERMINISTICALLY too — not just via the maxSessions LRU backstop. The
+                    // worktree dir IS the LSP cache root (env.cwd), so evict(env.cwd) on destroy hits it. (`lspManager` is declared
+                    // below but this closure only runs per-task, well after it's initialized — same forward-ref as the host factory.)
                     return lspManager ? evictLspOnDestroy(env, lspManager) : env;
                 },
                 logger,
             });
             worktreeReap = () => reapOrphanWorktrees(gitBaseEnv, config.worktreeIsolation.repoRoot, logger);
             logger.info("worktree_isolation_enabled", { provider: "host", repoRoot: config.worktreeIsolation.repoRoot });
+            // BOOT recovery sweep: reap any worktrees orphaned by a crash BEFORE this process started (the periodic
+            // reaper would otherwise wait a full interval). Best-effort, fire-and-forget; never blocks boot.
             void worktreeReap();
         }
         else {
+            // Not a no-op-silent: an operator who set WORKTREE_ISOLATION_ENABLED on a non-host lane should know it
+            // doesn't take effect yet (the worktree-rooted REMOTE env is a follow-on). Fail-loud-ish via a warning.
             logger.warn("worktree_isolation_unsupported_lane", {
                 provider: config.remoteExec?.provider,
                 note: "git-worktree isolation v1 covers only the 'host' lane — isolation:'worktree' is a no-op here (the base env is used). Worktree-rooted remote envs are a follow-on.",
             });
         }
     }
+    // SendUserFile v2(clay 拍 2026-07-14,Plan B 直传):沙箱 lane 的文件源需要「工具执行时拿到当前
+    // 任务的 env」——core 把 per-task env 关在 prepare-task 闭包里(ToolExecuteContext 无 env 面),但
+    // 工厂是我们装配的、工厂 ctx 自带 taskId,包一层登记 taskId→env(destroy 时注销)即可,零 core 改动
+    // (withWorktreeIsolation 同款包装先例)。lane 门+租户门=sandboxSendLaneEnabled(判定依据在其 doc):
+    // e2b/k8s=一任务一沙箱(沙箱文件系统=租户边界)任意租户可用;ssh(后补 2026-07-14)=同一 exec 契约
+    // (timeout 秒×1000/Result shape 同形)直传链零适配,但 peer=一台跨任务共享的常驻真实主机
+    // (sshExecutionEnvFactory 忽略 ctx、destroy=断连不删文件、isolation:false)→「沙箱 scoped 读=租户
+    // 隔离」不成立,与 host 同门单用户 only(requirePrincipal!==true 恒关多租户,不留口子)。
+    // 其余 lane 不包(零开销);签发面未配同样不包。
     const sendUserFileTaskEnvs = (() => {
         const provider = config.remoteExec?.provider;
         if (!config.sendUserFile || !executionEnvFactory || !sandboxSendLaneEnabled(provider, config.requirePrincipal))
@@ -838,6 +1264,11 @@ async function main() {
         executionEnvFactory = registry.wrapFactory(executionEnvFactory);
         return registry;
     })();
+    // D-1 附件物化包装(半场③):env 每次建立(fresh + resume/重建沙箱)都把该 session 绑定的附件写进
+    // 工作目录 `attachments/`。全 lane 统一(host/e2b/k8s/ssh/adb 都走 factory;ExecutionEnv.writeFile
+    // 双向通用);路径与 objective 告知共用 materializedRelPaths(确定性,两处不漂)。**fail-loud**:
+    // objective 已向模型宣告文件在场,静默缺文件=模型按幻影文件行动,比任务失败更糟 ⇒ 写失败即抛
+    // (env 建立失败,任务带明确错误)。链尾最外层:worktree 隔离等内层先定 cwd,附件落在最终 cwd。
     if (taskAttachmentStore && executionEnvFactory) {
         const inner = executionEnvFactory;
         const attStore = taskAttachmentStore;
@@ -850,43 +1281,103 @@ async function main() {
         };
     }
     if (executionEnvFactory) {
+        // k8s (Kata) is isolated; it becomes WORKSPACE-suspendable when an S3 snapshot store is configured
+        // (tar→S3→fresh pod restore — files durable, in-VM memory not); e2b is fully suspendable.
         const isolated = config.remoteExec.provider === "e2b" ||
             config.remoteExec.provider === "k8s" ||
-            config.remoteExec.provider === "local-docker";
+            config.remoteExec.provider === "local-docker"; // a container is a real OS-level isolation boundary
         const suspendable = config.remoteExec.provider === "e2b" ||
             (config.remoteExec.provider === "k8s" && !!config.remoteExec.s3Snapshot);
+        // Out-of-band sandbox env (e2b): log the KEY NAMES only (never the secret values) so ops can confirm
+        // injection is active without leaking the credential.
         const sandboxEnvKeys = config.remoteExec.provider === "e2b" ? Object.keys(config.remoteExec.sandboxEnv ?? {}) : [];
         logger.info("remote_exec_enabled", { provider: config.remoteExec.provider, isolated, suspendable, ...(sandboxEnvKeys.length > 0 ? { sandboxEnvKeys } : {}) });
         if (!isolated)
             logger.warn("remote_exec_real_system", { provider: config.remoteExec.provider, note: "non-isolated target — actions are permanent; rely on the policy gate + HITL (design/61 §5)" });
     }
+    // LSP sidecar (design/64 §13.1, the 1.86.2 seam): ONE stateless manager on RunnerDeps — core passes each
+    // task's env into sessionFor at the tool mount point, so the manager reaches the SAME sandbox the agent edits
+    // (no sessionId registry / per-task construction). Opt-in (LSP_ENABLED — the SANDBOX lane's knob; the host lane
+    // below has its own, LSP_HOST_ENABLED, because its default is the opposite); with the baked `sema-code-lsp`
+    // template the first call is fast, without it the language server installs on first use (slow once per sandbox).
+    // k8s lane (gate#2 alignment): same manager/bridge over the pod network — `ws://podIP:port` instead of E2B's
+    // public wss proxy, so it needs an IN-CLUSTER worker and a sandbox image with node + the language servers baked
+    // (no on-the-fly npm path on Kata; a miss degrades the lsp tool gracefully, same as E2B).
     const lspProvider = config.remoteExec?.provider;
     const lspManager = (lspProvider === "e2b" || lspProvider === "k8s") && config.lspEnabled
         ? createE2bLspManager({ log: (event, fields) => logger.info(event, fields), scheme: lspProvider === "k8s" ? "ws" : "wss" })
-        :
+        : // TOC local LSP (core 1.190): the host lane runs on THIS machine, so core's `NodeLspManager` spawns the
+            // language server as a LOCAL child_process over stdio (CC `services/lsp` parity). Its default resolveRoot uses
+            // `env.cwd` — and core passes each task's executionEnv (the per-agent WORKTREE env, so the server roots in the
+            // worktree not the base repo) into sessionFor. host ONLY: ssh/adb target another host/device and local-docker a
+            // container, none of which a local child_process can reach (those keep the E2B-style bridge / stay degraded).
+            // 🔒 `requirePrincipal !== true` gate = uniform with the sibling host powers (scheduler/backgroundShell/
+            // loadProjectMemory): the host lane is single-user by design; a (discouraged) multi-tenant host fails SAFE to
+            // grep/read rather than fanning a per-tenant×language×root pool of heavy language servers (double-review B).
             lspProvider === "host" && config.lspHostEnabled && config.requirePrincipal !== true
                 ? new NodeLspManager({ log: (event, fields) => logger.info(event, fields) })
                 : undefined;
     if (lspManager)
         logger.info("lsp_enabled", { provider: lspProvider });
+    // prove-before-scale stopgap: a no-op tool tracer (logs every tool call incl. resumed legs that
+    // /events hides) so we can diagnose single-agent coding behaviour. Off unless TOOL_TRACE=true.
     const toolTracer = config.toolTrace ? createToolTracer(logger) : undefined;
     if (toolTracer)
         logger.info("tool_trace_enabled", {});
+    // Goal B4 (2026-07-08): the ALWAYS-ON gate-deny meter (`permission_denied_total{source}`) — an
+    // operational/security signal that must not sit behind the TOOL_TRACE diagnostic switch. Composed
+    // UNDER the tracer (deployment slot order: meter first, tracer second — composeHooks double-runs the
+    // void permissionDenied slot); this composite is what every hooks site below uses as the deployment
+    // baseline, so a task-hooks fold (resolveSpec) shadows neither.
     const deploymentHooks = toolTracer ? composeHooks(createPermissionDeniedMeter(metrics), toolTracer) : createPermissionDeniedMeter(metrics);
+    // S8 / SVC-1 workflow run store (design/97 S1b): records LLM-authored BACKGROUND workflow
+    // runs for the /v1/workflows list+detail view (live subscribe is in-process via subscribeWorkflow,
+    // store-independent). Only present when self-orchestration is enabled (else no runs to record).
+    //
+    // SVC-1: the DEFAULT is now `FileWorkflowRunStore` (durable, crash-safe ledger) — NOT InMemory — so a
+    // background workflow's record SURVIVES a replica restart, which is the prerequisite for the at-least-once
+    // completion notify below to re-derive a run's terminal state after a crash. InMemory stays available only for
+    // an explicit ephemeral opt-out (WORKFLOW_RUN_STORE=memory); a durable cross-replica TiDB/PG WorkflowRunStore
+    // is a clean follow-on port (the workflowRunStoreContract makes it a drop-in like the run-store).
+    // P1 (fleet failover, 2026-07-05): `auto` (the default) prefers the SQL backend's cross-replica twin when
+    // present — a failover-landed session sees the run's history + its pending completion push on ANY replica.
+    // Explicit WORKFLOW_RUN_STORE=file/memory still wins (single-box File posture unchanged: local backend has
+    // no workflowRun() so auto falls to File there).
     const sqlWorkflowRunStore = config.workflowRunStoreBackend === "auto" ? backend?.workflowRun?.() : undefined;
     const baseWorkflowRunStore = config.selfOrchestrationEnabled
         ? config.workflowRunStoreBackend === "memory"
             ? new InMemoryWorkflowRunStore()
             : (sqlWorkflowRunStore ?? new FileWorkflowRunStore(join(config.localDataRoot ?? localRoot, "workflows")))
         : undefined;
+    // SVC-1 at-least-once completion-notify TRUST GATE (the half that is service's, [[core-service-boundary]]):
+    // core's `run_workflow` fires an in-process at-MOST-once notify on terminal — a crash between terminal and the
+    // receiver loses it. The gate makes it at-LEAST-once: a durable notify-journal records every STARTED run
+    // (observed via the JournalingWorkflowRunStore decorator's `put`), the LIVE notify path delivers-then-acks, and
+    // a BOOT recovery sweep re-derives every un-acked run's terminal state from the run store + re-delivers (the
+    // receiver is idempotent on runId). The default journal is the zero-dependency crash-safe File ledger; with no
+    // run store (self-orchestration off) there's nothing to journal, so the gate is absent.
+    // 1.108 review fix (lens③ HIGH): the journal FOLLOWS the run-store axis like the inbox — a SQL run store +
+    // inbox with a replica-LOCAL File journal meant a replica that died holding an un-acked notify stranded it
+    // forever (no surviving replica could recover it: at-least-once silently degraded to at-most-once across
+    // replica death — the exact fleet-failover gap P1 exists to close).
     const workflowNotifyJournal = config.selfOrchestrationEnabled && config.workflowRunStoreBackend !== "memory"
         ? (sqlWorkflowRunStore ? backend.notifyJournal() : new FileWorkflowNotifyJournalStore(join(config.localDataRoot ?? localRoot, "workflows")))
         : undefined;
+    // P1 ①②: the async-workflow COMPLETION INBOX — the push half. A finished background
+    // workflow's completion is enqueued here keyed by the ORIGINATING session, and drained + emitted as a
+    // `workflow_complete` out-of-band SSE frame when that session next opens a stream (see server.ts). File-backed
+    // (crash-safe) when self-orchestration is on with a durable store; the ephemeral opt-out uses in-memory.
+    // P1: the inbox FOLLOWS the run-store choice (one axis, no split-brain: a SQL run record with a File inbox
+    // would re-open the cross-replica double-push the fence rows exist to close).
     const workflowCompletionInbox = config.selfOrchestrationEnabled
         ? config.workflowRunStoreBackend === "memory"
             ? new InMemoryWorkflowCompletionInbox((msg, meta) => logger.warn(msg, meta))
             : (sqlWorkflowRunStore ? backend.completionInbox((msg, meta) => logger.warn(msg, meta)) : new FileWorkflowCompletionInbox(join(config.localDataRoot ?? localRoot, "workflows"), (msg, meta) => logger.warn(msg, meta)))
         : undefined;
+    // The deployment's REAL completion delivery: log + meter, THEN push into the originating session's inbox so the
+    // model that launched the workflow learns it finished (the `WorkflowStatus` poll is the deterministic floor;
+    // this is the proactive push). The gate guards this so it fires at-least-once + at-most-once-per-run-steady.
+    // `runStore` (below) is resolved at CALL time (post-boot) — a forward reference into the same boot scope.
     const deliverWorkflowCompletion = async (p) => {
         logger.info("workflow_completed", {
             runId: p.runId,
@@ -894,12 +1385,20 @@ async function main() {
             ...(p.sourceTaskId ? { sourceTaskId: p.sourceTaskId } : {}),
         });
         metrics.inc("workflow_runs_total", { status: p.status });
+        // Routing (core 1.208): session = payload's `originatingSessionId` (lookup-free); owner = run-row
+        // owner → payload `principal` (= VERIFIED spec.principal, the 1.55 F-fix invariant — covers the sync/resume
+        // legs whose sourceTaskId is a sessionId and misses getRun) → multi-tenant fail-closed /
+        // single-user null. Full rationale on `resolveCompletionRoute` (tested there).
         if (!workflowCompletionInbox)
             return;
         try {
             const route = await resolveCompletionRoute(p, runStore ? (id) => runStore.getRun(id) : undefined, config.requirePrincipal === true);
             if (!route)
-                return;
+                return; // no route / unverifiable owner → the WorkflowStatus poll floor covers it
+            // `p.summary` is HUMAN-READABLE at the source since core 1.232 (completed lane = bounded
+            // one-liner with name/elapsed/agents + a TaskOutput pointer; failed lane = the bounded redacted error)
+            // — pass through verbatim, single-sourced (the 1.101.0 service-side re-wrap was superseded by core's
+            // own half and removed to avoid two drifting formats).
             await workflowCompletionInbox.enqueue({
                 sessionId: route.sessionId,
                 owner: route.owner,
@@ -918,33 +1417,93 @@ async function main() {
             onError: (stage, runId, err) => logger.warn("workflow_notify_failed", { stage, runId, err: String(err) }),
         })
         : undefined;
+    // MF-Fleet (data contract): the in-process fleet aggregation bus backing GET /v1/fleet/stream. Created HERE
+    // (before the workflow run store) so the JournalingWorkflowRunStore can publish workflow rows to it. Always
+    // present (lightweight); the run (POST /v1/runs) + workflow lifecycle publish per-row deltas. Replica-local.
     const fleetBus = new FleetEventBus();
+    // The store handed to core (+ the /v1/workflows reader): ALWAYS wrapped when a run store exists ([1262]
+    // fleet decoupling) — the wrap publishes the workflow's MF-Fleet row on each put/update (the write-observation
+    // point the shell's /workflows panel lives on), and ADDITIONALLY journals the start-time `put` when the notify
+    // gate is active (durable backends). The old `baseWorkflowRunStore && workflowNotifyGate` guard silently
+    // dropped the FLEET half on the memory backend (gate needs a durable journal; fleet needs neither) — clay's
+    // workflow panel went empty on exactly that shape.
     const workflowRunStore = baseWorkflowRunStore
         ? new JournalingWorkflowRunStore(baseWorkflowRunStore, workflowNotifyGate, fleetBus)
         : undefined;
+    // SVC-2 (core CORE-7/CORE-9 Part A): the durable resume journal. core 1.145.0 added `RunnerDeps.workflowJournalStore`
+    // (twin of workflowRunStore) + auto-wires it into the run_workflow tool's startWorkflow(RunWorkflowOptions.journalStore);
+    // the tool's `resumeFromRunId` input then replays the longest unchanged prefix. tidb/pg = durable cross-replica resume;
+    // local = core's InMemory (single-process — in-process resume only, not restart-durable). Only when self-orchestration
+    // is on AND a backend is present (the load-bearing journal needs a real store).
     const workflowJournalStore = config.selfOrchestrationEnabled && backend ? backend.workflowJournal() : undefined;
+    // design/73 §1 consumption sink (see RunnerDeps.onTaskOutcome below). Present whenever a StoreBackend is —
+    // NOT gated on self-orchestration (goal-mode/harness emissions are orthogonal to workflows).
     const outcomeSink = backend?.outcomeSink();
+    // SVC-5 (CORE-9 Part B): the process-local registry of STEERABLE workflow-agent handles live on THIS replica,
+    // backing POST /v1/workflows/:id/agents/:label/steer. core 1.145.0 added `RunnerDeps.onWorkflowAgentSpawn` (the
+    // opt-in deployment handle-sink): when set, the run_workflow tool's `agent()` runs steerable + emits the handle
+    // HERE (the handle is a core object handed only to the trusted deployment sink — it NEVER enters the script/runner,
+    // so the script-sandbox host-context membrane stays closed). We register by runId+label; the steer route looks it up + calls
+    // handle.steer (core fences via CORE-5) behind our steer-in redaction + owner gate.
     const workflowAgentRegistry = config.selfOrchestrationEnabled ? new WorkflowAgentRegistry() : undefined;
+    // C2 (core 1.219): the replica-local registry of STEERABLE Task-subagent handles, backing
+    // POST /v1/runs/:runId/subagents/:target/steer. Core emits a handle to the per-run `onSubagentSpawn` sink
+    // (wired in each run leg) the moment a SYNC delegation spawns; the handle never reaches the model. Always
+    // present (lightweight Map) — the sink is only threaded where a durable runId exists to address it by.
     const subagentSteerRegistry = new SubagentSteerRegistry();
+    // E23 (shell-host contract): inbound MCP elicitation coordinator (live-only HITL). Present ONLY when MCP_ELICITATION_ENABLED
+    // — absent ⇒ onElicit is not wired ⇒ core advertises no elicitation capability to any server (fail-closed). Shared
+    // by the runner (the onElicit seam) and the HTTP layer (the respond route + the per-run ALS context wraps).
     const elicitation = config.mcpElicitation.enabled ? new ElicitationCoordinator(config.mcpElicitation.throttle) : undefined;
+    // §4④: AskUserQuestion LIVE-stream HITL coordinator — the sibling of `elicitation`. Present ⇒ wired onto
+    // `RunnerDeps.onQuestion` (core mounts the AskUserQuestion tool + routes live asks here) AND consumed by the HTTP layer
+    // (the `POST /v1/questions/:id/respond` route + the per-run ALS context wraps on the streaming legs). Absent ⇒ core
+    // mounts the tool with the headless default (a run never hangs; the model just can't get a live answer).
     const question = config.askQuestionEnabled ? new QuestionCoordinator() : undefined;
+    // [816]/[820]②: the live tool-approval HITL coordinator — the sibling of `question` on core's `RunnerDeps.onAsk`
+    // seam (1.290 sync-ask leg). Present ⇒ a policy `ask` on a LIVE streaming leg becomes a `tool_approval` frame the
+    // shell renders as the CC three-choice card, answered via POST /v1/tool-approvals/:id/respond.
+    // [1535] 正名(旧文「background/workflow ⇒ headless auto-deny stands」已过时):宿主 sync 腿现同时装
+    // `spec.onAsk = boundAsk(ctx)`(server.ts 装配点)——core 继承链把闭包冻给委派子代,**bg/嵌套子代的
+    // ask 浮到宿主 live 流**(带 sourceTaskId);真正无宿主流的腿(durable-submit/headless resume)才留
+    // 「unavailable → durable park;无 park 设施 core fail-closed deny」。durable 部署 G1 语义不变。
     const toolApproval = config.toolApprovalEnabled ? new ToolApprovalCoordinator() : undefined;
+    // [1.294 G1] durable 姿势必须在 runnerDeps 字面量之前可判(onAsk 的「在场性」本身就是 core suspendAsk 的
+    // 分路条件,不能再靠闭包惰性读)——判据与 checkpointStore 的构造条件同源(backend?.checkpoint 存在 ∧
+    // DURABLE_APPROVAL;store 本体已上移至 subRunner 构造前,[1535] 断点② 双 Runner 挂载)。
     const durableEnabled = backend?.checkpoint !== undefined && config.durableApproval === true;
+    // SendUserFile(真 CC 契约,clay 2026-07-14)两种 lane 形态,其余缺席=诚实(工具不进 roster):
+    //  - host lane:本地盘读+服务端上传,【单用户 only】——host 多租户=任意路径读→公网 URL 的 exfil 面,
+    //    clay 拍永久关死,不留口子。路径=绝对或相对 process.cwd(用户目录语义,与 CC 一致)。
+    //  - e2b/k8s lane(v2,Plan B 直传):沙箱内 stat+`curl -T` 打 server 预签的单对象 PUT(字节不中转、
+    //    凭据不进沙箱);沙箱自身文件系统=租户边界,故任意租户可用。
+    //  - ssh lane(后补 2026-07-14):同一直传链,但 peer=跨任务共享的真实主机(非租户边界)→
+    //    【单用户 only】,租户门在 sandboxSendLaneEnabled(多租户下注册表不建,工具诚实缺席)。
+    //    adb/local-docker 仍后补。
+    // 签发面缺 S3_PUBLIC_ENDPOINT 时 issue-time fail-loud(工具在但用即报修法);100MiB/文件帽在各 send 面。
     const sendUserFileEmitter = (() => {
         if (!config.sendUserFile)
             return undefined;
         if (sendUserFileTaskEnvs)
-            return new SendUserFileEmitter();
+            return new SendUserFileEmitter(); // e2b/k8s/ssh(单用户):注册表已就位(lane+租户+签发面判定)
+        // unset REMOTE_EXEC(in-process/TOC 本地形态)有意归入 host 语义:exec 与文件都在本机,单用户门
+        // 同样把关(codex 复审提出收紧到显式 "host";判定=不收——unset 单机+配了 S3 是合法 dev/TOC 场景,
+        // 且与 1.187.0 已发行为一致;真正的红线是 requirePrincipal 多租户,这里恒关)。
         const provider = config.remoteExec?.provider ?? "host";
         if (provider === "host" && config.requirePrincipal !== true)
             return new SendUserFileEmitter();
         return undefined;
     })();
+    // SendUserFile 账本(多租户治理面,[768]②a 后半):key 里的 scope 段是哈希(URL 不泄 principal),
+    // 按租户列/撤销的 scope↔对象映射记在 server 侧账本(四后端孪生,sendfile_link / JSONL)。有 backend 即建
+    // (签发面也配了才有写点);无 backend(env-only worker)= 无账本 = 不记账不 501 治理面(诚实缺席,
+    // capabilities.sendUserFileLedger=false)。
     const sendFileLedger = config.sendUserFile && backend ? backend.sendFileLedger() : undefined;
     const sendUserFileToolSpec = (() => {
         if (!sendUserFileEmitter || !config.sendUserFile)
             return undefined;
         const issuer = createSendUserFileIssuer(config.sendUserFile);
+        // 两条 lane 的 send 都把 ctx.principal(core VERIFIED)传给签发面 → key 带哈希 scope 段 + link 携原文 scope。
         const rawSend = sendUserFileTaskEnvs
             ? createSandboxFileSend({
                 registry: sendUserFileTaskEnvs,
@@ -959,10 +1518,13 @@ async function main() {
                 if (st.size > SEND_USER_FILE_MAX_BYTES)
                     throw new Error(`file exceeds the ${Math.floor(SEND_USER_FILE_MAX_BYTES / (1024 * 1024))} MiB per-file cap (${st.size} bytes)`);
                 const bytes = await fsReadFile(resolved);
+                // 读后复验(codex 复审 MED):stat→read 间文件可增长——上传的是读到的字节,帽必须按真实字节数把关。
                 if (bytes.byteLength > SEND_USER_FILE_MAX_BYTES)
                     throw new Error(`file exceeds the ${Math.floor(SEND_USER_FILE_MAX_BYTES / (1024 * 1024))} MiB per-file cap (${bytes.byteLength} bytes)`);
                 return issuer.issue(bytes, basename(resolved), undefined, sendCtx.principal);
             };
+        // 账本写点(两 lane 同语义):上传+verify 成功后、file_link 帧前记账;记账失败=该文件 fail-loud +
+        // best-effort 删已传对象(治理面必须有行;删失败 warn)。无账本(env-only)= 直通,行为与 1.189 一致。
         const send = sendFileLedger
             ? withLedgerRecording(rawSend, {
                 ledger: sendFileLedger,
@@ -972,11 +1534,43 @@ async function main() {
             : rawSend;
         return sendUserFileTool({ send, emitter: sendUserFileEmitter });
     })();
+    // design/99 §K (core 1.157 `RunnerDeps.runtimeCapsResolver`) — the ENFORCE last-link of the
+    // three-stage workflows gate. core calls it once per task at prepare time with `spec.principal`; we resolve the
+    // per-principal entitlement from center's `GET /api/config/effective?principal=` (cached + fail-closed). Wired
+    // ONLY when a center is configured AND not in dry-run: in dry-run the service pulls+logs but does NOT APPLY
+    // center config, so it must NOT ENFORCE center's per-principal caps either (enforcing would deny workflows = a
+    // real behavior change, contradicting observe-only). Absent ⇒ core sees `undefined` ⇒ no per-principal
+    // restriction (the deployment-level capability + toolPolicy gates still govern).
+    //
+    // 🔐 TRUST DEPENDENCY: the gate keys off `spec.principal` (= resolveSpec's `auth.principal`). F-fix (2026-07-01,
+    // core-steered; contract-compliance per core 1.187's hardened `TaskSpec.principal` doc — it MUST be the
+    // cryptographically VERIFIED identity, never a spoofable header): `auth.principal` now comes from
+    // `verifiedPrincipal` (security.ts). On a GATED door that's `principalFrom` (the BFF already verified the header;
+    // `gatedPrincipal === principalFrom` there); on a DIRECT door (`directDoorActive`) it's the verified
+    // `x-approval-principal-token` JWT `sub`, NEVER the spoofable header. So `spec.principal` is ALWAYS the verified
+    // identity — governance (this gate), cost, and isolation key off it safely on BOTH postures. The same verified
+    // identity also fans out to the non-authorizer owner/cost sites that don't run createAuthorizer
+    // (runOwnerOk / quotaExceeded / leader / idemKey — they call `gatedPrincipal` directly). The invariant:
+    // spec.principal AND every principal-keyed security decision are VERIFIED. (Was a real direct-door spoof hole
+    // before this fix; latent until a multi-tenant direct door ships, but it is the only wall against it.)
+    // wpt_ scoped-token: RESOLVED (center ruling, sema-registry `aeb4979`). The earlier 1.14.0 guard
+    // (skip the resolver on a `wpt_` token, because center 403'd it for `?principal=`) is GONE — center now lets a
+    // worker-scoped `wpt_<self>` resolve its OWN worker's principal caps when we pass `?worker=<self>` (caps-only,
+    // never others' config). So we ALWAYS wire the resolver (configCenter + !dryRun) and pass `worker` =
+    // `SEMA_REGISTRY_WORKER` — it authorizes the wpt_ path and is harmless on a full token (caps are worker-
+    // independent). Per-principal workflow gating now truly works on the scoped-token topology (no more silent
+    // fleet-wide deny). (A wpt_ with no worker still 403s → fail-closed deny, the correct degrade.)
+    // MISCONFIG diagnostic (review MEDIUM): a wpt_<self> token with NO SEMA_REGISTRY_WORKER will 403 every caps
+    // fetch → fail-closed DENY ALL workflows (correct degrade, but otherwise only per-task warns). One-shot BOOT
+    // warning so it's diagnosable. (The orchestrator normally injects the worker alongside a wpt_ — hand-misconfig.)
     if (config.configCenter && !config.configCenter.dryRun && scopedTokenNeedsWorker(config.configCenter.token, config.configCenter.worker)) {
         logger.warn("runtime_caps_scoped_token_no_worker", {
             reason: "SEMA_REGISTRY_TOKEN is a worker-scoped wpt_ token but SEMA_REGISTRY_WORKER is unset → center 403s per-principal caps → ALL workflow self-orchestration will be fail-closed denied. Set SEMA_REGISTRY_WORKER (the orchestrator normally injects it) or use the full SERVICE_PULL_TOKEN.",
         });
     }
+    // ONE per-principal caps client serves two faces off the same fetch/cache — `resolveRuntimeCaps`
+    // (core's seam, fail-closed) and `scenarioRuling` (resolveSpec's scenario gate, fail-open; center attaches the
+    // resolved {scenario, allowlist} to the caps body, single semantic source in center resolve-scenario.ts).
     const principalCaps = config.configCenter && !config.configCenter.dryRun
         ? createPrincipalEntitlementsClient({
             baseUrl: config.configCenter.baseUrl,
@@ -985,23 +1579,55 @@ async function main() {
             onError: (err, principal) => logger.warn("runtime_caps_resolve_failed", { principal, err: String(err) }),
         })
         : undefined;
+    // 「entitlement resolver wired」语义源(enableForkFromBody / selfOrchestrationFromBody 的多租户 fail-close
+    // 判别):只有 center 背书的 caps client 算数 —— 下面的 env observer 基线不是 entitlement 源,不得改变它。
     const centerRuntimeCapsResolver = principalCaps?.resolveRuntimeCaps;
+    // observer 开闸线 env 半场:EXPERIMENTAL_OBSERVER_AGENTS=true → 单用户部署把
+    // allowObservers:true 作部署基线合成(center caps 带键则 center 赢);多租户不认 env(boot warn 一次,
+    // 行为零变)。center caps 的 allowObservers 键本身在 toCoreRuntimeCaps 宽读透传(缺键=core 默认 OFF)。
     const runtimeCapsResolver = applyObserverEnvOptIn(centerRuntimeCapsResolver, {
         experimentalObserverAgents: config.experimentalObserverAgents,
         requirePrincipal: config.requirePrincipal,
         warn: (msg, fields) => logger.warn(msg, fields),
     });
+    // S8 (design/98) + SVC-1: mount core's `run_workflow` under the hardened-vm sandbox when
+    // enabled (default OFF → core fail-closed, tool not mounted, zero impact). The tool STARTS a workflow and
+    // returns its runId IMMEDIATELY (the background-run half — the caller never blocks); the workflow runs to
+    // terminal in the background and fires core's in-process completion notify. Workflow-spawned children inherit
+    // a CONSERVATIVE baseline (handsReadOnly — read-only by default; loosen deliberately); the script may pick
+    // ONLY allow-listed model names (empty ⇒ it cannot pick → the workflow's default role).
+    //
+    // design/158 S4:三处装配点里**唯一**一组多键条件段 —— 提成带类型标注的中间 const 再整体展开进
+    // runnerDeps。标注位 `Pick<RunnerDeps, …>` 本身触发 TS 多余属性检查(键名写错 / 键根本不属于
+    // RunnerDeps ⇒ 编译期红),所以这不是把旁路挪个地方;组内可选键一律写成显式
+    // `k: cond ? expr : undefined`,不再用 `...(cond ? { k } : {})`。
     const workflowModelAllowlist = workflowModelAllowlistFor(config);
     const selfOrchestrationDeps = config.selfOrchestrationEnabled
         ? {
+            // worker_thread isolation (heap cap + terminate) when opted in (multi-tenant DoS hardening), else
+            // the faster in-process runner. Both run the same conformance-validated + probe-hardened membrane.
             workflowScriptRunner: config.selfOrchestrationWorkerIsolation
                 ? createWorkerHardenedVmRunner()
                 : createHardenedVmRunner(),
             workflowRunStore: workflowRunStore ? workflowRunStore : undefined,
+            // SVC-2 (CORE-9 Part A): durable resume journal — core auto-wires it into the tool's startWorkflow, the
+            // `resumeFromRunId` tool input then replays the unchanged prefix (cross-replica when tidb/pg-backed). The
+            // store enforces scope in its WHERE (CORE-9 audit BLOCKER: a cross-tenant resumeFromRunId → empty → live).
             workflowJournalStore: workflowJournalStore ? workflowJournalStore : undefined,
+            // 切片 1.5 / design/140 §6: the named-workflow registry seam — a COMPOSITE store.
+            // persist/load = core's file store under `<localDataRoot>/workflow-scripts` (the CC scriptPath-iterate
+            // face: every invocation's script lands on disk, the model edits + re-invokes with {scriptPath};
+            // containment is the file store's contract). resolveName consults the collab projection FIRST (center
+            // collab templates as `{TEAM_DISCUSSION_SCRIPT, defaultArgs}` entries; a collab id equal to a built-in
+            // name SHADOWS it — §6 1c) and falls back to the file store's `<name>.js` face (an operator-saved
+            // script is a named workflow too). list() = collab entries only (the file store deliberately doesn't
+            // enumerate — its dir mixes per-run scripts with saved names, core contract note); sync, so the
+            // entries reach the statically-built Workflow tool card.
             workflowScriptStore: (() => {
                 const fileStore = createFileWorkflowScriptStore(join(config.localDataRoot ?? localRoot, "workflow-scripts"));
                 return {
+                    // core 1.366 (B-4) scope 分区一致性标:persist/load 直转 core file 实现(per-scope 子目录,
+                    // 真分区)——标是诚实声明;缺标=core 工具读侧拒/写侧跳(编译期必填字面量即为此设计)。
                     scopePartitioned: true,
                     persist: fileStore.persist.bind(fileStore),
                     load: fileStore.load.bind(fileStore),
@@ -1009,22 +1635,55 @@ async function main() {
                     list: () => listCollabWorkflows(),
                 };
             })(),
+            // SVC-5 (CORE-9 Part B): the opt-in steer handle-sink. When set, the tool's `agent()` runs STEERABLE and
+            // emits the live handle HERE (never into the script/runner — the host-context membrane stays closed). We
+            // register it by runId+label so POST /v1/workflows/:id/agents/:label/steer can route a steer to it, and
+            // unregister when the agent settles (result() settles on stream completion; a stale handle would only
+            // 409 `steering.not_running` anyway — this just bounds the map). A steered agent is NOT journaled (CORE-9.1
+            // limitation: its resume re-runs live), which is correct + documented.
             onWorkflowAgentSpawn: workflowAgentRegistry
                 ? (handle) => {
                     const unregister = workflowAgentRegistry.register(handle);
                     void Promise.resolve(handle.result()).then(unregister, unregister);
                 }
                 : undefined,
+            // workflowSizeGuideline: advisory size guidance injected into the
+            // Workflow tool card (core Wvs, CC 206 verbatim). Absent/unrestricted = byte-compat card.
             workflowLimits: config.workflowSizeGuideline ? { sizeGuideline: config.workflowSizeGuideline } : undefined,
             workflowGovernanceBaseline: {
+                // [824]① clay 拍 A 案(workflow 权限全面 CC parity):默认基线撤 handsReadOnly 钳 —— 主 LLM 与
+                // 子 agent 同 root 同信任域,主 LLM 本就能写这棵树([816] ask 门照管),单独钳子 agent 的安全增益≈0
+                // (只防绕路不防直路的门不是边界);实测产品代价=[814]A 死锁(写型 workflow agent 永远只读)。并发
+                // 写互踩按 CC 同姿用建议解决(worktree 契约话术+design/111 advisory),不用强制钳。要保守的 TOB
+                // 部署自己开 WORKFLOW_AGENTS_READONLY=true(config.workflowAgentsReadOnly)加回旧钳。
                 base: config.workflowAgentsReadOnly ? { handsReadOnly: true } : {},
+                // [824]②/[826]-core 1.291 worktree seam(TOB 旋钮回归腿):旋钮开启时 worktreeBase 配成
+                // overlay 形状 —— core 对 `agent({isolation:"worktree"})` 做 base 浅合并(非整体替换,
+                // workflow-primitives effectiveBaseline:{...base,...worktreeBase}),{handsReadOnly:false} 语义=
+                // 「只放写,其余基线全保留」。效果:保守部署里非隔离子 agent 仍只读,进了自有 worktree 的
+                // agent 恢复可写([814]A 写型 workflow 在 TOB 形态下不死锁)。A 案默认(旋钮 off)不配 worktreeBase。
                 worktreeBase: config.workflowAgentsReadOnly ? { handsReadOnly: false } : undefined,
+                // Model allowlist for the script's `agent({model})` picks: explicit
+                // SELF_ORCHESTRATION_MODELS wins; single-user defaults to the deployment's own catalog; multi-tenant
+                // keeps core's fail-closed empty default. Decision + rationale in workflowModelAllowlistFor.
                 workflowModelAllowlist: workflowModelAllowlist ? workflowModelAllowlist : undefined,
             },
+            // SVC-1 at-least-once notify: route core's terminal notify THROUGH the gate (deliver-then-ack +
+            // journal dedup) instead of straight to log/meter, so a crash mid-delivery re-delivers on the next boot
+            // recovery sweep. When the gate is absent (memory backend / no journal) fall back to the bare
+            // log+meter delivery (at-most-once, the prior behavior — honest about the lost-on-crash window).
             workflowCompletionNotifier: {
+                // ⚠️ design/158 S4 有意保留的展开:两臂**都非空**(要么 gate 造的 notifier,要么裸 notify 兜底),
+                // 不是「条件键」形——它合并的是同一必填键 `notify` 的两个来源,两来源都有类型,不构成
+                // 多余属性检查旁路(缺 notify 反而当场编译红)。
                 ...(workflowNotifyGate
                     ? workflowNotifyGate.buildNotifier()
                     : { notify: (input) => deliverWorkflowCompletion(input) }),
+                // core 1.232 (the CORE half of the poll-then-also-notify dedup): pollWorkflow fires this
+                // ONCE when the ORIGINATING session polls the run to a real terminal (timeout/cross-session polls
+                // don't) — drop that (session, runId)'s pending inbox entry + arm the served fence, so the push
+                // that would duplicate what the model just read is dead even across a shell restart. Session
+                // attribution mirrors resolveCompletionRoute's session half (payload id, else the run row).
                 ackServed: async (input) => {
                     if (!workflowCompletionInbox)
                         return;
@@ -1032,6 +1691,10 @@ async function main() {
                         const sid = await resolveServedSession(input, runStore ? (id) => runStore.getRun(id) : undefined);
                         if (sid) {
                             await workflowCompletionInbox.markTerminalServed(sid, input.runId);
+                            // The THIRD way an inbox entry disappears (besides the three stream-open drains
+                            // and the owner-mismatch drop) — the model itself polled the run to terminal, so the push is
+                            // suppressed. An "enqueue → ack within ms, but the shell showed nothing" report with THIS line
+                            // means the completion went to the MODEL in-process (core injected it), not onto any stream.
                             logger.info("workflow_complete_ack_served", { route: "poll-served", sessionId: sid, runId: input.runId });
                         }
                     }
@@ -1043,28 +1706,63 @@ async function main() {
         }
         : {};
     const runnerDeps = {
+        // e/b([985]):center catalog 轴的 core 消费面——candidate/pinned-digest 解析走这里(prepare-task
+        // dist:session_start 优先 candidate、resume 按 digest 解析、miss=fail-loud prompt_snapshot_unavailable)。
         promptSource,
+        // [1070]① agent-team S1:持久名册 seam(具名 spawn advisory 写入;SendMessage 活注册表 miss 后咨询)。
         rosterStore: rosterStore ? rosterStore : undefined,
+        // core 1.364 durable bg agents 读半场(写半场=scenarioDeps.backgroundAgentStore 同实例,组装区注释)。
         backgroundAgentStore: backgroundAgentStore ? backgroundAgentStore : undefined,
+        // S3c tier-3 懒复活(core 1.374):SendMessage 链内消费,与 backgroundAgentStore 同实例配套挂载。
         mailboxStore: mailboxStore ? mailboxStore : undefined,
         brain,
         models: config.models,
         roles: config.roles,
+        // core 1.265: the active tier table (tier words + CC aliases → catalog keys, expandTiers at Runner
+        // construction; empty = INERT by core contract). Same mutateInPlace reference applyEffective fills — a
+        // refresh-time tier change is restart-to-apply, same tier as models.
         tiers: config.tiers,
         pricing,
         tracer,
+        // [931]① clay 拍(core 1.300 BREAKING:缺省不署 Co-Authored-By,署名=产品身份资产归部署):
+        // branded 形态(local provider = Sema 产品线,scenarios brandIdentity 同判据)commit 尾注接 Sema 署名;
+        // 非 brand 部署维持 core 新缺省(不署)。seam=RunnerDeps.hands.commitCoAuthor。
         hands: config.configProvider === "local" ? { commitCoAuthor: "Sema <noreply@vivi-ai.com>" } : undefined,
+        // design/73 §1 (core 1.226 seam, clay 拍 2026-07-04 接): consume mechanical TaskOutcome facts into the
+        // outcome ledger — tidb/pg = SQL rows (coreOutcomeToLedgerRow mapping + verbatim `core_outcome` JSON so
+        // red-line ② oracleHadRedRun survives lossless), local = owner-only JSONL. Read-only v1: records facts,
+        // drives NO policy (§7.4 backtest gate stands). Fire-and-forget — a sink failure logs and never touches
+        // the run (core's emitTaskOutcome swallow-guards too). Emitters today: core runGoal terminal + any
+        // harness with a REAL mechanical oracle calling runner.emitTaskOutcome; plain runTask never auto-emits.
         onTaskOutcome: outcomeSink
             ? (o) => {
                 metrics.inc("task_outcomes_total", { status: o.status, green: String(o.oracle?.green ?? "unknown") });
                 void outcomeSink.recordCore(o).catch((err) => logger.warn("task_outcome_record_failed", { runId: o.runId, err: String(err) }));
             }
             : undefined,
+        // E23: the live-only inbound-elicitation seam. core invokes it only for servers that opted in via
+        // McpServerSpec.elicitation (default OFF) AND only when this is wired — both must hold (doubly fail-closed).
         onElicit: elicitation ? elicitation.elicit : undefined,
+        // §4④: the live AskUserQuestion seam. core mounts the tool when onQuestion is present + routes each ask here; the
+        // DURABLE leg's spec.onQuestion (QUESTION_AWAITS_RESUME) OVERRIDES this per-task so a disconnected-human ask suspends.
         onQuestion: question ? question.question : undefined,
+        // [816]/[820]②: the live tool-approval seam (core `resolveAsk` — `spec.onAsk ?? deps.onAsk`). ALS-routed like
+        // onQuestion: a leg wrapped by the coordinator's runWithContext reaches the human.
+        //
+        // [879] G1 终态(core 1.295 OnAsk 三值化):恒 wire。回调逐 ask 时刻判活人——ALS 附着腿 ⇒ 同步三选卡;
+        // 无附着/卡送达失败 ⇒ 返 "unavailable",core 以 approverUnavailable 回路把该 ask 交回 suspendAsk 走
+        // durable park(prepare-task 分路带 `approverUnavailable !== true` 豁免位,dist 亲读)——park 与 live 卡
+        // 两全,1.199 的「durable 部署不 wire deps.onAsk」止血撤除。无 park 设施的部署 core 自己 fail-closed
+        // deny(resolveAsk 的 unavailable 文案),与旧姿势同向。
         onAsk: toolApproval
             ? (req, signal) => toolApproval.ask(req, signal)
             : undefined,
+        // [822]② auto permission mode, deployment half: RunnerDeps.autoMode is the operator TRUST face of core's
+        // auto-mode classifier (1.276/1.277) — wiring it alone arms NOTHING (core requires the per-principal entitlement
+        // runtimeCaps.autoMode === true from center, fail-closed dark by default; see runtime-caps-resolver.ts). With
+        // both present, core screens every policy `ask` through the classifier (allow safe / deny hostile / leave the
+        // rest on the ask path → this bridge or durable park). Defaults-only config (core's rules/window); breaker-open
+        // is surfaced for observability.
         autoMode: {
             onBreakerOpen: (info) => {
                 metrics.inc("auto_mode_breaker_open_total");
@@ -1072,8 +1770,14 @@ async function main() {
             },
         },
         sessionStore,
+        // design/138 S1: the memory-engine switch — when present (single-user + engine on), core replaces the
+        // legacy memory path WHOLESALE per task (materialize → session file ops → harvest; no remember/recall
+        // tools). `memoryEngineDir` = the resolved config root (core derives the B3 control plane beside the
+        // memory dir). Absent (multi-tenant / MEMORY_ENGINE=off) ⇒ no deps.memoryBackend ⇒ memory dark.
         memoryBackend: memoryEngine ? memoryEngine.backend : undefined,
         memoryEngineDir: memoryEngine ? memoryEngine.root : undefined,
+        // S3-TOB 复审 F-9(operator 可观测底座):harvest 报告 → metrics(拒收/incident/patch 计数从此可见;
+        // core swallow-guard 保证 throwing consumer 不伤边界)。
         onMemoryHarvestReport: memoryEngine
             ? (report, info) => {
                 metrics.inc("memory_harvest_total", { ok: String(report.ok), phase: info.phase, incident: report.incident?.kind ?? "none" });
@@ -1081,47 +1785,89 @@ async function main() {
                     metrics.inc("memory_harvest_patches_total", { phase: info.phase }, (report.patches.add ?? 0) + (report.patches.update ?? 0));
                 if (report.incident)
                     logger.warn("memory_harvest_incident", { kind: report.incident.kind, phase: info.phase });
+                // 142-S2.5-W1: 成功 harvest 真有 patch 落地 = 本地记忆变了 ⇒ fire-and-forget 一轮同步
+                // (trigger 自带 inflight 节流:上一轮在飞则跳过,漏掉的变更下一轮全量补上)。
                 if (memorySyncRunner && report.ok && (report.patches?.add ?? 0) + (report.patches?.update ?? 0) > 0)
                     memorySyncRunner.trigger("harvest");
             }
             : undefined,
         toolResultStore,
+        // E6: operator-tightened session tool rules — core folds them into the ToolPolicy FIRST (subtract-only) for tasks
+        // carrying a sessionId (a delegated subagent has none → inherits no rules). Opt-in: undefined ⇒ no rules read.
         sessionPolicyStore: sessionPolicyStore ? sessionPolicyStore : undefined,
+        // design/99 §K: per-principal runtime entitlements (allowWorkflows / forceDurableGate) resolved from center.
+        // Opt-in: undefined ⇒ NO per-principal restriction (tighten-only; deployment default governs). See above.
         runtimeCapsResolver: runtimeCapsResolver ? runtimeCapsResolver : undefined,
+        // E19: working-tree snapshot/restore for rewind (+ the 2c artifact store). core snapshots each completed turn +
+        // restores on resumeAt when spec.rewindFiles is set, for ANY env when this store is wired (gate-split 1.134.0).
         fileSnapshotStore: fileSnapshotStore ? fileSnapshotStore : undefined,
         executionEnvFactory: executionEnvFactory ? executionEnvFactory : undefined,
         lspManager: lspManager ? lspManager : undefined,
+        // design/129-B (core 1.240.0): the PROCESS-LEVEL background-child observer — spawn/tick/terminal
+        // for every bg delegation child, never dying with a leg. Feeds the fleet rows (launch 即有行, session-scoped
+        // children stay visible past the turn — the 缺口① fix) + the bg_notification frame on the
+        // always-open fleet stream (缺口②: idle completion delivery is immediate). Wired once per process.
         onBackgroundChildEvent: fleetBackgroundChildPublisher(fleetBus, (msg, fields) => logger.info(msg, fields)),
+        // design/113 C4: inject CLAUDE.md + git narrative so a chat opens project-aware (like CC). The helper reads cwd via
+        // local fs/execFile — only meaningful when cwd is LOCAL (host/file lane); it stats the dir and returns null on a
+        // remote-sandbox cwd, so this is safe to wire generally, but we gate it to single-user (cwdHonored posture — the
+        // same lane where reading the local project for the caller isn't a confused-deputy hole) + the opt-out kill-switch.
         loadProjectMemory: config.requirePrincipal !== true && config.projectMemoryEnabled ? makeLoadProjectMemory({ logger }) : undefined,
+        // core 1.302 instructions-change lane (板 [952]②): re-fingerprint the declared instruction file each turn so a
+        // mid-run edit surfaces as a tail attachment. STRICTLY host lane — on a remote-sandbox lane the instruction file
+        // lives in the container; a local re-read would fingerprint the wrong tree, so the probe is not wired there.
         probeInstructionSources: config.remoteExec?.provider === "host" && config.requirePrincipal !== true && config.projectMemoryEnabled
             ? makeProbeInstructionSources()
             : undefined,
         hooks: deploymentHooks,
-        ...selfOrchestrationDeps,
+        ...selfOrchestrationDeps, // S8 self-orchestration 全家桶(成组条件段;类型标注在上方 const)
+        // F8: surface best-effort compaction failures + the 1.22 prompt-cache low-hit warning (an
+        // unstable/poisoned prefix tanking cost) instead of silently swallowing them.
         onError: (err, ctx) => {
+            // "degraded" (1.40) is an operational event, NOT a failure — the task still completes (on a cheaper
+            // model). Log it as a warning so it doesn't pollute error rates/alerts. The degraded_total metric
+            // comes from the tracer's task.degraded event.
             if (ctx.phase === "degraded") {
                 logger.warn("task_degraded", { sessionId: ctx.sessionId, info: String(err) });
                 return;
             }
+            // "prompt-constitution" (core 1.243): a stableSystem provider returned an ALREADY-
+            // assembled prompt (constitution anchor found); core passed it through un-doubled. The task is safe
+            // (guard un-doubles), but the provider is pre-1.243-shaped and should be upgraded to return only the
+            // role base. Warn — paired with the tracer's prompt_constitution_total{mode="provider-assembled"}.
             if (ctx.phase === "prompt-constitution") {
                 logger.warn("prompt_provider_needs_upgrade", { sessionId: ctx.sessionId, info: String(err) });
                 return;
             }
+            // "rewind" (E19 per-turn file snapshot): best-effort — a failed snapshot only makes that one turn
+            // non-rewindable; the task itself is unaffected. `too_large` is the EXPECTED shape on a big working
+            // tree (TOC user opening a 20G folder: enumerate hits the 256MB bound EVERY turn → an error-level
+            // line per turn reads like the run is broken). Downgrade to warn + count by code so a real store
+            // fault (enumerate_failed on a readable tree, blob-write errors) still stands out in the metric.
             if (ctx.phase === "rewind") {
                 const code = /\((\w+)\)/.exec(String(err))?.[1] ?? "unknown";
                 logger.warn("rewind_snapshot_failed", { sessionId: ctx.sessionId, code, info: String(err) });
                 metrics.inc("rewind_snapshot_failed_total", { code });
                 return;
             }
+            // "memory" (1.62, design/41): a best-effort post-task consolidation pass failed. The task already
+            // completed and its notes are safely appended (just not reconciled this round) — warn, fail-open,
+            // don't pollute error rates. (Consolidation cost still lands in model_cost_micro_usd via the tracer.)
             if (ctx.phase === "memory") {
                 logger.warn("memory_consolidation_failed", { sessionId: ctx.sessionId, info: String(err) });
                 return;
             }
+            // "mcp" (1.68): a broken MCP server was SKIPPED (fail-open) — the task still ran without
+            // that server's tools. Surface it as a warning + metric so a misconfigured server is observable, not silent.
             if (ctx.phase === "mcp") {
                 logger.warn("mcp_server_unavailable", { sessionId: ctx.sessionId, info: String(err) });
                 metrics.inc("mcp_server_unavailable_total");
                 return;
             }
+            // "prompt-cache" (1.22 low-hit + design/31 break detector): since core 1.89 the detector passes its
+            // root cause as ctx.classification — "server-or-ttl" is usually benign in agentic tasks (slow tools ⇒
+            // 5min+ request gaps expire provider caches) → warn; the prefix-bug causes
+            // (model-switch/tool-schema/tool-set/system-prefix) stay errors that warrant attention.
             if (ctx.phase === "prompt-cache") {
                 metrics.inc("prompt_cache_low_hit_total");
                 const fields = { sessionId: ctx.sessionId, ...(ctx.classification ? { classification: ctx.classification } : {}), err: String(err) };
@@ -1131,6 +1877,9 @@ async function main() {
                     logger.error("prompt_cache_break", fields);
                 return;
             }
+            // "config" (core 1.300 [931]②): assembly-time advisories — e.g. toolPolicy 名单池审计
+            // (config.toolpolicy.unmatched_names:名单里写了实挂宇宙不存在的工具名=typo 探测,enforcement
+            // 不变)。观测性提示,warn+metric,不进 error 告警面。
             if (ctx.phase === "config") {
                 logger.warn("runner_config_advisory", { sessionId: ctx.sessionId, info: String(err) });
                 metrics.inc("runner_config_advisory_total");
@@ -1140,8 +1889,28 @@ async function main() {
         },
     };
     const runner = new Runner(runnerDeps);
+    // codex R10: TRUE ⇒ the Runner just froze a PRIVATE tier-expanded catalog copy (core runtask.js constructor,
+    // dist-read) — in-place model-plane mutation no longer reaches it, so refresh-time plane changes must be
+    // DEFERRED to restart (see appliedPlaneEff / applyEffective deferModelPlane). Captured HERE, at the same
+    // config generation the constructor read.
     const runnerTierFrozen = Object.keys(config.tiers).length > 0;
+    // hooks 阶段三b(design/HOOKS-PHASE3B-PROMPT-AGENT.md):prompt/agent 条目的模型调用载体。
+    //  - hookLlm(prompt 条目)= 直连网关一次非流式 completion——一次判定调用不起 core task(重炮打蚊子
+    //    且引入可重入面);无系统注入(hook 作者的 prompt 即全部)。默认模型=summarize 角色(cheap tier,
+    //    council/压缩同款;缺角色→主模型);entry.model 覆盖须命中部署 catalog(单用户=自家目录全开,与
+    //    workflow 模型 allowlist 同纪律),未命中=该条目 fail(非阻断记账)。费用不折 task budget(hook=
+    //    部署策略面开销;hook_llm_calls_total/hook_llm_cost 由 metrics 记)。
+    //  - hookAgent(agent 条目)= runner.runTask 读-only 子代理:handsReadOnly + enableFork:false +
+    //    不装 hooks(🔴 可重入禁——结构性:这个 spec 永不携带 TaskSpec.hooks)+ maxTurns 10 + maxCostUsd
+    //    0.05 独立小预算,影响范围受限。final result 文本即输出(与 prompt 同一 SyncHookOutput 决策面)。
+    // hookModelFor/hookLlm 抽到 src/hooks/hook-llm.ts(可注入 fetch/keyResolver ⇒ 可单测):api 形分派
+    // (openai /chat/completions 与 anthropic /v1/messages 双腿)、缺省 baseUrl 按 api 分家、per-model key
+    // 恒胜 + foreign-no-key 连 prompt 都不发的 fail-closed 纪律,全在该模块内(注释含 audit 原文)。
+    // getKeyResolver 取函数:keyResolver 是下方 let,registry 热应用会整个换引用,这里必须每次现取。
     const { hookModelFor, hookLlm } = createHookLlm({ config, getKeyResolver: () => keyResolver, metrics });
+    // hook agent 的 session 绝不进 durable store——每次 runTask 会写 session_meta 且无人
+    // 清理(reaper 只扫 staging orphan),cap=4/事件 × 长会话=无主行堆积。专用 Runner 覆盖 sessionStore 为
+    // 进程内 TTL 店(1h 短 TTL,hook 子代理无 resume 语义,行随进程/TTL 消失);其余 deps 原样共享。
     const hookAgentRunner = new Runner({ ...runnerDeps, sessionStore: new TtlSessionStore({ defaultTtlDays: 1 / 24 }) });
     const hookAgent = async ({ prompt, model, timeoutMs }) => {
         const pick = hookModelFor(model);
@@ -1156,7 +1925,11 @@ async function main() {
                 enableFork: false,
                 maxCostUsd: 0.05,
                 limits: { maxTurns: 10, timeoutSec: Math.max(30, Math.ceil(timeoutMs / 1000)) },
+                // spec 无 toolPolicy → core `hasEffectAwareGate` 为假 → 每次 agent hook 触发一条
+                // error 级 UNGATED 警告(非致命但纯噪声)。挂已裁决的 auto-accept 基线(与 singleUserAutoAcceptBaseline
+                // 同构;hook 子代理本就 handsReadOnly + 单用户信任面,auto-accept 是既定姿态,只是让闸机制在场)。
                 toolPolicy: createAllowDenyPolicy({}),
+                // 🔴 可重入禁:此 spec 不带 hooks 字段(deps.hooks 是部署观测 tracer,void 观察者,无决策面)。
             });
             metrics.inc("hook_llm_calls_total", { type: "agent" });
             if (result.status !== "completed")
@@ -1168,12 +1941,15 @@ async function main() {
         }
     };
     const clipHookErr = (s) => (s ?? "").slice(0, 300);
+    // Auto session titles — fire-and-forget at first
+    // submit, one cheap hookLlm call (summarize role → MODEL_CHEAP_ID when configured), write-once via the session
+    // store's setTitleIfNull (SQL twins + local sidecar carry it; the memory dev store doesn't → titler dark, honest).
     const titleCapable = sessionStore;
     const sessionTitler = config.sessionAutoTitle && titleCapable.setTitleIfNull && titleCapable.probeTitle
         ? createSessionTitler({
             setTitleIfNull: titleCapable.setTitleIfNull.bind(sessionStore),
             probeTitle: titleCapable.probeTitle.bind(sessionStore),
-            redact: redactSecrets,
+            redact: redactSecrets, // audit 2026-07-13: scrub a model-echoed secret before persist/list/log
             llm: (o) => hookLlm({ prompt: o.prompt, timeoutMs: o.timeoutMs }),
             logger,
             metrics,
@@ -1181,8 +1957,54 @@ async function main() {
         : undefined;
     if (sessionTitler)
         logger.info("session_auto_title_enabled", {});
+    // ① workflowsCapability SINGLE-SOURCE (core 1.155 `workflowsCapability(deps)`; ruling = SPLIT two caps):
+    // `capabilities.workflows` = core's own truth (`workflowScriptRunner.safeForUntrustedScripts` ∧ governance), boot-
+    // computed from the SAME RunnerDeps the engine uses = the ENGINE-CAN axis ("can the engine self-orchestrate /
+    // ultracode"), ORTHOGONAL to the durable-LIST axis (`Boolean(workflowRunStore)`, surfaced as `workflowsList`).
+    // ⚠️ Today these COINCIDE — `workflowRunStore` is built iff self-orch (InMemory/File, ~L527), the same gate that
+    // wires the safe runner — so this is core's FORWARD-LOOKING contract, not a live-divergence fix (the earlier
+    // "memory backend diverges" premise was wrong; double-review caught it — see the cap site in http/server.ts).
+    // Static per deployment (deps are boot-fixed).
     const workflowsCapable = workflowsCapability(runnerDeps);
+    // Sub-task runner (code-review council lenses/arbiter, subagent/team children). [1364]①/[1367]①(core
+    // 1.350 fork 终修的部署要求):fork 子任务带 `requireExistingSession:true` 在这里执行而源会话在 HOST 店
+    // ——拆店=响亮 `resume.session_not_found`(cli fork 案的 server 半场)。但整店共享被 codex 判两 high
+    // (普通子任务铸 committed durable 会话:无 reaper 覆盖=无界增长+污染 /v1/sessions 枚举),故走
+    // ForkRoutingSessionStore:fork/resume 形(requireExisting)→ host 店优先,普通子任务 → 私有 TTL 店
+    // (throwaway 姿势保留)。hookAgentRunner 仍保独立 TtlSessionStore(1h)——纯瞬态 hook 车道,与 fork 无关。
+    // CC-parity (CRITICAL — 子代理 hands, root cause is the service spawn path): the subagent delegation
+    // tool runs child tasks on THIS subRunner. Without executionEnvFactory the child's `handsEnabled` (= ownedEnv ||
+    // deps.executionEnv, prepare-task) is FALSE → the child gets NO hands (Bash/Read/Edit) and can't run `pwd` — the
+    // "subagent couldn't run pwd" defect hit in real TUI use. core's createSubagentTool gives hands when the env is
+    // wired (gate3: opts.tools:[] still yields Bash), so the fix is to give the subRunner the SAME executionEnvFactory +
+    // lspManager as the main runner. Deliberately NOT inherited: selfOrchestration (no recursive workflow spawn),
+    // scheduler, memory, fileSnapshot, runtimeCaps — a delegated child is a short focused task, not a full session.
+    // codex-2 F1:promptSource 必须随子代——core 1.341 把父的 centerArtifactDigest 传给委派子任务并在子
+    // runner 上按 digest 解析;缺席=每个 catalog 任务的 Agent 子代 fail-loud prompt_snapshot_unavailable。
+    // backgroundAgentStore(1.248 复审 F2):core prepare-task 给每个 task 的 TaskOutput/TaskStop/
+    // AgentTranscript 装 durable 臂用的是所在 runner 的 deps——子代任务跑在 subRunner 上,缺席=子代读
+    // 工具无 durable 回落(第三消费点,与 RunnerDeps/scenarioDeps 同一实例)。
+    // [1543]§三族A(core 穿透审查,历史欠账键批——主 runner 挂了、subRunner 漏挂 = 子代 lane 静默降级;
+    // 全部直引 runnerDeps 同一实例,双点永不漂移):
+    //  - tiers(H):模型目录双 runner 分叉——tier 词 AgentDefinition 在子代 lane 抛 unknown_model、Agent
+    //    model 参数("opus")静默 modelNote 降级、S3c revive 臂 row.model 记 tier 词时复活换模型。
+    //  - rosterStore(M):具名 spawn 不落 durable 名册 → tier-3 按名复活从子代不可达。
+    //  - onBackgroundChildEvent(M):子代触发的 revive/孙代对 fleet 流全盲(同一 publisher 实例=单管道)。
+    //  - loadProjectMemory/probeInstructionSources(M):委派子代 project-blind(core types 已为子代 ctx
+    //    设计 isSubagent/agentName;门禁条件随 runnerDeps 条件键自动一致)。
+    //  - hooks/onError/toolResultStore/sessionPolicyStore(L):子代进 tracer/计量;best-effort 故障不静默;
+    //    fork 子代跨 wake 保 offload 引用;fork 形(有 sessionId)会话规则可达。
+    // 1877 注释的「Deliberately NOT inherited」清单(selfOrchestration/scheduler/memory/fileSnapshot/
+    // runtimeCaps)不变——本批只补漏配,不动裁定。
+    // checkpointStore 构造(从 runStore 区上移,只依赖 backend/config——顺序安全;DURABLE_APPROVAL 仍是
+    // 唯一门,ALL three backends carry checkpoint(),local = core FileCheckpointStore + service half)。
+    // 三个消费点同一实例:主 runner 的 per-task spec 面(resolveSpec durableEnabled 分支)、scenarioDeps
+    // (subagent spawn 面 forwardDurableApproval)、subRunner deps(子代执行面 suspendAsk——[1584] 接线,
+    // 裁定见下方 subRunner 构造内注)。
     const checkpointStore = backend?.checkpoint && config.durableApproval ? backend.checkpoint(logger) : undefined;
+    // [1593] 提名成变量:parked 子代的 ensureChildSessionDurable 晋升半场要拿它做 promoteToHost
+    // (子会话住私有 TTL 店,park 前整树拷进 host durable 店——只查不迁的 1.263 形在拆店生产形下恒
+    // 否决 park,cli 真机 14ms~2s expired 即此)。
     const subRunnerSessions = new ForkRoutingSessionStore(sessionStore, new TtlSessionStore({ defaultTtlDays: 1 / 24 }));
     const subRunner = new Runner({
         brain,
@@ -1193,6 +2015,9 @@ async function main() {
         tracer,
         promptSource,
         sessionStore: subRunnerSessions,
+        // A7/S4 余量(design/158):core RunnerDeps 消费端对以下键均无在场性判定(无 "k" in deps /
+        // Object.keys(deps) 分支——S4 已逐键核过全量 RunnerDeps 消费面),故显式可选键(undefined 与
+        // 缺席同义)替代条件 spread,行为等价、可读性与主 runnerDeps 装配点(1687 行)同款。
         executionEnvFactory: executionEnvFactory ? executionEnvFactory : undefined,
         lspManager: lspManager ? lspManager : undefined,
         backgroundAgentStore: backgroundAgentStore ? backgroundAgentStore : undefined,
@@ -1204,15 +2029,42 @@ async function main() {
         hooks: deploymentHooks,
         onError: runnerDeps.onError ? runnerDeps.onError : undefined,
         toolResultStore,
+        // sessionPolicyStore:挂载无害(tighten-only 空查);如实注(复审 F5)——子代 sessionId 是新铸
+        // uuid,E6 规则按宿主 id 键存 → 子代查自己恒空;规则真到子代靠 inheritedGate.ancestorRules(本就
+        // 通)。真实受益面 = retained child 自己 session 被显式 PUT 过规则的边角。
         sessionPolicyStore: sessionPolicyStore ? sessionPolicyStore : undefined,
+        // checkpointStore = 子代**执行面**的 park 设施([1582] cli TiDB 真验撞获缺口,[1584] core 定谳
+        // 接线步):core prepare-task `spec.checkpointStore ?? deps.checkpointStore` 里 spec 侧永不被
+        // subagent 设置,子代 suspendAsk 全靠这里——缺席 = 具名 bg 子代的 gated ask 只能 deny+continue,
+        // checkpoint 表零行(cli T2 复现原话「denied by an approval constraint」)。必须与 scenarioDeps
+        // (spawn 面 forwardDurableApproval 判定)**同一实例**:claim/expire/consumeParkedFlip 都作用于
+        // 同一行。旧 [1546] HIGH-2 撤载(「core 不转发 durableApproval + SAFETY ask 会 park 出搁浅
+        // checkpoint」)的前提被 core 1.388 件4(转发臂)消除,搁浅顾虑由件1-4+1.389 逐项闭合:watcher
+        // park 翻行 + reap 豁免 + reconciliation 兜孤儿;unattended SAFETY park 恒带缺省 deadline;
+        // TaskStop on parked 走 expire CAS 仲裁(1.389 F-1);/decide 可赎回。行为钉 =
+        // test/subagent-park-wiring.test.ts(SOURCE PIN + park 全链 + 旧形反向控制)。
         checkpointStore: checkpointStore ? checkpointStore : undefined,
     });
+    // S6: resolve identity + owned session from the authenticated channel (never the body).
     const authorize = createAuthorizer(config, sessionStore);
+    // S1/S2: durable async run registry + replayable event log (TiDB-backed).
     const runStore = backend ? backend.run() : undefined;
+    // E18 resume-at: the eventId→entryId anchor map. REQUIRED on every backend (works local — needs only the session
+    // tree + this map, no cloud-only checkpoint), so the only undefined case is the env-only/no-backend deploy (which
+    // also has no async runs — consistent). The shell sends body.resumeAt=eventId; resolveSpec resolves it here.
     const resumeAnchorStore = backend ? backend.resumeAnchor() : undefined;
+    // Per-session approval exemption ("本会话不再询问") — REQUIRED on every backend like the anchor
+    // map; undefined only on the env-only/no-backend deploy (which has no durable approvals either — consistent).
     const approvalExemptionStore = backend ? backend.approvalExemption() : undefined;
     const instanceId = uuidv7();
+    // Per-task wall-clock override (seconds). 0/absent = keep the built-in 600 (1500 council/debate/team) —
+    // the override only ever RAISES (Math.max at the use site), so a misconfigured low value cannot shrink
+    // the council budget.
     const taskTimeoutSec = Math.max(0, Math.floor(Number(process.env.TASK_TIMEOUT_SEC ?? "0")) || 0);
+    // [854]④ per-request 配速的运营方上限旋钮(可选;缺省不设=不封顶):body.limits 每键各自被对应旋钮
+    // Math.min 封顶(normalizeLimits)。多租部署想约束 caller 自报配速时才设;单用户 turnkey 通常留空。
+    // ⚠️ 语义=只钳「显式请求值」,不是全队默认限额:body 缺席(或重放体里的非法值被 defensive DROP)⇒ 该键
+    // 不设限,与升级前行为同形——要给所有任务强加限额是另一个旋钮(未建),别指望这三个(交叉评审 F1 判读)。
     const capEnv = (name) => {
         const n = Math.floor(Number(process.env[name] ?? "0"));
         return Number.isFinite(n) && n > 0 ? n : undefined;
@@ -1222,12 +2074,32 @@ async function main() {
         maxOutputTokens: capEnv("TASK_MAX_OUTPUT_TOKENS_MAX"),
         maxTurns: capEnv("TASK_MAX_TURNS_MAX"),
     };
-    const approvalStore = backend?.approval ? backend.approval() : undefined;
+    // F4: human-in-the-loop approval gate (pending state durable so any instance can decide).
+    const approvalStore = backend?.approval ? backend.approval() : undefined; // local omits approval() → legacy poll-gate off (durable HITL needs checkpoint anyway)
     const approvalEnabled = approvalStore && config.approvalRequire.length > 0;
+    // Finding #2 (edge case): the single-user auto-accept tool-policy BASELINE applies ONLY when the operator
+    // expressed NO gate intent. If they SET approval flags (APPROVAL_REQUIRE/APPROVAL_DENY/DURABLE_APPROVAL) but no
+    // backing store is wired (e.g. DB_BACKEND=local → no approvalStore/checkpointStore ⇒ approvalEnabled/durableEnabled
+    // false), that is a MISCONFIG — do NOT mask it with allow-all; leave toolPolicy undefined so core's UNGATED warning
+    // still surfaces it. So the baseline needs single-user turnkey ∧ zero expressed gate intent.
     const operatorGateIntent = config.approvalRequire.length > 0 || config.approvalDeny.length > 0 || config.durableApproval;
     const singleUserAutoAcceptBaseline = config.requirePrincipal !== true && !operatorGateIntent;
+    // design/45 durable-checkpoint (core 1.67): opt-in (DURABLE_APPROVAL + a pool). When on, F4 uses durable
+    // suspend/resume instead of the poll gate — a gated `ask` suspends the task (status:"suspended" + checkpoint)
+    // and an operator resumes it on any replica. Default off → unchanged poll-policy.
+    // checkpointStore 构造已上移到 subRunner 之前([1535] server 半场:子代 park 设施);本行原位注释保留。
+    // TOC integration ask③ (INTEGRATION-DESIGN §11): reclaim runs orphaned by a previous host-lane engine
+    // process (orphaned `running` → failed + release its EEXIST-blocking claim; exclude resume-in-progress rows). The
+    // logic + its null-safety (runStore undefined on the env-only/no-backend lane) live in the unit-tested
+    // `reclaimOrphansAtBoot` helper — extracted after a workflow re-review caught a boot crash there (HIGH, 1.49.0).
     await reclaimOrphansAtBoot(runStore, checkpointStore, logger);
-    const imageIndex = backend?.imageIndex ? backend.imageIndex() : undefined;
+    // Sandbox-image-pool index (IMAGE-API-DESIGN.md §2): enables /v1/images* query + select. TiDB-backed projection
+    // of the bake manifests + publish lifecycle. Present whenever a pool is — read-only catalog until P2/P3 bakes.
+    const imageIndex = backend?.imageIndex ? backend.imageIndex() : undefined; // local omits imageIndex() → sandbox-image-pool is cloud/fleet-only
+    // RFC A2 (A 切片先行): the model-facing SelectEnvironment tool — mounted via spec.tools
+    // (RFC 判定②(a)) whenever the per-task image chain is actually usable (k8s backend + image catalog), opt-out
+    // via SELECT_ENVIRONMENT_TOOL=false. Viewer scope is rebuilt per-execute from the Runner-threaded read-only
+    // ctx.principal (auth-channel-derived — a tool argument can never widen visibility).
     const selectEnvTool = config.selectEnvironmentTool && config.remoteExec?.provider === "k8s" && imageIndex
         ? selectEnvironmentTool({
             catalog: imageIndex,
@@ -1235,42 +2107,91 @@ async function main() {
             viewerFor: (principal) => ({ operator: explicitOperator(principal, config.operatorPrincipals), tenantId: principal ?? null }),
         })
         : undefined;
-    const imageBakes = backend?.imageBake && config.imageBakes.enabled ? backend.imageBake() : undefined;
+    // Sandbox-image-pool BAKE control plane (IMAGE-API-DESIGN.md §P2): enables /v1/images/bakes* when a pool exists
+    // AND IMAGE_BAKES_ENABLED. The config boot-invariant already fail-fasts an empty OPERATOR_PRINCIPALS (a
+    // world-writable build-host-RCE door). image-api stays the UNPRIVILEGED controller; the privileged build runs
+    // on the sema-registry-managed bake-runner worker on build-host (it claims + ingests over the internal routes).
+    const imageBakes = backend?.imageBake && config.imageBakes.enabled ? backend.imageBake() : undefined; // local omits imageBake() → cloud/fleet-only
     if (imageBakes)
         logger.info("image_bakes_enabled", { operators: config.operatorPrincipals.length, runner: config.imageBakes.runnerPrincipal });
+    // Durable HITL surface = checkpointStore ALONE (DURABLE_APPROVAL=true). It mounts AskUserQuestion-suspend (the
+    // agent asks the human + the portal approval center) AND the resumable checkpoint. The F4 TOOL-APPROVAL
+    // gate is an ADDITIVE layer driven by APPROVAL_REQUIRE — empty = no tool is gated, but AskUserQuestion HITL
+    // still works. (Decoupled 2026-06-13: previously these were coupled, forcing a placeholder APPROVAL_REQUIRE
+    // to get HITL — clay: OA writes don't gate (OA-backend RBAC is the authority), but portal HITL must work.)
+    // durableEnabled 已在 runnerDeps 前按同一条件求值([1.294 G1] 前置声明处)——checkpointStore 构造条件与其
+    // 同源,恒有 durableEnabled === !!checkpointStore。
     if (durableEnabled)
         logger.info("durable_approval_enabled", { toolApprovalGate: config.approvalRequire.length });
+    // 修4(三路复审 W3):the fs-write ask gate (resolveSpec, applyTaskSettings wiring below) mounts purely off the
+    // host-semantics lane — DELIBERATELY decoupled from any approval face, so no assembly path is ever gateless:
+    // with no live coordinator and no durable park, a permissionMode default/auto Write/Edit ask fail-closed
+    // auto-denies via core resolveAsk (onAsk absent ⇒ headless auto-deny, loud in-transcript). What that posture
+    // must NOT be is silent at boot: an operator who explicitly set TOOL_APPROVAL_ENABLED=false (or a multi-tenant
+    // default) would otherwise read the resulting hand-tool denials as an outage. Warn once, at boot.
     if ((config.remoteExec === undefined || config.remoteExec.provider === "host") && !toolApproval && !durableEnabled) {
         logger.warn("fs_write_gate_no_responder", {
             hint: "host-semantics lane with no approval face: permissionMode default/auto Write/Edit asks will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
         });
     }
+    // [1245]/[1248]② the workflow ask leg attaches on EVERY lane (not fs-dependent — see createWorkflowAskPolicy),
+    // so a sandbox-lane deployment running self-orchestration with no approval face hits the same fail-closed
+    // auto-deny class. Same loud-at-boot posture; host lanes are already covered by the broader warn above.
     if (config.selfOrchestrationEnabled && config.remoteExec !== undefined && config.remoteExec.provider !== "host" && !toolApproval && !durableEnabled) {
         logger.warn("workflow_gate_no_responder", {
             hint: "self-orchestration with no approval face: permissionMode default/auto/acceptEdits run_workflow asks will auto-deny (fail-closed); wire TOOL_APPROVAL_ENABLED=true or DURABLE_APPROVAL=true to answer them",
         });
     }
+    // Finding #2: a single-user turnkey worker with no explicit approval/durable/commandPolicy gets an
+    // ADJUDICATED auto-accept tool-policy BASELINE (createAllowDenyPolicy — a PRESENT effect-aware policy, so core's
+    // write-capable hand tools are never UNGATED / unadjudicated). Log the posture so the auto-accept is OBSERVABLE,
+    // not silent; tighten irreversible ops via APPROVAL_REQUIRE / AUTONOMY / commandPolicy (layered tighten-only).
     if (singleUserAutoAcceptBaseline) {
+        // Blanket auto-accept over ALL write/hand/MCP tool surfaces (core's per-surface UNGATED enumeration — hand band /
+        // destructive-MCP / first-party-write — is suppressed for single-user turnkey by design). Log it so the posture is
+        // observable; tighten (which also re-surfaces per-surface gating) via APPROVAL_REQUIRE / AUTONOMY / commandPolicy.
         logger.info("tool_policy_single_user_default", {
             posture: "adjudicated auto-accept — ALL write/hand/MCP tool surfaces auto-allowed (core per-surface UNGATED enumeration suppressed for single-user turnkey)",
             tighten: "APPROVAL_REQUIRE / AUTONOMY / commandPolicy (re-surfaces + gates specific surfaces)",
         });
     }
+    // D-G: a boot-time signal that this worker is in crypto-bound direct-door mode (trusted-header path disabled).
+    // Pairs with the /health directDoorActive field for the DG-M2 go-live runbook (a positive go signal, not just
+    // a behavioral 401). The boot invariant in config.ts already fail-fasts a half-configured direct door.
     if (config.directDoorActive)
         logger.info("direct_door_active", { iss: config.principalJwtIss, aud: config.principalJwtAud, operators: config.operatorPrincipals.length });
+    // CC-parity (adversarial-review finding): a MULTI-TENANT deployment running self-orchestration WITHOUT worker
+    // isolation is an availability risk — the in-process hardened VM is ESCAPE-isolated but NOT RESOURCE-isolated, so an
+    // entitled tenant's workflow script can starve the host event loop (microtask loop / OOM), affecting every tenant
+    // (src/orchestration/hardened-vm-runner.ts documents this). Loud boot warning so the operator sets
+    // SELF_ORCHESTRATION_WORKER_ISOLATION=true. (Single-user is unaffected — the one principal owns its own worker.)
     if (config.requirePrincipal && config.selfOrchestrationEnabled && !config.selfOrchestrationWorkerIsolation)
         logger.warn("self_orchestration_no_worker_isolation", { detail: "multi-tenant self-orchestration without SELF_ORCHESTRATION_WORKER_ISOLATION=true — a tenant workflow can starve the host event loop (availability risk). Set it to enable worker_thread resource isolation." });
+    // 🔒 (systematic-audit HIGH fix, defense-in-depth): a multi-tenant deployment (requirePrincipal) with NO service/trace
+    // token now correctly fails CLOSED — fleet/trace/session-list are owner-gated, never fleet-wide (isFleetWide, server.ts).
+    // Warn the operator: without SERVICE_AUTH_TOKEN/authTokens/TRACE_TOKEN those endpoints only ever return the caller's own
+    // rows (safe, but may surprise an operator expecting cross-tenant ops visibility — set a token for ops-relay).
     if (config.requirePrincipal && !config.authToken && Object.keys(config.authTokens ?? {}).length === 0 && !config.traceToken)
         logger.warn("multi_tenant_no_service_token", { detail: "REQUIRE_PRINCIPAL is on but no SERVICE_AUTH_TOKEN/authTokens/TRACE_TOKEN — fleet/trace/session-list are owner-gated only (never fleet-wide, tenant-isolation safe). Set a token for cross-tenant ops visibility." });
+    // Rate limiter: TiDB-backed (cross-replica SOFT limit, same write-behind counter as the cost quota)
+    // when a pool exists, else in-memory per-replica. Both satisfy RateGate. (design/30 P0-2)
     const rateLimiter = config.rateLimitPerMin > 0
-        ? backend?.rateLimiter
+        ? backend?.rateLimiter // local omits rateLimiter() → in-memory per-process RateLimiter (single-replica)
             ? backend.rateLimiter(config.rateLimitPerMin, counterDegradeHook).startRefresh()
             : new RateLimiter(config.rateLimitPerMin)
         : undefined;
+    // Capability layer: scenario → {tools (+ subagent roster), prompt, skills}. Heavy bits (skills,
+    // git client) are built ONCE here; per request we only select a scenario and bind coordinates.
     let skills = loadSkills(config.skillsDir);
+    // Sema-registry B1 (restart-to-apply, baked into scenarios below): overlay center skills (lazy-fetched by
+    // hash + sha256-verified) over the image baseline, center-wins-by-name; resolve center MCP servers' env-NAME
+    // refs to real values from this service's env. Both empty/unset → unchanged (image SKILLS_DIR, no MCP).
     if (effective?.skills && config.configCenter) {
         skills = await applyCenterSkills(skills, effective.skills, config.configCenter.baseUrl, config.configCenter.token, logger, undefined, configLkgEnabled() ? defaultSkillCacheDir() : undefined);
     }
+    // plugins 域消费半场(契约 [1361]②/[1362]/[1366]①;2026-07-28 开工车):把 center 声明的插件引用
+    // 物化(https-only+ALLOW_HOSTS 纵深复验/sha 钉扎/隔离 clone/LKG)并装载其 skills —— **在 center 直发
+    // skills 之后**:撞名让位判据(收紧④,plugin 让位)以此刻的 skills 集为准。失败单条不连坐,永不拒启。
     if (effective?.plugins && config.configCenter) {
         const pluginOut = await applyCenterPlugins(skills, effective, {
             cacheRoot: join(config.localDataRoot ?? join(homedir(), ".ai-agent"), "plugin-cache"),
@@ -1287,21 +2208,44 @@ async function main() {
             }
         }
     }
+    // F7:boot 的 LKG 落盘点。codex R26:走同一只 persistLkgDurable(完整性门在前)——此前裸 saveLkg 会把
+    // applyCenterSkills 静默吞掉失败的「缺正文 manifest」发布成 boot 可见 LKG(离线重启=静默缺 skill 且不再
+    // 有信号收敛)。校验失败=不落盘(warn 已在函数内),下一个干净候选/refresh 重试重写。
     if (bootLkgCandidate && lkgEnabled) {
         const bootPublished = await persistLkgDurable(bootLkgCandidate.effective, bootLkgCandidate.etag).catch((err) => {
             logger.warn("config_lkg_save_failed", { path: lkgPath, err: String(err), note: "boot LKG persist failed — retained for the per-tick retry" });
             return false;
         });
+        // codex R30: a failed/incomplete boot publication must enter the SAME retained-candidate retry lane as the
+        // refresh path — ccEtag has already advanced, so the next ticks 304 and nothing else would ever retry; a
+        // restart during a center outage would then boot stale/env config instead of the generation this process
+        // already applied. blocked=[] — everything WAS applied at boot, this is a publication-only retry (promotion
+        // with no withheld reasons publishes NO restart signal, it just completes the LKG and clears the state).
         {
+            // codex R32/R34: verify the boot's LIVE application UNCONDITIONALLY — applyCenterSkills skips an
+            // unfetchable body (this process may run skill-stale / on an older same-name built-in), and the LKG
+            // prewarm inside persistLkgDurable can succeed where the live fetch failed (bootPublished true, LKG
+            // complete, process still stale). Any live miss ⇒ a skills restart: published immediately when the
+            // handoff already stands, or carried in blocked for the 304-gated promotion when it doesn't.
             const enabledManifest = (bootLkgCandidate.effective.skills?.skills ?? []).filter((m) => m.enabled !== false);
+            // codex R33: the FULL runtime projection must match, not just name+body — a same-body built-in retained
+            // after a failed center fetch can carry different scenarios/description (e.g. global exposure where the
+            // manifest restricts to one scenario), and the scenario bundles baked right after are then stale.
             const canonScenarios = (a) => [...(a ?? [])].sort().join("\u0000");
             const liveSkillMiss = enabledManifest.some((m) => !skills.some((sk) => sk.spec.name === m.name &&
                 skillContentHash(sk.spec.content) === m.contentHash &&
                 sk.spec.description === m.description &&
                 canonScenarios(sk.scenarios) === canonScenarios(m.scenarios)));
             if (liveSkillMiss)
-                bootSkillStale = true;
+                bootSkillStale = true; // codex R35: sticky — survives same-generation 200 recomputes
             if (liveSkillMiss && (bootPublished || (!lkgSurvivesRestart && lastPrewarmBodiesVerified))) {
+                // Signal NOW only on the arms where a restart PROVABLY repairs (codex R34/R36/R37):
+                //  · durable + published — the complete LKG (manifest + hash-verified bodies) is the handoff;
+                //  · NON-durable + body proof — the prewarm inside persistLkgDurable just hash-verified every enabled
+                //    body on disk, so the miss was a TRANSIENT live-application failure and a restarted process
+                //    re-pulls successfully. WITHOUT the proof (persistent 404/hash mismatch) publishing here would
+                //    restart-storm a stateless deployment (codex R37) — that case falls to the retained-debt arm
+                //    below: visible on /health, retried per confirming 304, promoted only once the proof holds.
                 pendingRestart = { restartRequired: true, reasons: ["skills"], version: bootLkgCandidate.effective.version, since: Date.now() };
                 logger.warn("config_boot_skill_stale_restart", { version: bootLkgCandidate.effective.version, durableHandoff: bootPublished, note: bootPublished ? "live skill application incomplete but the durable LKG carries the full candidate — skills restart published (the next boot reads the complete LKG)" : "live skill application incomplete on a non-durable deployment but every enabled body is verified in the cache — skills restart published (transient failure proven repaired; the restarted process re-pulls live)" });
             }
@@ -1314,11 +2258,42 @@ async function main() {
     if (effective?.mcp)
         config.mcpServers = resolveMcpServers(effective.mcp, logger);
     const repoClient = config.gitApiBaseUrl ? new GiteaClient(config.gitApiBaseUrl, config.gitApiToken) : undefined;
+    // CC-parity: deployment-injected WebSearch backend (the leg core leaves open). Absent WEB_SEARCH_PROVIDER →
+    // undefined → the default scenario doesn't assemble the WebSearch tool. The API key stays in the backend closure.
     const webSearchCfg = webSearchConfigFromEnv();
     const webSearch = webSearchCfg ? createWebSearchBackend(webSearchCfg) : undefined;
     if (webSearch)
         logger.info(`WebSearch enabled (provider=${webSearchCfg.provider}, maxResults=${webSearch.maxResults})`);
+    // core 1.382([1561] 提货单①②,design/153 parked 状态机)「同车必接」的 ensureChildSessionDurable 挂点:
+    // 只在 checkpointStore 真在场时构造(与 core parkEligible 门「两者全在场才成立」的判据同源——checkpoint
+    // 不在场时构造这个闭包毫无意义,连带把「local/无 durable backend 部署不该跑这条 acquire/release」的
+    // 边界直接编码进构造条件,不用额外判断)。实现体拆到 `ensureSessionDurable`(session-store.ts,可独立
+    // 测试;双复审②抓的 F-7 同族空壳缺口——host 店可能存在 `register()` 留下的零内容 session_meta 行——
+    // 的校验也在那边)。
+    // 🔴 [1575] F3 修(cli 复查,红先行确认真红):`checkpointStore` 在场 ⇏ `sessionStore` 就是 TiDB 真店
+    // ——这是两个独立 config 轴(DB_BACKEND 供 checkpoint/runs 等用途 vs SESSION_BACKEND 单独控 session
+    // 落哪),`SESSION_BACKEND` 显式留在默认值时 `sessionStore` 是纯内存 `TtlSessionStore`(无 repo 构造,
+    // core `release()` 语义在该形态下是**整删会话**,不是"归还租约")——探针的 finally release 会销毁它
+    // 刚证明存在的会话。追加门 `config.sessionBackend === "tidb"`(此刻已被前面装配区从 "auto" 归一,
+    // 恒是 "tidb"|"memory" 二选一,时序安全):唯一保留可达的店形正是 release() 真安全的那种
+    // (TiDBSessionStore.release 逐字注释「Durable history is retained; just drop any in-flight cache
+    // entry」)。非 tidb 场景下 undefined = 子代按 pre-153 settle failed,零回归(与 checkpointStore 缺席
+    // 同一处置)。
+    // [1593] 只查不迁 → 主动晋升(cli TiDB 真机撞获:bg 子会话住 subRunner 私有 TTL 店、从不在 host 店,
+    // 旧形恒 veto → core 当场 expire checkpoint(14ms~2s)+ settle failed,赎回窗口不存在)。晋升链=
+    // 快查 host → promoteToHost(整树拷贝+私店 forget+路由记 host)→ 同一严检复验(leaf 非空);任何
+    // 一步失败仍如实 veto(pre-153 行为,不放大)。tidb 门与 F3 裁定不变。
     const ensureChildSessionDurable = checkpointStore && config.sessionBackend === "tidb" ? (sessionId) => ensureChildSessionDurableWithPromotion(sessionStore, subRunnerSessions, sessionId) : undefined;
+    // [1900]/[1904] WebFetch 摘要器:core 工厂 + summarize 角色模型(cheap tier;resolveTaskModel 自带
+    // 默认回落——与压缩线同族档位,不新造)。构造一次全场景共享;多租户形 WebFetch 整体被 filter,
+    // 本注入无效化由 scenarios 现行为保证。
+    // 🔴 复审 E-MED-2/E-MED-3 两修:
+    //  ① **惰性解析**:模型每次调用现取——`config.models`/`config.roles` 会被 center 的 effective
+    //     热应用 mutateInPlace 整表替换,boot 期急求值会把摘要器永久 pin 在占位/旧模型上(故障形态是
+    //     静默退回上下文放大 + 每次一发无效 LLM 调用)。
+    //  ② **fail-soft**:core resolveTaskModel 在无可解析角色时 throw,这是全仓唯一 boot 期裸调用;
+    //     center 发一张既无 summarize 又无 default 的 roles 表就会拒启。解析失败 ⇒ 本次不摘要
+    //     (core 的 summarize 抛错是 fail-open:回退原文+note),绝不崩 boot。
     const webFetchSummarize = async (content, prompt, signal) => {
         const model = (() => {
             try {
@@ -1333,14 +2308,29 @@ async function main() {
             throw new Error("summarize model unresolved for this deployment");
         return createWebFetchSummarizer(brain, model)(content, prompt, signal);
     };
+    // design/158 S4:标注 `: ScenarioDeps` —— 无标注的字面量连自己的键名都不校验(打错/多写一个键
+    // 只是多一个没人读的属性,编译期无声),这是 1.304 落错家那一族的另一半土壤。
     const scenarioDeps = {
         runner, subRunner, model: "default", skills, repoClient, requirePrincipal: config.requirePrincipal,
         webSearch: webSearch ? webSearch : undefined, metrics, logger, webFetchSummarize,
+        // core 1.364 写半场:与 RunnerDeps.backgroundAgentStore 同实例(组装区注释;半接=静默死特性)。
         backgroundAgentStore: backgroundAgentStore ? backgroundAgentStore : undefined,
+        // core 1.382 parked 状态机「同车必接」一对——checkpointStore 与 main runner 的 checkpointStore(subRunner
+        // 构造区上方 const)同实例;ensureChildSessionDurable 见上方构造闭包注释。
         checkpointStore: checkpointStore ? checkpointStore : undefined,
         ensureChildSessionDurable: ensureChildSessionDurable ? ensureChildSessionDurable : undefined,
         oaApiBaseUrl: config.oaApiBaseUrl, oaServiceToken: config.oaServiceToken, oaIssue: config.oaIssue,
         brandIdentity: config.configProvider === "local",
+        // core 1.287 extraTools seam ([802]③ server half): SendUserFile reaches the delegated-child roster. SAME
+        // existence gate as the top-level mount (the one sendUserFileToolSpec built above — lane/tenancy/config
+        // posture already encoded in its presence). The spec is execute-time late-bound (ctx.taskId →
+        // TaskEnvRegistry lookup; emit via ALS to the top-level frame tail), so returning the SAME instance per
+        // spawn is correct — per-spawn state lives in the registry, not the spec ([797] confirmed with core).
+        // codex F1/F2 gates (subagentSendUserFileExtraTools): (F1) the subRunner carries no toolPolicy and core
+        // does not propagate the parent's policy into child specs, so an APPROVAL_DENY/ask-gated SendUserFile was
+        // reachable from delegated children — the factory now pre-checks the LIVE deployment approval face
+        // (deny/require/neverAuto, canonical-space) and injects nothing when gated (conservative stopgap until a
+        // core child-policy seam lands); (F2) read-only builtin agents (Explore/Plan) never receive the tool.
         subagentExtraTools: sendUserFileToolSpec
             ? subagentSendUserFileExtraTools({
                 spec: sendUserFileToolSpec,
@@ -1349,7 +2339,16 @@ async function main() {
             : undefined,
     };
     const scenarios = buildScenarios(scenarioDeps);
+    // design/153 件3d:/decide parked 赎回腿的裸 Agent 工具——boot 期从**内建 default** 场景工厂取一份
+    // (必须在 center overlay 盖名之前取:赎回腿要的是与 spawn 同源的生产装配,subRunner/bg opts/
+    // checkpointStore 同实例天然成立;per-request 项如 webSearch 对 revive 无关——objective 在 core
+    // driveParkedResume 里被丢弃)。checkpointStore/agentStore 任一缺席 = park 本就不可达,分支不接线。
     const parkedReviveTool = checkpointStore && backgroundAgentStore ? scenarios.default?.({})?.tools.find((t) => t.name === "Agent") : undefined;
+    // [1596]/[1597] 跨进程父约束重供席工厂:host 任务的 toolPolicy 解析槽按部署配置**同参重建**
+    // (resolveSpec durableEnabled 分支的同款折叠:durableQuestion + durableAsk 四旋钮),单层链
+    // count=1,durableMandate=true(host 有 durableApproval 且 durable 车道无 live onAsk 的恒形)。
+    // exempt 探针锚 = row.rootSessionId——与 parked decide 的 remember grant 锚同键([1591] 候裁②),
+    // 重建链上的豁免语义与原链一致。重建不出(无 root 锚)= 不供席 = core pre-CAS 门诚实拒(现状)。
     const parkedReviveInheritedGate = parkedReviveTool && config.durableApproval
         ? (row) => ({
             parentConstraints: [{
@@ -1366,8 +2365,13 @@ async function main() {
                 }],
         })
         : undefined;
+    // 场景详情:内建 details 必须在 overlay 合并【前】构建(探针要打纯内建工厂,不是被 center 顶掉的);
+    // center details 随 overlay 同判定源盖同名——source 语义与 selectScenario 实际取用永一致(约定①)。
     const scenarioDetails = builtinScenarioDetails(scenarios, scenarioDeps);
-    const builtinScenarioNames = Object.keys(scenarioDetails);
+    const builtinScenarioNames = Object.keys(scenarioDetails); // overlay 前捕获(六内建名)
+    // Center-declared scenarios (composition-as-config): overlay over the built-ins, center wins — it MAY
+    // shadow a built-in name (usability first), so shadows are logged loudly here for audit.
+    // Restart-to-apply like skills/mcp (this runs once at boot; a refresh carrying scenarios only signals).
     if (effective?.scenarios) {
         const { overlay, shadows } = centerScenarios(scenarioDeps, effective.scenarios.scenarios, Object.keys(scenarios), logger);
         Object.assign(scenarios, overlay);
@@ -1376,23 +2380,59 @@ async function main() {
             logger.info("sema_registry_scenarios", { scenarios: Object.keys(overlay), ...(shadows.length > 0 ? { shadowsBuiltin: shadows } : {}) });
     }
     logger.info("capabilities", { skills: skills.length, scenarios: Object.keys(scenarios), repoTools: Boolean(repoClient) });
+    // Background reapers: recover runs whose instance died, expire never-answered approvals, sweep
+    // rate windows. Unref'd so they never hold the process open.
+    // design/80 D-D (SLA-timer): the deny-sweep reuses the server's resumeCheckpoint, so it is wired in AFTER
+    // createHttpServer returns it (below) via this holder — the reaper is defined before the server.
     let runDenySweep;
+    // S7 (SILENT-FALLBACK P0-d): the sweeps' return counts were discarded — an instance death that batch-fails
+    // N orphans was indistinguishable from organic failures. Count + log ONLY when a sweep flipped rows (>0),
+    // so healthy ticks stay silent. Tolerant of void-returning stores (typeof guard).
     const reapCount = (metric, labels) => (n) => {
         if (typeof n === "number" && n > 0) {
             metrics.inc(metric, labels, n);
             logger.info("reaper_swept", { metric, ...labels, count: n });
         }
     };
-    let wfRunReapInFlight = false;
-    let attachmentSweepInFlight = false;
-    let bgAgentReapInFlight = false;
+    let wfRunReapInFlight = false; // 1.108 review (lens③): serialize the all-scopes retention sweep across ticks
+    let attachmentSweepInFlight = false; // 复审 F1:附件孤儿 sweep 的重入守卫(同上)
+    let bgAgentReapInFlight = false; // core 1.364: same serialization for the durable bg-agent joint reap (per-scope serial loop)
+    // core 1.364([1503] 提货单③):retention **只走** reapDurableAgents(联合 reap:条件删赢了才 release
+    // 转录 session;裸 store.reap 会 strand 转录)。staleRunning 翻转在 core 编排内先行(store.reap 一步)。
+    // scope 枚举:core 1.368 `BackgroundAgentStore.listScopes?()`([1516]② 交付,SQL twins/File 双实现
+    // 都带)——1.248 拍的「file 腿只扫 default」假设已撤;无该方法的第三方 store 仍回落 "default"(可选
+    // 接口成员,诚实回落)。
+    // sessions=subRunner.sessions —— [1522] 裁定件(③ 显式裁定形,双店真相考据后拍):bg 子代转录会话
+    // 是**双店**(ForkRoutingSessionStore):①非 fork 子代铸在 transient 店(TtlSessionStore,进程内
+    // 1h TTL)——release=内存删=**真正终结可寻址性**(转录本就不 durable;跨实例读面读的是行内
+    // finalOutput,非转录);②fork 子代铸在 host durable 店——release=lease 释放,durable 转录行**有意
+    // 保留**,留存归 session 留存策略/E21 purge 生命周期管(行先删可接受:行是执行记录,转录是会话资产,
+    // 两者生命周期本就不同)。core [1522] 复审只见 durable 腿判 HIGH——按其契约句「做不到终结可寻址性
+    // 宁可不传」,transient 类做得到、fork 类是显式裁定,维持传入。sessionsReleased 计数=「store 侧
+    // release 被调次数」(transient=真删,durable=lease 释放),非「durable 转录处置数」——如实注。
+    // 复审 F4 如实注:条件删的赢者若非写者副本,fork-routing 对未知 id 回落 transient=本地 no-op,写者
+    // 进程内 pinned 转录滞留到自身 TTL/进程退出——sessionsReleased 计数偏低是诚实读数,非缺陷。
     const reapBgAgents = backgroundAgentStore
         ? async () => {
             const store = backgroundAgentStore;
             const scopes = await (store.listScopes?.() ?? Promise.resolve(["default"]));
             let rows = 0, sessions = 0, skipped = 0, failedScopes = 0;
             for (const scope of scopes) {
+                // [1522] LOW3:per-scope 错误隔离——一个 scope 抛(坏 record_json/权限)不饿死后续 scope;
+                // 失败响亮(warn+计数),下 tick 重试。
                 try {
+                    // core 1.382([1561] 提货单④,design/153 parked 状态机对账):先对账 parked 行(checkpoint
+                    // expired/missing → 行诚实翻 failed;stale claim → 回滚 parked),再让下面既有的
+                    // reapDurableAgents 按自然节奏处置(刚翻 failed 的行本 tick 不会立刻被 maxAge 删——它是
+                    // "刚失败"的新行,不是"失败很久"的老行)。**走 registry 面**(裂脑 fence 内建于
+                    // TaskRegistry.reconcileParkedAgents 内部,不裸调 store 面——那是无活实例场景专用,core
+                    // [1561]④ 措辞)。仅在 checkpointStore 真在场时跑(同 [1561]①②「同车必接」判据——没有
+                    // checkpointStore 就不可能有真正 parked 的行,调用本身没有意义)。
+                    // 🔴 [1575] F1 修(cli 复查,红先行确认):`opts.staleClaimMaxAgeMs` 必须显式传——core 把
+                    // 整个 stale-claim 清算块(claimer 崩死回滚 + resolved-未-finalize 诚实翻 failed)门在
+                    // `staleMs !== undefined` 上,缺席不是"跳过 stale-claim 这一小步",是**整块永不运行**
+                    // (此前漏传,`bg_agents_park_reconciled_rolledback_total` 恒 0,人已做出的审批决定会被
+                    // 静默丢弃——见 config.ts backgroundAgentParkClaimStaleMs 顶注)。
                     if (checkpointStore) {
                         const pr = await defaultTaskRegistry.reconcileParkedAgents({ agentStore: store, checkpointStore }, scope, Date.now(), { staleClaimMaxAgeMs: config.backgroundAgentParkClaimStaleMs });
                         if (pr.failed > 0 || pr.rolledBack > 0) {
@@ -1401,6 +2441,8 @@ async function main() {
                             logger.info("reaper_swept", { metric: "bg_agents_park_reconciled", scope, failed: pr.failed, rolledBack: pr.rolledBack });
                         }
                     }
+                    // deps.mailbox(core 1.374,[1533]②):行删联动 F-13——agent 行 reap 时同 drop 其信箱
+                    // (盒生命周期随行终结;不挂=信箱行无 retention 无界涨)。
                     const r = await defaultTaskRegistry.reapDurableAgents(scope, { store, sessions: subRunner.sessions, ...(mailboxStore ? { mailbox: mailboxStore } : {}) }, {
                         maxAgeMs: config.backgroundAgentRetentionMs,
                         staleRunningMaxAgeMs: config.backgroundAgentStaleRunningMs,
@@ -1422,7 +2464,12 @@ async function main() {
             }
         }
         : undefined;
+    // S10 (SILENT-FALLBACK P1): the write-behind counters bucket on LOCAL floor(now/windowMs) — replica clock
+    // skew vs the DB splits a fleet window into disjoint buckets (soft-limit leak) with zero visibility. Probe
+    // the DB clock each reaper tick; the gauge is the fleet-wide skew fingerprint (can be negative).
     const probeClockSkew = async () => {
+        // Probe-ok gauge: a failing probe froze the skew gauge at its last value with zero signal —
+        // "probe ran, skew=N" vs "probe failing for 30 min" were indistinguishable.
         try {
             const dbMs = await backend?.dbNowMs?.();
             if (typeof dbMs === "number" && Number.isFinite(dbMs)) {
@@ -1435,24 +2482,54 @@ async function main() {
         }
     };
     const reaper = setInterval(() => {
-        void probeClockSkew().catch(() => undefined);
+        void probeClockSkew().catch(() => undefined); // S10
         void runStore?.reapStale(config.runStaleSec * 1000).then(reapCount("runs_reaped_total", { kind: "stale" })).catch(() => undefined);
+        // Durable F4 (design/45) + design/80 §3 inv#3 crash-safe backstop: CAS-expire checkpoints past their
+        // deadline OR their absolute terminal_at backstop (≈ deny), then fail the suspended run rows whose
+        // checkpoint was thereby expired (release task_active = unlock the session). These run EVERY tick,
+        // REGARDLESS of APPROVAL_TIMEOUT_SEC — terminal_at (stamped at put, never before an explicit deadline)
+        // bounds even a NULL-deadline pending checkpoint, so the backstop is the always-on safety net (it was
+        // inert when nested under the approvalTimeoutSec>0 guard — adversarial finding). The run-row half is
+        // checkpoint-STATE-driven (not a uniform timer) so it aligns with the per-row terminal_at. Global +
+        // idempotent across replicas, no election.
         if (checkpointStore) {
+            // 轴A #5 注释落档(1.254):core CheckpointStore.reap 契约把弃置臂的 unpin 义务派给部署 reaper——
+            // 真 pin 只存在于 in-memory TtlSessionStore;本部署 durable checkpoint 恒配 durable session 后端
+            // (pin=no-op),deny-sweep 走 resumeCheckpoint=core 内部 unpin ✓。SESSION_BACKEND=memory+durable
+            // checkpoint 的 niche dev 组合下 abort-expire 臂会把被钉会话泄到进程终——显式接受,不为 dev 形加腿。
             void checkpointStore.reapExpired(Date.now()).then(reapCount("checkpoints_reaped_total", {})).catch(() => undefined);
             void runStore?.failSuspendedWithExpiredCheckpoint().then(reapCount("runs_reaped_total", { kind: "expired_checkpoint" })).catch(() => undefined);
+            // D-D SLA-timer: resolve-DENY human/irreversible_ask gates past their deadline (graceful — the model
+            // continues with the denial), vs the abort reapExpired gives the other kinds. Bounded per tick.
             void runDenySweep?.(Date.now()).catch(() => undefined);
         }
+        // The finer, OPT-IN per-approval TTL sweeps (APPROVAL_TIMEOUT_SEC): the F4 poll-gate store + the
+        // time-based suspended-run reaper. Stay gated — reapSuspended with a 0 TTL would nuke ALL suspended rows
+        // (cutoff = now). The absolute backstop above is the safety floor; this is the operator-chosen deadline.
         if (config.approvalTimeoutSec > 0) {
             void approvalStore?.expireStale(config.approvalTimeoutSec * 1000).catch(() => undefined);
             void runStore?.reapSuspended(config.approvalTimeoutSec * 1000).then(reapCount("runs_reaped_total", { kind: "suspended" })).catch(() => undefined);
         }
+        // GC checkpoint_ctx rows whose checkpoint is gone (bound to the checkpoint lifecycle).
         void checkpointStore?.reapCtx(Date.now() - config.runStaleSec * 1000).catch(() => undefined);
         rateLimiter?.sweep();
         if (costQuota instanceof CostQuota)
-            costQuota.reap();
-        void toolResultStore?.reapOlderThan?.(Date.now() - config.toolResultTtlSec * 1000)?.catch(() => undefined);
+            costQuota.reap(); // TiDB variant self-reaps in its flush loop
+        void toolResultStore?.reapOlderThan?.(Date.now() - config.toolResultTtlSec * 1000)?.catch(() => undefined); // optional extra: SQL twins only (the local FileToolResultStore persists like transcripts)
+        // 2c session-sync: GLOBALLY GC grace-window orphan blobs (standalone /sync/blobs PUTs that were never
+        // imported are otherwise collected only on reap()/deleteBySession(), which never fire for a never-imported scope).
+        // Bounds the standalone-PUT orphan-blob exhaustion (review finding) to the grace window. Durable twins only (local
+        // omits the seam → optional-chained no-op).
         void fileSnapshotStore?.sweepOrphanBlobs?.().catch(() => undefined);
+        // D-1 附件 TTL:上传后从未被任何 task 引用(session_id NULL)且超过 attachmentUnboundTtlMs 的行收割
+        // (绑定行不在此收——随会话 E21 级联删)。best-effort,与其余 reaper 腿同姿。
         void taskAttachmentStore?.reapUnbound(Date.now() - config.attachmentUnboundTtlMs).then(reapCount("attachments_reaped_total", {})).catch(() => undefined);
+        // D-1 孤儿**对象**彻底 GC(clay 拍 2026-07-28):对象存储 × meta 行对账,grace 默认 1h(上传先行窗
+        // 保护;`ATTACHMENT_ORPHAN_GRACE_MS=0` 关掉本腿——同 tick 邻居都有旋钮,复审 F10)。
+        // 列举失败=本轮 warn 跳过(「列不出来」绝不当「没有孤儿」),下轮再试。
+        // 🔴 复审 F1:必须 in-flight 守卫——本腿时长随对象总数增长(20 万对象实测秒级、百万级可达 30s),
+        // 无守卫时超过 tick 间隔即逐 tick 叠加(实测叠 6 层),同时压 LIST/SQL/DELETE 三面。邻居
+        // wfRunReap/bgAgentReap 都有同款守卫。
         if (config.attachmentOrphanGraceMs > 0 && !attachmentSweepInFlight && taskAttachmentStore?.sweepOrphanObjects) {
             attachmentSweepInFlight = true;
             void taskAttachmentStore
@@ -1464,29 +2541,61 @@ async function main() {
                 .catch((err) => logger.warn("attachment_orphan_sweep_failed", { err: String(err) }))
                 .finally(() => { attachmentSweepInFlight = false; });
         }
+        // P1d-β 2c session-sync: GC ABANDONED staged imports — staging-id session_event rows (`%#stg-%`) with NO
+        // session_meta whose oldest row is older than the grace window (an in-flight stream stays fresh → never reaped).
+        // Bounds the orphan-staging-row growth (a Phase B that opened a staging then never committed). Durable session
+        // stores only (the local backend stages in memory → no durable rows; the seam is absent → optional-chained no-op).
         void backend?.session()?.sweepStagingSessions?.().catch(() => undefined);
+        // Bake-runner backstop (§P2.7): fail any `running` bake whose lease went stale (the runner crashed mid-build),
+        // append a synthetic terminal `done{failed}` so SSE readers settle, and force-release the single-flight lease.
+        // staleMs (≈3× the 30s heartbeat) bounds a healthy slow build so it is never wrongly reaped.
         void imageBakes?.reapStaleBakes(config.imageBakes.staleMs).then(reapCount("bakes_reaped_total", {})).catch(() => undefined);
+        // SVC-3 worktree isolation: deregister worktrees orphaned by a process crash (the Runner never reached
+        // destroy → `git worktree remove` never ran). `git worktree prune` cleans registrations whose dirs are
+        // already gone. Best-effort, userland (core ships no post-kill Runner hook); never throws. Unset = no-op.
         void worktreeReap?.();
+        // SVC-1 (adversarial-review HIGH): PERIODIC notify-recovery sweep (not just at boot) — re-delivers a terminal
+        // run whose in-process notify was lost, AND finalizes-as-abandoned a `running` run orphaned past the grace
+        // window (core never resumes/reaps a prior `running` row, so nothing else would). Idempotent; best-effort.
         void workflowNotifyGate?.recover({ orphanGraceMs: config.workflowOrphanGraceMs }).catch(() => undefined);
+        // SVC-2 (adversarial-review HIGH): time-based GC of the workflow_journal table (the heaviest, TaskResult-bearing
+        // one) — the per-run deleteByRun has no run-store reap hook, so this bounded sweep is what stops unbounded
+        // growth. A resume of a journal older than the retention window re-runs live (resume is an optimization).
         void workflowJournalStore?.reapExpired?.(Date.now(), config.workflowJournalRetentionMs).catch(() => undefined);
+        // Retention (WorkflowRunStore never auto-purges, reap is explicit):
+        // age out TERMINAL workflow_run rows across ALL scopes. SQL twins only (reapAllScopes is their DISTINCT-scope
+        // extension; the contract itself has no cross-scope enumeration, and the File store keeps the transcripts-like
+        // keep-everything posture). Running rows are untouched — the orphan-grace sweep above owns those.
+        // In-flight guard (1.108 review, lens③): the sweep enumerates EVERY scope serially — under a short
+        // REAP_INTERVAL_SEC + many scopes, overlapping sweeps would pile up on the pool. One at a time.
         if (!wfRunReapInFlight) {
             const sweep = sqlWorkflowRunStore?.reapAllScopes?.(Date.now(), { maxAgeMs: config.workflowRunRetentionMs });
             if (sweep) {
                 wfRunReapInFlight = true;
                 void sweep.catch(() => undefined).finally(() => (wfRunReapInFlight = false));
             }
+            // 1.108: SQL notify-journal retention rides the same knob — ACKED rows are pure history (pending rows are
+            // the recovery backlog and are NEVER reaped; the orphan-grace sweep retires a stuck pending run).
             void workflowNotifyJournal
                 ?.reapAcked?.(Date.now() - config.workflowRunRetentionMs)
                 .catch(() => undefined);
         }
+        // core 1.364 durable bg-agent joint reap(定义在 interval 上方,契约注释在彼)。in-flight 守卫同
+        // wfRun sweep(per-scope 串行循环,短 tick + 多 scope 下不叠罗汉)。
         if (reapBgAgents && !bgAgentReapInFlight) {
             bgAgentReapInFlight = true;
             void reapBgAgents().catch(() => undefined).finally(() => (bgAgentReapInFlight = false));
         }
+        // [1522] MED2:agent_roster TTL 清理(core RB-23②③ 派给部署的半场)——SQL twins 扩展面
+        // (reapOlderThan,duck probe;File/Memory 店 core 自带 maxAgeMs,无此面=no-op)。
         void rosterStore
             ?.reapOlderThan?.(Date.now() - config.rosterRetentionMs)
             .then(reapCount("roster_rows_reaped_total", {}))
             .catch(() => undefined);
+        // 修8(三路复审 absorb-2,接线 (b)):periodic scratchpad sweep — 无 E21 purge 兜到的孤儿目录(session 从未
+        // DELETE、purge 当次失败、local 后端无 purge coordinator)按 mtime 过期回收。SCRATCHPAD_SWEEP_TTL_MS
+        // (default 7d,0=禁用)。activeSessionIds 不传:活跃判据的诚实边界在 env-facts.ts 的 sweep 文档——TTL 7d
+        // 远大于任何在飞任务;一个 7 天零写入的 scratchpad 被回收是可接受的(它本就是临时区,fact 文案即如此宣示)。
         if (config.scratchpadSweepTtlMs > 0) {
             void sweepStaleScratchpads(config.localDataRoot ?? localRoot, { olderThanMs: config.scratchpadSweepTtlMs })
                 .then((removed) => {
@@ -1497,29 +2606,69 @@ async function main() {
         }
     }, config.reapIntervalSec * 1000);
     reaper.unref?.();
+    // Optional OTLP/HTTP metrics export (1.37). Periodically pushes the registry to an OTel collector;
+    // best-effort (a collector outage is logged, never affects serving). /metrics stays available too.
     const otelExporter = config.otel
         ? startOtlpExporter(metrics, {
             ...config.otel,
             onError: (err) => logger.warn("otel_export_failed", { err: String(err) }),
         })
         : undefined;
+    // Config refresh: re-pull with the ETag; teams hot-reload via the registry. A models/roles
+    // change updates config but the live Runner keeps its startup set — logged so ops restart to apply.
+    // 提示词装配协议 §9.5-1/-3: the loop goes through the ConfigProvider seam (never the raw HTTP fetch —
+    // one resolver, no remote/local drift) and runs for the LOCAL provider too: config.d edits are picked
+    // up by the same 60s poll (the local provider's etag = the store's raws hash, so an unchanged tree is
+    // a cheap null and a corrupt↔fixed flip bumps the version). Local mode previously read config.d
+    // exactly once at boot.
     if (configProvider) {
         const ccRef = config.configCenter;
+        // Single-flight (codex F2): an async tick body under setInterval has no serialization — a slow read
+        // (degraded disk/远端) outliving the 60s interval would let a LATER tick apply a newer candidate and
+        // the stalled OLDER read then complete and roll the config (and ccEtag) back. Skip the tick while one
+        // is in flight; the flag flips in `finally`, so a throw never wedges the loop shut.
         let refreshInFlight = false;
         const refreshTick = async (prefetched) => {
             if (refreshInFlight)
                 return;
             refreshInFlight = true;
             try {
+                // codex-3/4 F1:欠账的 catalog 过渡在**每个真拍**开头无条件重试——与 fetch 成败/候选好坏解耦
+                // (304、fetch 抛错、候选被整拒的拍此前全都跳过重试=盘错恢复后过渡仍卡死)。次序安全:本拍
+                // 若随后采用了更新候选,adopt 自会覆盖/清空 pending(先重试旧账、后采新目标,永不倒退)。
                 await retryPendingCatalog("refresh-retry");
+                // codex R18: the stuck-deferred state must not vanish behind the advanced etag — re-warn + count on
+                // EVERY tick (incl. 304s and fetch-error ticks) while it persists; /health carries the same state.
+                // The RECOVERY (persist retry + promotion) moved BELOW the fetch (codex R29): promoting before
+                // adjudicating the current source generation could publish a SUPERSEDED candidate N as the
+                // boot-visible LKG while N+1 exists — a restart in that window resurrects withdrawn config.
                 if (planeDeferredNoHandoff) {
                     metrics.inc("models_tiers_plane_deferred_stuck_total");
                     logger.warn("models_tiers_deferred_no_handoff", { version: planeDeferredNoHandoff.version, since: planeDeferredNoHandoff.since, note: "candidate still retained without a next-boot handoff — mount restart-surviving LKG storage + CONFIG_LKG_DURABLE=true, or restart manually after ensuring the candidate is re-pulled at boot" });
                 }
+                // F3(LKG 复审):LKG-boot 的 deferred 到货把 unconditional 结果直接喂进来——丢弃它再按 LKG 的
+                // etag 条件拉,会在「center 重建且 etag 值撞旧」的场景永远 304=陈旧配置钉死;消费原始结果则
+                // 应用后 ccEtag=真实新值,陈旧面消除(顺带省一次拉取)。
                 const r = prefetched !== undefined ? prefetched : await configProvider.fetchEffective(ccEtag);
+                // codex R23/R29 recovery lane: a 304 (r === null) CONFIRMS the retained candidate's generation is
+                // still the source's current one (its etag advanced when it was retained) — only then is it safe to
+                // retry persistence and promote the withheld restart signal. A fetch that returned a NEWER candidate
+                // takes the normal branches below (which replace/supersede the retained state); a fetch that THREW
+                // never reaches here (freshness unknown ⇒ no promotion this tick). Retry only where promotion is
+                // possible (durable-declared lane; R37 adds the non-durable skills-debt lane, whose retry doubles as
+                // the repair proof) — elsewhere a per-tick write could never promote and just burns IO.
                 if (r === null && planeDeferredNoHandoff) {
+                    // Retry where promotion is possible: the durable-declared lane (full handoff), and — codex R37 —
+                    // the NON-durable skills-debt lane, where the retry's body prewarm+verify is the repair PROOF that
+                    // gates the withheld skills restart (see lastPrewarmBodiesVerified).
                     const skillsDebt = (planeDeferredNoHandoff.blocked ?? []).includes("skills");
                     const promoted = lkgSurvivesRestart || skillsDebt ? await persistLkgDurable(planeDeferredNoHandoff.candidate, planeDeferredNoHandoff.candidateEtag) : false;
+                    // codex R37 proof-gated promotion (non-durable lane): every enabled body now hash-verifies on disk
+                    // ⇒ the center + body endpoint are BOTH live, a restarted process re-pulls successfully — publish
+                    // the skills restart exactly now, never on manifest-success alone (restart-storm breaker: a boot
+                    // that fails the body again lacks the proof and returns to visible-debt, not to signaling).
+                    // models-tiers never rides this arm (R16: a FORCED plane restart requires a durable handoff), so a
+                    // retained candidate that ALSO defers the plane keeps everything withheld until durability exists.
                     const skillsProofPromotion = !promoted && !lkgSurvivesRestart && skillsDebt && lastPrewarmBodiesVerified && planeDeferredNoHandoff.planeDeferred !== true;
                     if (skillsProofPromotion) {
                         pendingRestart = { restartRequired: true, reasons: ["skills"], version: planeDeferredNoHandoff.version, since: Date.now() };
@@ -1527,6 +2676,10 @@ async function main() {
                         planeDeferredNoHandoff = undefined;
                     }
                     else if (promoted) {
+                        // models-tiers joins only when the PLANE was deferred (codex R27: a skill-only retained candidate
+                        // must not manufacture a plane reason on promotion). codex R30: an EMPTY promotion (boot
+                        // publication retry — nothing was withheld, everything already applied) publishes NO restart
+                        // signal; it just completes the LKG and clears the state.
                         const promotedReasons = [...new Set([...(planeDeferredNoHandoff.blocked ?? []), ...(planeDeferredNoHandoff.planeDeferred ? ["models-tiers"] : [])])];
                         if (promotedReasons.length > 0) {
                             pendingRestart = { restartRequired: true, reasons: promotedReasons, version: planeDeferredNoHandoff.version, since: Date.now() };
@@ -1536,6 +2689,17 @@ async function main() {
                     }
                 }
                 if (r) {
+                    // §9.5-5 candidate gate: ANY invalid domain rejects the WHOLE candidate — the live config
+                    // keeps serving the LKG (`latestEffective`) instead of that domain falling to schema-default/
+                    // empty. ccEtag is deliberately NOT advanced: the bad tree stays visible (re-judged each poll),
+                    // and fixing the file bumps the version so the next poll lands. The dedupe key is the SORTED
+                    // de-duplicated domain set (codex F3: the collector's ordering isn't guaranteed, a raw join
+                    // would re-warn every poll), and the first warn carries the full per-domain error detail —
+                    // that's the actionable diagnosis, the key only mutes repeats. The prompts-domain artifact
+                    // validation (core S1) hooks into this same gate when it ships.
+                    // F6(二轮复审):prompts 面判形进候选门——坏 pack(重复 id/空数组/坏信封)若只在 boot 验,
+                    // refresh 会带着它推进 etag+发 restart 信号,重启后 boot 拒之回内置=好包 A 被坏包 B 顶掉。
+                    // 这里与 domainErrors 同门:坏形=整拒候选(etag 不进,LKG/现用包 A 继续服务,持续 warn 到修复)。
                     const promptsRaw = r.effective.prompts;
                     const promptsGate = promptsRaw !== undefined ? validatePromptsDomain(promptsRaw) : { ok: true };
                     const badDomains = [
@@ -1560,11 +2724,28 @@ async function main() {
                         return;
                     }
                     lastRejectedCandidate = undefined;
+                    // ccEtag advances at the END of each branch (codex lens-1 HIGH): advancing before apply meant
+                    // an applyEffective throw mid-way left a MIXED-generation live config AND a cached etag — the
+                    // next poll 304'd, so the failed candidate was never retried. Now a throw keeps the old etag,
+                    // the next poll re-fetches the same candidate, and the (idempotent) re-apply self-heals.
                     if (ccRef?.dryRun) {
-                        logEffectiveDiff(config, r.effective, logger);
+                        logEffectiveDiff(config, r.effective, logger); // compare-only: surface ongoing center changes, apply nothing
                         ccEtag = r.etag;
                     }
                     else {
+                        // refresh: teams + runtime governance + MODELS/ROLES/ROSTER now hot. teamsOnly skips
+                        // only the boot-only runtime GATES (rate/cost/approval). applyEffective mutates config.models/roles
+                        // IN PLACE (the Runner's live ref) — but `pricing` (separate object the Runner also reads live) and
+                        // `keyResolver` (closes over modelApiKeyEnv) are ours to refresh.
+                        // codex R10: hot-apply of the MODEL PLANE holds ONLY when the Runner shares our map (tier-less at
+                        // construction). A tier-frozen Runner keeps a private expanded copy — hot-applying a changed plane
+                        // would split admission from execution (same-key retarget silently routes/bills the stale Model
+                        // object through the restart window). Defer the plane; the models-tiers slice below signals the
+                        // orchestrator; the restarted process applies it at boot BEFORE Runner construction.
+                        // codex R12: defer also when the CANDIDATE activates tiers on a tier-less-booted Runner — it never
+                        // re-runs expandTiers, so hot-applying the arriving tier table would let tier words pass the
+                        // expanded admission gate while core throws "Unknown model ref" until restart. Hot-apply is safe
+                        // only when BOTH generations are tier-less.
                         const planeDeferred = (runnerTierFrozen || planeHasActiveTiers(r.effective)) && modelPlaneChanged(appliedPlaneEff, r.effective);
                         applyEffective(config, r.effective, logger, { teamsOnly: true, sealedKeys, ...(planeDeferred ? { deferModelPlane: true } : {}) });
                         if (planeDeferred) {
@@ -1572,36 +2753,87 @@ async function main() {
                         }
                         else {
                             appliedPlaneEff = r.effective;
-                            planeDeferredNoHandoff = undefined;
+                            planeDeferredNoHandoff = undefined; // plane landed — the stuck state (if any) is resolved
                         }
-                        await adoptCenterPrompts(r.effective, "refresh");
+                        await adoptCenterPrompts(r.effective, "refresh"); // 热采用(core 1.316 声明轴:新任务边界自动重 pin,见 ref 注释)
+                        // codex R13: readiness may open ONLY off an APPLIED plane — a deferred candidate's roster is not
+                        // installed (config.models still the old/placeholder generation), so opening the billable gate on
+                        // it would route/bill the wrong model until restart. Deferred ⇒ gate stays as-is; the restarted
+                        // process applies the candidate pre-Runner and opens it at boot.
                         if (!planeDeferred)
-                            markRosterLanded(r.effective);
-                        mutateInPlace(pricing, buildPricing(config.models));
-                        keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
+                            markRosterLanded(r.effective); // boot pull 失败/未发布时,refresh 落 roster 同样开门
+                        mutateInPlace(pricing, buildPricing(config.models)); // hot: cost/model changes; Runner reads this.deps.pricing live
+                        keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys); // hot: per-model key add/remove/change (env-ref + sealed)
+                        // skills/mcp/scenarios/runtime-gates are baked into the live process at boot (buildScenarios / boot
+                        // middleware) — a refresh carrying a DIFFERENT value can't hot-apply, only a restart re-reads them.
+                        // We compare against the BOOT snapshot (`effective`), NOT presence: an orchestrator auto-restarts on
+                        // a non-empty `reasons` WITHOUT a restart loop (same diff every 60s is idempotent, not a fresh trigger).
+                        // Sticky `since`: keep the first-detected timestamp while `reasons` is unchanged; reset it when the set
+                        // changes; CLEAR the signal when a later pull reverts to boot (reasons empty) — restart no longer needed.
+                        // F2(LKG 复审):落盘 **await 且先于** restart 信号可见——orchestrator 见信号即杀进程,
+                        // fire-and-forget 的 rename 可能没完成 → 下一进程读旧 LKG → 同差异重现 = 本功能要消的环。
+                        // 顺序=先持久化(含 skill 正文预热,F1)再发信号;持久化失败=warn+照发(不发=配置永不生效;
+                        // 「盘坏+中心挂」双故障下环重现,接受并点名)。
                         const lkgPersisted = await persistLkgDurable(r.effective, r.etag);
                         const reasons = restartReasons(effective, r.effective);
+                        // codex R35: the sticky boot skill debt rides EVERY tick's reasons — change-detection vs boot is
+                        // blind to it (the stale table IS the boot baseline). Under a no-handoff deferral it folds into
+                        // blocked (promoted later); otherwise it keeps pendingRestart alive until the restart happens.
+                        // codex R38: change-DETECTED skills (manifest actually changed) is distinguished from the sticky
+                        // rider — the former keeps the pre-existing documented posture (rides regardless; the restart
+                        // pulls the NEW generation live), the latter is proof-gated below on the non-durable lane.
                         const skillsChangeDetected = reasons.includes("skills");
                         if (bootSkillStale && !skillsChangeDetected)
                             reasons.push("skills");
+                        // codex R15/R16/R19: a DEFERRED plane is adjudicated by HANDOFF STATUS alone — independent of
+                        // whether change-detection already produced the reason (R19: an already-present models-tiers with
+                        // no handoff sailed through = the exact storm R16 closed). With a confirmed next-boot handoff the
+                        // reason is ensured present (R15: env-baseline blind spot) and the stuck state clears; without one
+                        // the reason is SUPPRESSED (a restart the next process cannot satisfy — over-budget boot pull + no
+                        // LKG — is a rolling-restart storm) and the persistent stuck state + per-tick warn carry the
+                        // observability instead. Non-plane reasons (skills/mcp/…) keep riding either way.
                         if (planeDeferred) {
                             if (lkgPersisted) {
                                 if (!reasons.includes("models-tiers"))
                                     reasons.push("models-tiers");
-                                planeDeferredNoHandoff = undefined;
+                                planeDeferredNoHandoff = undefined; // handoff exists — the restart signal carries observability
                             }
                             else {
+                                // codex R22: suppress the candidate's ENTIRE restart signal, not just models-tiers — a
+                                // co-occurring skills/mcp reason would still restart the worker, and with no handoff the
+                                // replacement can't land ANY of this candidate (same over-budget pull) = the same storm.
+                                // The blocked reasons stay observable (state + warn) and promote once a handoff exists.
                                 const blocked = reasons.splice(0, reasons.length);
                                 planeDeferredNoHandoff = { version: r.effective.version, since: planeDeferredNoHandoff?.since ?? Date.now(), ...(blocked.length > 0 ? { blocked } : {}), planeDeferred: true, candidate: r.effective, ...(r.etag !== undefined ? { candidateEtag: r.etag } : {}) };
                                 logger.warn("models_tiers_deferred_no_handoff", { version: r.effective.version, blockedReasons: blocked, note: "plane deferred but no NEXT-BOOT handoff (LKG disabled/unwritable, or storage not declared restart-surviving — set CONFIG_LKG_DURABLE=true) — the WHOLE restart signal is withheld (it would loop); the old generation keeps serving" });
                             }
                         }
                         else if (lkgSurvivesRestart && !lkgPersisted) {
+                            // codex R27/R31: retention is NOT conditional on restart reasons — a hot-only candidate
+                            // (autonomy/prompts/teams/tier-less models) with a failed publication would otherwise advance
+                            // the etag and never retry (304s), and a restart during a center outage would roll back to the
+                            // older LKG (weaker governance). blocked may be [] = publication-only recovery (R30 promotion
+                            // publishes no signal for an empty set).
+                            // codex R27: a DURABLE-DECLARED deployment whose candidate publication is incomplete (skill-body
+                            // verify failed → LKG not replaced) must not signal restart off that candidate either — the next
+                            // boot would land the OLD LKG and re-signal while the center stays unavailable. Retain + withhold
+                            // + per-tick retry-promote, same machinery as the deferred plane (no models-tiers added on
+                            // promotion — the plane was NOT deferred here). Non-declared deployments keep the pre-existing
+                            // documented posture (restart converges off a live boot pull when the center is healthy).
                             const blocked = reasons.splice(0, reasons.length);
                             planeDeferredNoHandoff = { version: r.effective.version, since: planeDeferredNoHandoff?.since ?? Date.now(), blocked, candidate: r.effective, ...(r.etag !== undefined ? { candidateEtag: r.etag } : {}) };
                             logger.warn("restart_candidate_publication_incomplete", { version: r.effective.version, blockedReasons: blocked, note: "durable LKG declared but the candidate's publication is incomplete (skill bodies unverified) — restart signal withheld; retried every tick until the cache completes" });
                         }
                         else if (!planeDeferred && !lkgSurvivesRestart && bootSkillStale && !skillsChangeDetected && !lastPrewarmBodiesVerified) {
+                            // codex R38: the NON-durable lane's sticky rider must clear the SAME proof gate as the boot/304
+                            // arms (R37) — a same-generation 200 (center omits/rotates ETags or ignores conditionals) lands
+                            // here with reasons=[skills] purely from the sticky debt, and publishing it unproven re-opens
+                            // the restart storm R37 closed (every replacement fails the same body, 200s again, signals
+                            // again). persistLkgDurable just ran for THIS candidate, so the proof flag is current: unproven
+                            // ⇒ strip the rider from the publishable set and retain it as visible debt (the same
+                            // planeDeferredNoHandoff machinery the 304 recovery lane re-verifies and proof-promotes).
+                            // Proven or durable-handoff ⇒ the rider rides as before. Change-DETECTED skills is exempt
+                            // (pre-existing posture — the restart pulls the NEW generation, a different repair claim).
                             const i = reasons.indexOf("skills");
                             if (i >= 0) {
                                 reasons.splice(i, 1);
@@ -1620,10 +2852,17 @@ async function main() {
                         }
                         logger.info("sema_registry_refreshed", {
                             version: r.effective.version,
+                            // hot-applied: teams + runtime governance (autonomy/commandPolicy) + MODELS/ROLES/ROSTER (+pricing
+                            // +per-model keys). Still restart-to-apply: skills/mcp/scenarios + runtime GATES (rate/cost/approval).
                             note: "teams + runtime governance + models/roles/roster hot-applied; skills/mcp/runtime-gates/scenarios are restart-to-apply",
+                            // Structured signal: orchestrator consumes the SAME object via GET /health.restart.
                             ...(pendingRestart ? { restartRequired: true, restartReasons: pendingRestart.reasons } : {}),
                         });
-                        latestEffective = r.effective;
+                        // BOTH the LKG and the etag advance ONLY after the whole apply/pricing/keyResolver/restart
+                        // chain succeeded (codex lens-3): if any step above throws, latestEffective keeps pointing at
+                        // the last FULLY-applied candidate and the etag stays put, so the next poll re-fetches and
+                        // re-applies the same candidate (idempotent self-heal) — the LKG never names a half-applied one.
+                        latestEffective = r.effective; // LKG advance (§9.5-2): candidate validated + fully applied
                         ccEtag = r.etag;
                     }
                 }
@@ -1637,9 +2876,21 @@ async function main() {
         };
         const ccTimer = setInterval(() => void refreshTick(), 60_000);
         ccTimer.unref?.();
+        // Boot-deferred continuation(二轮复审 F5 改形):到货结果按「迟到的 boot」处理,而不是转普通 tick——
+        // 普通 tick 的 restartReasons(undefined, r) 会把 prompts/skills 面全判为差异 → restart → 中心持续慢时
+        // 下一进程又 deferred → 无限重启环。迟到 boot:①候选门同 F6(坏形=拒,cadence 重判);②热面
+        // teamsOnly apply(boot-only gates/skills/mcp 已按 env 建,迟到不可应用——诚实);③prompts adopt
+        // (进程刚起、会话面≈空,失真面⊆重启路径,且 adopt 后 prompts 不再贡献 restart 理由=prompts 无环);
+        // ④一次性诚实 restart 信号=剩余 restart-to-apply 面(skills/mcp/scenarios/gates)非空才发;⑤基线
+        // `effective`/LKG/etag 落位 → 后续 cadence 与到货值比较,不重复触发。⚠️ 残余环面(诚实记账):center
+        // 发布了 skills/mcp 且中心**持续**慢于 boot 预算时,每个新进程仍会为真缺失的 skills 面发一次 restart
+        // ——完整解=LKG 落盘(boot 直读上个进程的干净候选),已报 clay 裁量。
         const deferredBootApply = async (r) => {
             if (!r)
                 return;
+            // F6(LKG 复审三轮):与 cadence tick 同一 single-flight 车道——deferred 的 skill 预热可能拖过 60s,
+            // 期间 cadence 落了更新的候选 B,A 迟到完成再覆盖盘/信号=回滚。inFlight 时直接让行(丢弃 deferred
+            // 结果无损:cadence 已经/即将拉到更新的),持有 flag 至信号发布后。
             if (refreshInFlight)
                 return;
             refreshInFlight = true;
@@ -1666,6 +2917,9 @@ async function main() {
                 ccEtag = r.etag;
                 return;
             }
+            // codex R10 (deferred-boot twin of the refresh-lane guard): the Runner was built from the ENV plane before
+            // this late arrival — if it froze a tier-expanded copy, the arriving center plane must not hot-apply
+            // (admission/Runner split). Tier-less env boot (the common deferred-boot shape) keeps true hot-apply.
             const planeDeferredLate = (runnerTierFrozen || planeHasActiveTiers(r.effective)) && modelPlaneChanged(appliedPlaneEff, r.effective);
             applyEffective(config, r.effective, logger, { teamsOnly: true, sealedKeys, ...(planeDeferredLate ? { deferModelPlane: true } : {}) });
             if (planeDeferredLate)
@@ -1676,14 +2930,23 @@ async function main() {
             }
             await adoptCenterPrompts(r.effective, "boot-deferred");
             if (!planeDeferredLate)
-                markRosterLanded(r.effective);
+                markRosterLanded(r.effective); // codex R13: same guard as the refresh lane — never open readiness off an unapplied plane
             mutateInPlace(pricing, buildPricing(config.models));
             keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
-            effective = r.effective;
+            effective = r.effective; // restart 比较基线=到货值(cadence 不再重复触发)
             latestEffective = r.effective;
             ccEtag = r.etag;
-            const lkgPersistedLate = await persistLkgDurable(r.effective, r.etag);
-            const reasons = restartReasons(undefined, r.effective);
+            const lkgPersistedLate = await persistLkgDurable(r.effective, r.etag); // F2 parity:信号可见前落盘+skill 正文预热
+            const reasons = restartReasons(undefined, r.effective); // (prompts 不在 restart slices——热采用已在上方 adopt)
+            // codex R15 (late-boot twin): tiered env boot + tier-less late candidate ⇒ deferral fires but BOTH slice
+            // fingerprints reduce to null (undefined baseline, tier-less candidate) — no models-tiers reason, plane
+            // deferred forever. Deferral is the ground truth; force the reason so the orchestrator restarts and the
+            // next process lands the candidate at boot. codex R16: forced ONLY with a confirmed LKG handoff — without
+            // it the restarted process re-enters this exact lane (env plane, late candidate) = restart storm; keep
+            // serving the old generation and warn instead.
+            // codex R19 (late-boot twin): handoff status decides, regardless of whether change-detection already
+            // produced the reason — an active-tier candidate over an env boot deterministically carries models-tiers
+            // from restartReasons(undefined, candidate), and letting it through with no handoff is the R16 storm.
             if (planeDeferredLate) {
                 if (lkgPersistedLate) {
                     if (!reasons.includes("models-tiers"))
@@ -1691,12 +2954,16 @@ async function main() {
                     planeDeferredNoHandoff = undefined;
                 }
                 else {
+                    // codex R22 (late-boot twin): withhold the WHOLE signal — co-occurring skills/mcp reasons would
+                    // restart into the same over-budget/no-LKG lane and loop.
                     const blocked = reasons.splice(0, reasons.length);
                     planeDeferredNoHandoff = { version: r.effective.version, since: planeDeferredNoHandoff?.since ?? Date.now(), ...(blocked.length > 0 ? { blocked } : {}), planeDeferred: true, candidate: r.effective, ...(r.etag !== undefined ? { candidateEtag: r.etag } : {}) };
                     logger.warn("models_tiers_deferred_no_handoff", { version: r.effective.version, blockedReasons: blocked, note: "late-boot plane deferred but no NEXT-BOOT handoff (see CONFIG_LKG_DURABLE) — the WHOLE restart signal is withheld (it would loop); old generation keeps serving" });
                 }
             }
             else if (planeDeferredLate === false && lkgSurvivesRestart && !lkgPersistedLate) {
+                // codex R31 (late-boot twin): retain failed publications even with zero restart reasons.
+                // codex R27 (late-boot twin): durable-declared + incomplete publication ⇒ retain + withhold + retry.
                 const blocked = reasons.splice(0, reasons.length);
                 planeDeferredNoHandoff = { version: r.effective.version, since: planeDeferredNoHandoff?.since ?? Date.now(), blocked, candidate: r.effective, ...(r.etag !== undefined ? { candidateEtag: r.etag } : {}) };
                 logger.warn("restart_candidate_publication_incomplete", { version: r.effective.version, blockedReasons: blocked, note: "late-boot candidate publication incomplete on a durable-declared deployment — restart signal withheld; retried every tick" });
@@ -1705,19 +2972,32 @@ async function main() {
                 pendingRestart = { restartRequired: true, reasons, version: r.effective.version, since: Date.now() };
             logger.info("config_loaded_deferred", { source: configProvider.kind, version: r.effective.version, models: (r.effective.models?.models ?? []).filter((m) => m.enabled !== false).length, ...(reasons.length > 0 ? { restartRequired: true, restartReasons: reasons } : {}) });
         };
+        // LKG 起服的进程有完整 boot 基线 → 到货走普通 tick(候选门+hot+对 LKG 的 restartReasons,通常
+        // 零差异=无信号无环);env 起服(无 LKG)才走「迟到 boot」路径。
         if (bootConfigPending)
             void bootConfigPending.then((r) => (lkgBooted ? refreshTick(r) : deferredBootApply(r)), () => { });
     }
+    // Per-model API key (sema-registry `apiKeyEnv`): resolve each model's own upstream key per brain call /
+    // cascade rung. undefined when no per-model keys are configured → spec field stays unset (core default).
+    // `let` (not const): rebuilt on a sema-registry refresh so per-model key ADDITIONS hot-apply too (the
+    // resolver is undefined when no per-model keys exist, so in-place mutation alone wouldn't cover empty→non-empty).
     let keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
+    // PAIR-REVIEW F-6:Bearer-only 网关 × per-model key 组合死角的 boot 响亮告警——core 的 per-call auth 是
+    // **整体替换**语义(1.345:per-call apiKey 在场即剥构造期 Authorization,x-api-key 成唯一凭据),而
+    // key-resolver 只会产 { apiKey } 形;部署若以 ANTHROPIC_AUTH_TOKEN(Bearer)直连此类网关,则每个配了
+    // per-model key 的模型必 401 且无从自诊。headers 形支持候 core/registry additive 席位(跨仓件);此前
+    // 先把组合不可用讲清楚。只 warn 不拒:混合网关(两种头都收)是存在的,fail-open+可诊断。
     if (process.env.ANTHROPIC_AUTH_TOKEN && !process.env.ANTHROPIC_API_KEY && (Object.keys(config.modelApiKeys).length > 0 || Object.keys(config.modelApiKeyEnv).length > 0)) {
         logger.warn("per_model_key_bearer_gateway_combo", {
             perModelKeys: Object.keys(config.modelApiKeys).length + Object.keys(config.modelApiKeyEnv).length,
             note: "ANTHROPIC_AUTH_TOKEN (Bearer) deployment with per-model keys: core's per-call auth REPLACES the Authorization header with x-api-key for those models — a Bearer-only gateway will 401 them. Remove the per-model key for such models, or use a gateway accepting x-api-key.",
         });
     }
+    // Audit回溯 + degenerate-output instrument are TiDB-specific raw-SQL consumers (outside the store
+    // abstraction); they run only on the TiDB backend (the mysql2 pool), and are a no-op on PG until ported.
     const mysqlPool = backend?.mysqlPool();
-    const auditPgPool = backend?.pgPool();
-    const auditLocalRoot = backend?.kind === "local" ? (config.localDataRoot ?? localRoot) : undefined;
+    const auditPgPool = backend?.pgPool(); // the audit face now has a PG twin — web session area lights up on DB_BACKEND=pg
+    const auditLocalRoot = backend?.kind === "local" ? (config.localDataRoot ?? localRoot) : undefined; // the File leg
     const ownerAware = sessionStore;
     const sessionAudit = mysqlPool || auditPgPool || auditLocalRoot
         ? async (sessionId) => {
@@ -1731,6 +3011,24 @@ async function main() {
             return { ...audit, owner: (await ownerAware.ownerOf?.(sessionId)) ?? null };
         }
         : undefined;
+    // §0.5 E21 — DELETE /v1/sessions/:id purge coordinator. Deletes the session abstraction's CONVERSATION HISTORY
+    // (sessionStorage.deleteSession → session_meta/session_event) PLUS the service-owned operational rows for that
+    // session: the runs ledger (runStore.deleteBySession → task_run/task_active/task_event, owner-guarded), the
+    // durable checkpoints + resume-ctx (checkpointStore.deleteBySession, present only under DURABLE_APPROVAL), and
+    // offloaded tool results (toolResultStore.deleteBySession). Wired only when the session store can actually
+    // delete (a DB backend).
+    //
+    // 🔴 ORDERING (adversarial-review HIGH — privacy/right-to-delete + silent-success): the session HISTORY delete
+    // (session_meta) is the `ownerOf` gate the DELETE route consults to decide idempotency. It MUST be the LAST
+    // committed leg. If a privacy-relevant child leg (runs/checkpoint/tool-result) is deleted AFTER the meta row is
+    // gone and then FAILS, the idempotent retry sees `ownerOf===undefined` (history already gone) → the route
+    // short-circuits to 200 {deleted:false} and NEVER re-purges → those child rows are stranded while the API
+    // reports success. So we purge the child legs FIRST and PROPAGATE any error (do NOT swallow): on a child
+    // failure the history delete is SKIPPED, `session_meta` survives, the DELETE returns 500, and the idempotent
+    // retry's `ownerOf` still resolves → it re-runs the FULL purge to convergence. `deleted` is computed from the
+    // FINAL committed result (history-deleted || runsRemoved>0 — the privacy-relevant data that actually existed).
+    // [1196] session-watch registry(SSE 订阅共享探针面)。谓词与 /head 探针同门(getLeafId+ownerOf);
+    // env 旋钮经 posIntEnv 有界校验;getLeafId 箭头包一层=天然绑定宿主(SESSION_CACHE_TTL_SEC=0 裸类实例)。
     const sessionWatchRegistry = ownerAware.getHead && ownerAware.ownerOf
         ? new SessionWatchRegistry(async (sid) => (await ownerAware.getHead(sid)) ?? { owner: undefined, leafId: null }, {
             hotMs: posIntEnv(process.env.SESSION_EVENTS_HOT_MS, 200),
@@ -1738,29 +3036,73 @@ async function main() {
             maxWatchedSessions: posIntEnv(process.env.SESSION_EVENTS_MAX_PROBES, 512, 100_000),
         })
         : undefined;
+    // S2 fast path([1208]③ 兑现):同副本 append 落点(tidb/pg persist post-commit)经 leaf-bus 直推
+    // notifyLocal——单副本部署零延迟;owner 不随 bus 传(写点无廉价 owner 读),探针围栏仍是租户权威
+    // (session-leaf-bus 契约注)。local lane 无写钩,探针道照旧。
     setLeafAdvanceListener(sessionWatchRegistry ? (sid, leaf, owner, seq) => sessionWatchRegistry.notifyLocal(sid, leaf, owner, seq) : undefined);
     const purgeSession = ownerAware.deleteSession
         ? async (sessionId, owner) => {
+            // Runs-ledger FIRST: it transactionally re-asserts the no-active-run invariant (FOR UPDATE on task_active,
+            // serializing against a concurrent createRun). If a run claimed the session in the route's check→purge
+            // window it returns `{ active }` and deletes nothing → we bubble it up so the route 409s, BEFORE touching
+            // any other table (no partial purge of a live session). Each leg propagates its error so a child failure
+            // aborts the purge BEFORE the history-delete gate is removed (keeping the idempotent retry convergent).
             const runs = runStore ? await runStore.deleteBySession(sessionId, owner) : { removed: 0 };
             if ("active" in runs)
                 return { active: runs.active };
+            // checkpoint rows carry no owner column → owner-guarded via a session_meta.owner sub-select, so they MUST
+            // run while session_meta still exists (before the history delete below); tool_result is keyed only by
+            // `ref` so it stays route-guarded (see its deleteBySession doc).
             if (checkpointStore)
                 await checkpointStore.deleteBySession(sessionId, owner);
             if (toolResultStore)
-                await toolResultStore.deleteBySession?.(sessionId);
+                await toolResultStore.deleteBySession?.(sessionId); // optional extra: SQL twins only (local file store has no per-session purge index; E21 purge is a durable-backend contract)
+            // E18 resume-at anchors are per-session privacy-relevant metadata → purge ALL of them with the session, scoped
+            // by session_id ALONE (the route already proved session ownership at the DELETE gate). A per-ROW owner guard
+            // here would LEAK: an anchor's owner is the per-run submitting principal, which diverges from the canonical
+            // session owner when an anonymous session is later attached by a principal (REQUIRE_PRINCIPAL=false) — those
+            // mixed-owner rows would survive the delete (a right-to-delete violation reported as success).
             if (resumeAnchorStore)
                 await resumeAnchorStore.deleteBySession(sessionId);
+            // Approval exemptions are per-session operator decisions → purge with the session (same
+            // session_id-alone scoping rationale as the anchors above).
             if (approvalExemptionStore)
                 await approvalExemptionStore.deleteBySession(sessionId);
+            // E6 session-policy rows are per-session operator rules → purge them too, scoped by session_id (the route
+            // owner-gated the session). Since core 1.423 the seam is on the INTERFACE (optional) and core's File/InMemory
+            // stores carry it too — so this fires on EVERY backend now. (The old note here claimed local rules were
+            // "process-ephemeral anyway" — false for the file-backed local store, whose policy rows survive restarts;
+            // that right-to-delete hole is what [1796]§三 → core 1.423 closed.)
             if (sessionPolicyStore?.deleteBySession)
                 await sessionPolicyStore.deleteBySession(sessionId);
+            // D-1 附件随会话删(E21 级联;session_id 单键 scoping,与 anchors 同理由——路由已证会话所有权)。
             if (taskAttachmentStore)
                 await taskAttachmentStore.deleteBySession(sessionId);
+            // E19 rewind-files snapshots are per-session working-tree state → purge them too (scoped by sessionId; the
+            // durable twins carry deleteBySession, local InMemory omits it → optional no-op on local).
             if (fileSnapshotStore?.deleteBySession)
                 await fileSnapshotStore.deleteBySession(sessionId);
+            // P1 ①②: drop any pending async-workflow completions for this session (else they orphan when a later
+            // tenant reclaims the sessionId). Best-effort + non-fatal — a leftover entry is ALSO gated by the
+            // drain-time owner check, so a purge failure never leaks; it must not abort the session delete.
+            // `owner` scopes the purge fence (1.80): only the DELETED session's own late completions are fenced —
+            // a new tenant legitimately re-claiming this sessionId within the window keeps its push (review MED).
             if (workflowCompletionInbox)
                 await workflowCompletionInbox.purge(sessionId, owner ?? null).catch((err) => logger.warn("workflow_completion_inbox_purge_failed", { sessionId, err: String(err) }));
+            // 修8(三路复审 absorb-2,接线 (a)):the session's scratchpad dir ([820]③, ensureScratchpadDir) rides
+            // the session lifecycle — purge it with the session. purgeScratchpadDir SELF-SWALLOWS (env-facts.ts
+            // contract: cleanup never faults the delete path; the periodic sweep below is the convergence backstop),
+            // so it cannot strand the E21 ordering invariant. Same root the ensure used (config.localDataRoot ?? localRoot).
             await purgeScratchpadDir(config.localDataRoot ?? localRoot, sessionId);
+            // design/129 (core 1.239): reap this session's SESSION-scoped background children — they
+            // deliberately outlive turns (backgroundScope:"session"), so the session's DELETE is their lifecycle
+            // end (core's parent-teardown reap skips them by design; without this they run to their forced timeout).
+            // Sync + replica-local (the registry is in-process); best-effort — a reap of 0 on the wrong replica is
+            // covered by core's forced child-timeout cap.
+            // [1892]{core} 跨仓待办:scope 轴必传——core canAccess 对缺省 scope fail-closed(拒绝非通配,
+            // 1.441 复审①正过极性),不传 = 四类后台任务在会话删除时恒 0 回收(潜伏至今,core 复审顺手
+            // 核出)。铸值同源 runs.ts:25 契约:core 按 `spec.principal ?? "default"` 注册 ⇒ 此处
+            // owner(会话主)?? "default" 对齐;错 scope 不越租户由 canAccess 保证(session-reap-scope 钉)。
             try {
                 const reaped = defaultTaskRegistry.reapSessionBackground(sessionId, owner ?? "default");
                 if (reaped > 0)
@@ -1769,13 +3111,26 @@ async function main() {
             catch (err) {
                 logger.warn("session_background_reap_failed", { sessionId, err: String(err) });
             }
+            // History/meta LAST: once committed, the `ownerOf` gate is gone and the delete is durably complete. The
+            // owner is threaded into the SQL guard (session_meta.owner) for data-layer defense-in-depth.
             const historyDeleted = await ownerAware.deleteSession(sessionId, owner);
+            // [1196] 三轮复审(租户轮转围栏,同副本半场):session 删除即终结其 SSE 订阅者+watch 条目——
+            // 旧 owner 的活流不得跨越 delete/reclaim 边界收新租户的 head;跨副本半场=路由心跳期 owner 复核。
             sessionWatchRegistry?.dropSession(sessionId);
             return { deleted: historyDeleted || runs.removed > 0 };
         }
         : undefined;
+    // Degenerate-output a/b instrument: needs the durable session log to inspect turn history (design/39
+    // ② gating data). Only on the TiDB backend (mysql2 pool); env-only / PG deploys get no-op.
     const instrumentDegenerate = mysqlPool ? makeDegenerateInstrument(mysqlPool, metrics, logger) : undefined;
+    // Plan-cache recurrence probe (core design/42, INSTRUMENT-FIRST): pure in-memory, no backend needed —
+    // counts per-scope task-objective recurrence so core can decide whether to build plan caching.
     const planCacheProbe = new PlanCacheProbe(metrics, logger);
+    // v2 leader endpoint (design/50 + design/68): wire when LEADER_ENABLED + an isolated remote-exec backend
+    // (E2B or k8s/Kata — SSH/ADB are single-worker real-system backends, not fan-out targets). Default off →
+    // zero prod impact. 🔴 a real run also needs `git` on the host PATH + a durable remote with write creds.
+    // F2(a) factory mode (preferred) = the service's executionEnvFactory + MinIO self-upload diff-out; the k8s
+    // lane REQUIRES it (no static k8s mode). E2B without MinIO falls back to the static compat mode.
     const leaderMinio = process.env.MINIO_ENDPOINT && process.env.MINIO_ACCESS_KEY && process.env.MINIO_SECRET_KEY
         ? {
             s3: {
@@ -1788,6 +3143,9 @@ async function main() {
         }
         : {};
     const leaderProvider = config.remoteExec?.provider;
+    // DUAL-MODE §5: orchestration is an ENGINE capability, not fleet-only — the TOC `host` lane runs leader fan-out
+    // bounded by ONE box (isolation=none, NON-durable: no snapshot, so the durable sub-worker suspend block below is
+    // skipped — host workers run to completion in-process-adjacent). e2b/k8s keep their isolated/suspendable posture.
     const leaderEndpoint = config.leaderEnabled &&
         (leaderProvider === "e2b" ||
             (leaderProvider === "k8s" && "s3" in leaderMinio && executionEnvFactory) ||
@@ -1795,21 +3153,37 @@ async function main() {
         ? createLeaderEndpoint(createLeaderRunner({
             brain, models: config.models, roles: config.roles, pricing, logger,
             fanoutEnabled: config.leaderFanoutEnabled,
+            // Route the single-vs-fanout classification on the cheap model (deepseek-v4-flash): the heavy
+            // reasoning worker model returns empty ~2/3 of the time on the route prompt → silent collapse to
+            // single (observed 2026-06-14). MODEL_ROUTER_ID overrides; else the cheap model; else default.
             ...((process.env.MODEL_ROUTER_ID || process.env.MODEL_CHEAP_ID)
                 ? { routerModel: (process.env.MODEL_ROUTER_ID || process.env.MODEL_CHEAP_ID) }
                 : {}),
             ...(leaderProvider === "e2b" ? { e2bApiKey: config.remoteExec.apiKey } : {}),
             ...(executionEnvFactory ? { envFactory: executionEnvFactory } : {}),
             ...leaderMinio,
+            // Durable offload store for sub-worker tool results — without it core REFUSES the durable
+            // suspend (InMemory offload would not survive a cross-replica resume) and the gated call is
+            // denied via the unwired onAsk fallback → the worker fails instead of suspending (drill c3).
             ...(toolResultStore ? { toolResultStore } : {}),
+            // k8s lane: align the wire's workspace with the adapter's durable-snapshot root (/workspace) —
+            // the E2B default (/home/user) is OUTSIDE the k8s suspend tar, so a suspended sub-worker's repo
+            // would silently vanish on resume (drill c3: 105-byte empty snapshots).
             ...(leaderProvider === "k8s" ? { workspace: "/workspace" } : {}),
+            // Same store as the main runner: a suspended sub-worker's session must be readable on /decide
+            // resume (sub-runner-local in-memory sessions die with "Entry <leafId> not found" on resume).
             sessionStore,
+            // design/68 C4: sub-workers can durably suspend when the service runs durable approvals.
             ...(checkpointStore && config.approvalRequire.length > 0
                 ? {
                     durable: {
                         checkpointStore,
                         requireApproval: config.approvalRequire,
                         deny: config.approvalDeny,
+                        // design/80: the leader's orchestrated sub-agents adopt the SAME supervisor loop as the
+                        // top-level agent — the D-E auto-budget (auto-approve NORMAL asks up to the budget, then
+                        // escalate) + the never-auto safety set. Without these a sub-agent's gated ask always
+                        // suspends-to-human, defeating the budget circuit-breaker for the supervised team.
                         autoBudget: config.approvalAutoBudget,
                         neverAuto: config.approvalNeverAuto,
                         ...(config.approvalTimeoutSec > 0 ? { ttlMs: config.approvalTimeoutSec * 1000 } : {}),
@@ -1818,12 +3192,20 @@ async function main() {
                 : {}),
         }), {
             logger,
+            // SDK 全量核查(2026-07-24,黑板 GD 组)撞获:wire.ts:368 的 runLeader 实际要求这五个字段全部
+            // 非空,此前同步门只查 objective,不完整请求会先拿到 202 再在后台必然失败——同步前移,让错误
+            // 尽早暴露而不是靠后续 GET 才发现。
             requiredFields: ["objective", "durableRemote", "testCmd", "seedCmd", "baseSha"],
         })
         : undefined;
     if (leaderEndpoint)
         logger.info("leader_endpoint_enabled", { provider: leaderProvider, mode: "s3" in leaderMinio ? "factory" : "static" });
+    // Graceful drain: shared mutable state — SIGTERM flips `draining` (shutdown below), createHttpServer
+    // assigns `inflight` (live leg count on this instance), /health + the submit 503 gate read it.
     const drainState = { draining: false };
+    // 鉴权桥(registry-core api/auth-bridge):SEMA_REGISTRY_URL 在位即点亮(零新配置——worker 已信
+    // registry 的 effective config,同一信任根延伸到其 JWKS);split 部署用 AUTH_BRIDGE_ISSUER/JWKS_URL/AUDIENCE
+    // 显式覆盖。缺 registry(纯 env 部署)=分支不存在,bearer 行为与今天字节一致。
     const authBridgeIssuer = process.env.AUTH_BRIDGE_ISSUER || config.configCenter?.baseUrl;
     const registryJwtVerifier = authBridgeIssuer
         ? createRegistryJwtVerifier({
@@ -1836,108 +3218,212 @@ async function main() {
         : undefined;
     if (registryJwtVerifier)
         logger.info("auth_bridge_enabled", { issuer: authBridgeIssuer });
+    // asyncRewake wake 管道 holder:server 启动时装 deliver(session→本副本活流 steer);createTaskHooks 的
+    // ctx.wake 闭包经它投递(main 建壳/server 填实,双向不循环依赖)。
     const hookWakeBus = {};
+    // ═══════════ design/158 A8:ServiceDeps 分组装配(七组窄接口)═══════════
+    // 每组一个**带类型标注**的中间 const —— 标注位触发 TS 多余属性检查,键放错组当场编译红。
+    // (平铺形做不到:69 键的全可选面里任何键名都「属于」它,于是键落错家/从未接线只能靠源码钉
+    // 逐个盯 —— 1.300/1.301/1.304/1.307/1.310 五起真缺陷都是这个病族。)组形状门见
+    // test/deps-literal-shape-gate.test.ts;消费点仍读平铺 `deps.x`(createHttpServer 入口摊平)。
+    /** durable 持久面(键 present ⇔ 路由/能力位在场;absent ⇒ 501 诚实缺席) */
     const stores = {
         runStore,
-        resumeAnchorStore: resumeAnchorStore ? resumeAnchorStore : undefined,
+        resumeAnchorStore: resumeAnchorStore ? resumeAnchorStore : undefined, // E18 resume-at eventId→entryId map (tidb/pg/local)
         approvalStore,
-        approvalExemptionStore: approvalExemptionStore ? approvalExemptionStore : undefined,
+        approvalExemptionStore: approvalExemptionStore ? approvalExemptionStore : undefined, // decide remember="session" + list/revoke
         checkpointStore,
-        sessionPolicyStore: sessionPolicyStore ? sessionPolicyStore : undefined,
+        sessionPolicyStore: sessionPolicyStore ? sessionPolicyStore : undefined, // E6 operator session-rule store (PUT/GET /v1/sessions/:id/policy)
+        // E19 cap: core's gate-split (1.134.0) REMOVED the isRemoteExecutionEnv skip — core now snapshots each
+        // completed turn + restores on resumeAt for ANY ExecutionEnv when fileSnapshotStore is wired (captureManifest/
+        // applyManifest run over any env's FileSystem ops; a 30s timeout bounds a slow remote walk). So rewind works for
+        // host/e2b/k8s/ssh/adb/local-docker AND the in-process worker → advertise `rewindFiles` whenever the store is wired.
         fileSnapshotStore: fileSnapshotStore ? fileSnapshotStore : undefined,
-        taskAttachmentStore: taskAttachmentStore ? taskAttachmentStore : undefined,
+        taskAttachmentStore: taskAttachmentStore ? taskAttachmentStore : undefined, // D-1 上传/取回/删除三动词面
+        // design/153 件3d(/decide parked 赎回腿):durable bg 行店 + boot 裸 Agent 工具,与 RunnerDeps/
+        // scenarioDeps 同实例(claim/expire/consumeParkedFlip 作用于同一行)。任一缺席=分支不存在。
         backgroundAgentStore: backgroundAgentStore ? backgroundAgentStore : undefined,
+        // §0.5 session-ownership: the durable session abstraction (SessionRepo-style list/fork/delete) + the delete
+        // coordinator. `ownerAware` is the (possibly cache-wrapped) session store; both delegate to the DB-backed
+        // TiDB/PG store. Undefined-safe: on an in-memory dev store these carry no SessionRepo ops → the routes 501.
         sessionStorage: ownerAware,
         workflowRunStore: workflowRunStore ? workflowRunStore : undefined,
-        workflowJournalStore: workflowJournalStore ? workflowJournalStore : undefined,
+        workflowJournalStore: workflowJournalStore ? workflowJournalStore : undefined, // [1402] journal 读面(GET /v1/workflows/:id/journal 数据源,与 runner 同实例)
         imageIndex,
         imageBakes,
-        outcomeSink: outcomeSink ? outcomeSink : undefined,
-        sendFileLedger: sendFileLedger ? sendFileLedger : undefined,
+        outcomeSink: outcomeSink ? outcomeSink : undefined, // P2: GET /v1/outcomes 读面(design/73 §7.2 仪表盘底料)
+        sendFileLedger: sendFileLedger ? sendFileLedger : undefined, // SendUserFile 账本读面:GET /v1/sendfile-links(owner-scope 镜像 sessions list)
+        // 2c session-sync (P1d): the WHOLE backend so the /v1/sessions/:id/sync/* routes can call exportSession/
+        // importSession (they fan out across session entries + fileSnapshot + sessionPolicy + resumeAnchor, which must
+        // come from ONE backend in the §8 atomic order). Undefined-safe: the env-only/no-backend worker 501s the routes.
         backend: backend ? backend : undefined,
     };
+    /** 进程内活体协调面(本副本 only,重启即空:HITL 协调器/可 steer 句柄注册表/总线/收件箱) */
     const coordinators = {
-        elicitation: elicitation ? elicitation : undefined,
-        question: question ? question : undefined,
-        toolApproval: toolApproval ? toolApproval : undefined,
-        workflowAgentRegistry: workflowAgentRegistry ? workflowAgentRegistry : undefined,
-        subagentSteerRegistry,
-        workflowCompletionInbox: workflowCompletionInbox ? workflowCompletionInbox : undefined,
+        elicitation: elicitation ? elicitation : undefined, // E23: live-only inbound-elicitation coordinator (respond route + ALS wraps)
+        question: question ? question : undefined, // §4④: AskUserQuestion live coordinator (respond route + ALS wraps on streaming legs)
+        toolApproval: toolApproval ? toolApproval : undefined, // [816]/[820]②: live tool-approval coordinator (respond route + ALS wrap on the sync streaming leg)
+        workflowAgentRegistry: workflowAgentRegistry ? workflowAgentRegistry : undefined, // SVC-5: steerable workflow-agent handle registry
+        subagentSteerRegistry, // C2 (core 1.219): steerable Task-subagent handle registry (POST /v1/runs/:id/subagents/:target/steer)
+        workflowCompletionInbox: workflowCompletionInbox ? workflowCompletionInbox : undefined, // P1 ①②: drain → workflow_complete frame on stream-open
         fleetBus,
-        sessionWatch: sessionWatchRegistry ? sessionWatchRegistry : undefined,
+        // [1196] session 级 SSE 订阅:watch registry(N 订阅共享一条探针,自适应拍距,无订阅即停)。谓词与
+        // /head 探针同门(getLeafId+ownerOf);缺 store 面不建=路由 501+capabilities.sessionEvents=false。
+        sessionWatch: sessionWatchRegistry ? sessionWatchRegistry : undefined, // [1196] 建于 purgeSession 之前(delete 即 dropSession 的同副本围栏)
         hookWakeBus,
-        sendUserFile: sendUserFileEmitter ? sendUserFileEmitter : undefined,
+        sendUserFile: sendUserFileEmitter ? sendUserFileEmitter : undefined, // SendUserFile 切片2:file_link 帧 ALS(bg/sync 腿 wrap)
         leaderEndpoint,
-        sessionTitler: sessionTitler ? sessionTitler : undefined,
+        sessionTitler: sessionTitler ? sessionTitler : undefined, // fire-and-forget auto-title at first submit
     };
+    /** 函数/构件缝(main 把跨子系统的动作编译成一个可调用面交给路由) */
     const seams = {
         sessionAudit,
         purgeSession: purgeSession ? purgeSession : undefined,
+        // [1488]③(b): bg agent-handle read face — GET /v1/runs/:id/subagents/:handle/output → the same registry
+        // face the TaskOutput tool reads (defaultTaskRegistry is the process singleton every run leg registers
+        // its background children into). Access tuple is derived from the run row in server.ts, never the caller.
+        // codex R2: kind-gated BEFORE the poll (backgroundAgentOutput) — generic pollTask has side effects on
+        // other kinds (workflow onServedTerminal ack, bash output-cursor advance).
         subagentTaskOutput: (handle, access) => backgroundAgentOutput(defaultTaskRegistry, handle, access, backgroundAgentStore),
+        // [1499] CC TaskOutput/TaskStop 人侧对位 — the GENERIC task-handle verbs over the same registry singleton
+        // (kind gate at the seam: bash/monitor/agent pass, workflow refused — journal face owns it).
         taskHandleOutput: (handle, access) => taskHandleOutput(defaultTaskRegistry, handle, access, backgroundAgentStore),
         taskHandleStop: (handle, access) => taskHandleStop(defaultTaskRegistry, handle, access, backgroundAgentStore),
+        // 142-S5 §1.4: GET /v1/memory/export 数据源(DB memory plane only;file 形态 route 501)。
         memoryExport: memoryExportBackend ? (scope) => exportMemoryScope(memoryExportBackend, scope) : undefined,
+        // 142-S2.5: POST /v1/memory/sync/:scope 执行位(同一 DB entry plane + sync_cursors 游标面;
+        // plan 随数据走——core 纯函数在 performMemorySync 内直调,file 形态 route 501)。
         memorySync: memoryExportBackend && memorySyncCursors
             ? (scope, syncReq) => performMemorySync(memoryExportBackend, memorySyncCursors, scope, syncReq)
             : undefined,
+        // sessionMirror 观测面(server 非执法端,论证在 ServiceDeps.sessionMirrorRuling):
+        // 与 executionRuling 同车同缓存(零额外 center RTT);无 center/dry-run ⇒ 不接线,观测面暗、零行为差。
         sessionMirrorRuling: principalCaps
             ? async (p) => (await principalCaps.executionRuling(p))?.sessionMirror
             : undefined,
         instrumentDegenerate,
-        sideQueryAccounting,
+        sideQueryAccounting, // [1469] side-query 四路 sink 记账(与 tracer 同源装配)
         parkedReviveTool: parkedReviveTool ? parkedReviveTool : undefined,
+        // design/158 S2(F-1)修:工厂在 :2308 造好、server.ts 消费分支在等,但从未进本实参段——HIGH-1
+        // 同族第二例(条件 spread 的键从不接线,编译期无声)。缺席后果=带 requiresParentConstraint 的
+        // parked checkpoint 重启后恒被 core pre-CAS 门拒,**不可赎回**。接线钉:test/parked-revive-gate-wiring.test.ts。
         parkedReviveInheritedGate: parkedReviveInheritedGate ? parkedReviveInheritedGate : undefined,
     };
+    /** 可观测面(全体 fail-open,观测失败绝不改业务面行为) */
     const observability = {
         logger,
         metrics,
-        modelUsage: modelUsageTracker,
-        promptManifests: promptManifestTracker,
+        modelUsage: modelUsageTracker, // E8: shared with createTracer above → runs drain it into the modelUsage echo
+        promptManifests: promptManifestTracker, // [998]②: shared with createTracer → the durable legs drain prompt_assembled events
         planCacheProbe,
     };
+    /** 准入/治理面(每件都是拒绝的权力;缺席 = 该道门不存在,不是「默认放行的门」) */
     const governance = {
         authorize,
         registryJwtVerifier: registryJwtVerifier ? registryJwtVerifier : undefined,
         rateLimiter,
         costQuota,
-        fleetLease: fleetLease ? fleetLease : undefined,
+        fleetLease: fleetLease ? fleetLease : undefined, // lease admission 门(提交面,镜像 quotaExceeded)
     };
+    /** 部署自述面(/health + /v1/capabilities + 提交前置门读的部署事实;多为 live getter) */
     const deployment = {
+        // 海外 pilot 实机发现:/health 曾 verbatim 回显 sessionBackend 枚举——auto/DB_BACKEND 收编把它
+        // coerce 成 LABEL "tidb"(泛指 durable),pg 部署上误读成 SQL-TiDB 带偏排障。回显有效 store(与 listening
+        // 日志 session 标签同款诚实修)。
         sessionStoreLabel: config.sessionBackend === "tidb" && backend ? `durable(${backend.kind})` : config.sessionBackend,
-        modelReady: () => modelReadyState.ready,
-        scenarioDetails,
-        workflowsCapable,
+        modelReady: () => modelReadyState.ready, // boot ready 门:roster 未落地=计费提交 503+health ready:false
+        scenarioDetails, // 场景详情只读面(内建+center 同判定源)
+        workflowsCapable, // ① core split: capabilities.workflows = engine-can (workflowsCapability); workflowsList = store (below)
         instanceId,
+        // Capability discovery: the deployment facts only main knows. Store-derived booleans
+        // (asyncRuns/artifacts/approvals/leader) are computed inside the server from the deps themselves.
+        // pricingConfigured disambiguates costMicroUsd=0 ("free run" vs "MODEL_COST_* not configured") —
+        // it is worker-level config, so one flag here beats decorating every result's stats.
         capabilities: {
             version: serviceVersion(),
             scenarios: Object.keys(scenarios),
             pricingConfigured: Object.values(pricing).some((p) => Object.values(p).some((v) => typeof v === "number" && v > 0)),
         },
+        // center: orchestrator polls GET /health for this — set by the sema-registry refresh loop when a
+        // pull's restart-to-apply slices differ from boot. A live getter (not a snapshot) so /health always reads current.
         restartState: () => pendingRestart,
-        planeDeferredState: () => planeDeferredNoHandoff,
+        planeDeferredState: () => planeDeferredNoHandoff, // codex R18: /health.modelPlaneDeferred (stuck-deferred plane, no handoff)
+        // shared drain state — SIGTERM flips `draining`, createServer assigns `inflight`, /health mirrors it.
         drainState,
-        storeDegraded: storeBackendDegraded,
+        storeDegraded: storeBackendDegraded, // S5: /health twin of the store_backend_degraded gauge
     };
+    /** 数值旋钮(缺省写在消费点,此处只承载覆写) */
     const knobs = {
+        // (a) SQL 默认店的 per-blob 帽 → PUT /sync/blobs 前置 413(与 SqlBlobBackend 方言默认同源:
+        // 显式 env > tidb 的 6MiB entry-限默认;pg 默认无帽=不前置)。
+        // 🔴 复审 2026-07-28(E-HIGH-1)修:此键是 **ServiceDeps** 字段,原先被 spread 进 `runnerDeps`
+        // (core 的 RunnerDeps 无此字段,条件 spread 绕过 TS 多余属性检查 ⇒ 编译期无声)⇒ HTTP 面恒
+        // undefined、413 前置是死枝、超帽仍走 502。落错家的死键病族(verify-cost 先例)——接线钉见
+        // test/review-2026-07-28-batch1.test.ts。
         snapshotBlobSqlCapBytes: backend && backend.kind !== "local" && !config.snapshotBlobStore
             ? (config.snapshotBlobSqlMaxBytes ?? (backend.kind === "mysql" ? SQL_BLOB_DEFAULT_MAX_BYTES : undefined))
             : undefined,
+        // 帽只在 watch 面在场时才有意义(缺席时路由 501,读不到它)——保持与原条件段同门,不单独接线。
         sessionEventsMaxConnections: sessionWatchRegistry ? posIntEnv(process.env.SESSION_EVENTS_MAX_CONNS, 256, 100_000) : undefined,
     };
+    // Deployment-owned mapping. Tools/prompt/skills come from the selected scenario (assembled once,
+    // bound per request); identity/session/policy stay server-side. Never taken from the request body.
+    // design/158 A8:从 createHttpServer 实参里提出来(原地占该字面量 1,093 行中的 967 行)——
+    // 类型标注 `ServiceDeps["resolveSpec"]` 顶替了原来的上下文推导,签名不变。
     const resolveSpec = async (body, _req, auth, opts) => {
+        // per-principal scenario governance (assignment-as-default; an explicit
+        // body.scenario is bounded to the allowlist — outside ⇒ typed 400 `scenario_not_allowed`). The ruling
+        // {scenario, allowlist} is center-RESOLVED and rides the caps view (TTL-cached, same fetch as runtimeCaps);
+        // no center / dry-run / anonymous / older center / caps blip ⇒ undefined ⇒ legacy body-or-default chain.
         const requested = gateScenarioRequest(await principalCaps?.scenarioRuling(auth?.principal), body.scenario, config.defaultScenario);
+        // per-principal execution-lane policy — this worker's lane is a
+        // PROCESS identity (REMOTE_EXEC boot wiring, no per-task switch), so admission is the gate: lane ∉
+        // allowedLanes ⇒ typed 403 `execution_lane_not_allowed`. Same caps car as the scenario ruling (zero extra
+        // RTT); fail-open + audit on blip. "in-process" = fleet's REMOTE_EXEC-unset core stub lane
+        // (named distinctly from the explicit `host` lane — same machine, different posture).
         gateExecutionLane(await principalCaps?.executionRuling(auth?.principal), config.remoteExec?.provider ?? "in-process");
+        // Resolve an unknown name to "default" so the WHOLE bundle stays coherent — tools/prompt AND
+        // skills/mcp fall back together. (selectScenario already falls back for tools/prompt; without
+        // resolving here, skills/mcp would still be filtered by the raw unknown name → any skill/MCP tagged
+        // ["default"] silently drops. council finding.)
         const scenarioName = scenarios[requested] ? requested : "default";
+        // [891] deprecation(一版过渡窗):"autonomous" 已改名 "code"(persona 同一,唯一差别=alias 仍
+        // 定死 finalVerification:true 保存量行为)。warn 不 400——TB harness/存量部署平滑迁移。
         if (scenarioName === "autonomous")
             logger.warn("scenario_autonomous_deprecated", { alias: "code", note: "renamed by [891]; alias keeps finalVerification pinned — pass scenario:'code' (+ explicit finalVerification if wanted)" });
         const cap = selectScenario(scenarios, scenarioName)(body, auth?.principal);
+        // codex R3/R4 (appendSystemPrompt 案): ONE center-pack snapshot per request — the append-less gate below
+        // AND the provider pick (promptProvider field) both read THIS capture, never the mutable centerPrompts ref
+        // again (R4 TOCTOU: a refresh between the two reads could make the final provider assembled while the gate
+        // judged safe, restoring the in-core silent drop).
         const centerDecls = centerPrompts?.declarations;
+        // TRUE when the EFFECTIVE assembly for this request takes core's pass-through arm (no core/role.append
+        // section ⇒ any append rider/outputStyle silently discarded in core). codex R9: PROVIDER-AWARE — mirrors
+        // core's actual triggers (stableBlocks identity decls / stableSystem OUTPUT carrying the anchors), because
+        // a raw body.systemPrompt anchor heuristic false-positives on default-provider scenarios (unbranded
+        // default / scan: no provider ⇒ core defaultPromptProvider retains role.append and the rider mounts even
+        // with an anchored systemPrompt). center-wins mirrors the provider pick below (same snapshot, same
+        // scenario derivation — principal ruling + defaultScenario already folded into scenarioName above).
         const appendLessPack = centerDecls
             ? centerIdentityAssembled(centerDecls, scenarioName, hasConstitutionAnchors)
             : providerDropsAppend(cap.promptProvider, typeof body.systemPrompt === "string" ? body.systemPrompt : undefined);
+        // Accepted rider (defensive resume mirror inside; fresh malformed/over-cap shapes already 400'd in
+        // prepareSpec). Hoisted to a const so the R14 combined-cap check below can see the accepted length.
         const acceptedAppend = acceptAppendSystemPrompt(body.appendSystemPrompt, (detail) => logger.warn("append_system_prompt_dropped", { detail, sessionId: auth?.sessionId ?? null }), appendLessPack);
+        // @-model (1.24) + explicit picker: an end user may pick a CONFIGURED model via the CLI
+        // `/model` picker / `run --model` flag (body.model) OR an inline `@name` in the objective. resolveTaskModel
+        // gates BOTH against the catalog allow-list (config.models keys) — pick WHICH model, never inject one — with
+        // body.model winning over @mention winning over `default`. Returns the objective with the @mention stripped.
         const objective = typeof body.objective === "string" ? body.objective : "";
+        // TaskRequest.settings (client per-request SemaSettings stamp). Parsed DEFENSIVELY off the untrusted body
+        // (every field shape-checked; `bypassPermissions`/unknown modes dropped). `env`/`hooks` are recorded as
+        // received-but-deferred (never silent-dropped). Folded into the spec TIGHTEN-ONLY after applyRuntimeGovernance.
         const parsedSettings = parseTaskSettings(body.settings);
+        // codex R4 (appendSystemPrompt 案) fresh-leg fail-loud: a NEW submit whose append payload (top-level rider
+        // or settings.outputStyle) meets an append-less pack 400s HERE — inside resolveSpec, where the effective
+        // scenario (principal ruling + defaultScenario) and the center-pack snapshot are the SAME ones the provider
+        // pick uses (an HTTP-side gate could disagree with the actual assembly). Resume legs (opts.leg absent)
+        // keep the drop+warn mirror below — a 4xx would brick a pre-1.243 stored task.
         if (opts?.leg === "fresh" && appendLessPack) {
             const riderPresent = typeof body.appendSystemPrompt === "string" && body.appendSystemPrompt.length > 0;
             if (riderPresent || parsedSettings.settings?.outputStyle) {
@@ -1945,8 +3431,26 @@ async function main() {
             }
         }
         if (parsedSettings.deferred.length > 0) {
+            // No-silent-drop: a caller SENT env/hooks but this version does not wire them on remote (need a core seam /
+            // a remote hook-runner — see task-settings.ts + capabilities). Log so the gap is visible, never silent.
             logger.warn("task_settings_deferred", { fields: parsedSettings.deferred, sessionId: auth?.sessionId ?? null });
         }
+        // [#40 / TOC cwd seam] register the caller's launch dir so the HOST factory runs the agent there (read by
+        // ctx.sessionId). 🔒 GATED: only the single-user host lane (cwdHonored) honors it; on any other lane / multi-tenant
+        // a sent cwd is IGNORED (logged once, never silently — the shell learns via capabilities.projectContext). isValidCwd
+        // re-checked here too (RESUME re-runs resolveSpec WITHOUT the prepareSpec 400 validation). Re-applies on resume.
+        // [851]P3a 信号真实化:cwdHonored 只认显式 REMOTE_EXEC=host;provider 未设的 in-process 单用户 lane 没有
+        // shell hands(core prepare-task:无 factory/executionEnv ⇒ StubExecutionEnv,亲读 dist 坐实),但进程级
+        // 消费者(hooks 命令、C4 projectContext 本地读取)仍看引擎自身的 cwd/env——壳把引擎 spawn 在用户目录/用户
+        // 环境时,请求的 override 往往「已被进程状态满足」,此前每任务打 "ignored" warn 与实际状态矛盾(飞轮双平台
+        // 观测)。改法:已满足 ⇒ debug;真失配 ⇒ 保留 warn 且带 lane 字段(值与 run_local_start exec 口径一致:
+        // provider ?? "in-process")。真 per-session honor 之路仍是 REMOTE_EXEC=host(host factory 消费
+        // perSessionCwd/perSessionShellEnv)。
+        // ── D-1 附件绑定半场(②):TaskRequest.attachments = 上传句柄数组 ──
+        // fresh 腿硬验证(未知/他人 id → 400 typed;超数 → 400)——「引用了不存在的附件」必须在提交时
+        // 拒,不能等 env 建立时才炸。resume 腿降级(acceptedAppend 同姿):缺行 warn+跳过,余下照常
+        // (4xx 会砖存量 task;记录不可变 ⇒ 在场行的 notice 字节恒稳)。绑定=把行钉到 auth.sessionId
+        // (authorizer 恒解析出一个;绑定幂等,重复提交/resume 重绑同值)。
         let attachmentNotice;
         {
             const reqAtt = body.attachmentIds;
@@ -1988,10 +3492,14 @@ async function main() {
             else
                 logger.warn("task_cwd_ignored", { honored: cwdHonored(config), lane: execLane, sessionId: auth.sessionId });
         }
+        // [R-survey / TOC shellEnv seam] register the caller's `settings.env` so the HOST factory injects it into the
+        // agent's shell env. 🔒 GATED identically to cwd (single-user host lane only — design/107 env=capability axis);
+        // on any cloud/multi-tenant lane a sent env is IGNORED (logged once, never silent). Re-applies on resume.
         if (parsedSettings.settings?.shellEnv && auth?.sessionId) {
             if (cwdHonored(config))
                 setSessionShellEnv(auth.sessionId, parsedSettings.settings.shellEnv);
             else if (inProcessSingleUserLane(config)) {
+                // 只记失配键「数量」,绝不记键值(秘密类)与键名(名字本身可带敏感语义)——shellEnvMismatchCount 文档同款红线。
                 const requested = parsedSettings.settings.shellEnv;
                 const mismatched = shellEnvMismatchCount(requested, process.env);
                 if (mismatched === 0)
@@ -2002,6 +3510,11 @@ async function main() {
             else
                 logger.warn("task_shell_env_ignored", { honored: false, lane: execLane, sessionId: auth.sessionId });
         }
+        // hooks hook-runner(阶段一):settings.hooks(契约校验过)→ core TaskSpec.hooks 进程内回调。
+        // 🔒 hook 命令跑在 WORKER HOST(CC 语义:hooks 跑在引擎所在机,哪怕工具在远端沙箱)= design/107 class ②
+        // 能力授予 → 单用户闸 `requirePrincipal !== true`,与 scheduler/backgroundShell/lspHost/MCP 注入同一姿势;
+        // 多租户 lane 收到只警告忽略(`task_hooks_ignored`,capabilities.taskSettings.hooks 同步 advertise),绝不执行。
+        // Re-applies on resume(从 stored body 重解析,幂等)。
         const taskHooks = (() => {
             const hc = parsedSettings.settings?.hooks;
             if (!hc)
@@ -2010,55 +3523,122 @@ async function main() {
                 logger.warn("task_hooks_ignored", { honored: false, sessionId: auth?.sessionId ?? null });
                 return undefined;
             }
+            // payload 的 permission_mode 用【生效】模式——body.permissionMode(显式请求)优先于
+            // settings.permissions.defaultMode(与 spec 的 withPermissionMode 同一优先序),否则钩子读到的模式与
+            // 实际裁决模式不一致(如 body=plan 时钩子仍看到 default)。
             const effMode = coercePermissionMode(body.permissionMode) ?? parsedSettings.settings?.permissions?.defaultMode;
             return createTaskHooks(hc, {
                 logger,
                 sessionId: auth?.sessionId ?? "",
                 cwd: (auth?.sessionId ? perSessionCwd.get(auth.sessionId) : undefined) ?? process.cwd(),
                 ...(effMode ? { permissionMode: effMode } : {}),
+                // 用户变量通道(hook 进程 env + http $NAME 插值源):同请求的 settings.env——hookEnv 绝不读
+                // 裸 process.env 的非 allowlist 键(服务密钥不可被 allowedEnvVars 点名)。
                 ...(parsedSettings.settings?.shellEnv ? { shellEnv: parsedSettings.settings.shellEnv } : {}),
+                // 阶段三b:prompt/agent 条目的模型载体(boot 组装,见 hookLlm/hookAgent 定义处的影响范围说明)。
                 hookLlm,
                 hookAgent,
+                // cli [1786] 点名的观测位:一次 hook 判定**未能完成**时,往常开的 fleet 流推一帧。
+                // ⚠️ **纯 observe**(不拦、不续跑、不注入)——`additionalContext` 那条通道会让这一轮不结束,
+                //    所以不能拿它当"提示一下"用(见 hook-runner 折叠处旁注)。
+                // ⚠️ 带 ownerScope/ownerSessionId 供流侧做 **fail-CLOSED** 过滤(与 bg_notification 同一姿势):
+                //    一条关于别人会话的通知落到这个壳上,会让用户以为是自己这轮出了问题。
                 onHookNotice: (n) => fleetBus.publishHookNotice({
                     ...n,
                     ...(auth?.principal ? { ownerScope: auth.principal } : {}),
                     ...(auth?.sessionId ? { ownerSessionId: auth.sessionId } : {}),
                 }),
+                // asyncRewake wake 管道(契约:exit 2 唤醒模型):session→本副本活流 steer(hookWakeBus,server
+                // 启动装 deliver)。stderr 过 redactSecrets 再注入(hook 进程可能回显 env 密钥;与 trace 出口同纪律)。
+                // 无 session(匿名一次性任务)不给 wake——没有可稳定寻址的流。
                 ...(auth?.sessionId
                     ? {
                         wake: async (text) => hookWakeBus.deliver
-                            ?
+                            ? // provenance 围栏:注入内容标明来源=asyncRewake hook 的运行时输出,
+                                // 模型按 hook 反馈对待而非操作者指令(trusted:false 在 server 侧同批落定)。
                                 hookWakeBus.deliver(auth.sessionId, `[hook asyncRewake] ${redactSecrets(text)}`)
                             : false,
                     }
                     : {}),
             });
         })();
+        // design/119 (CC --add-dir parity, core 1.215 `TaskSpec.additionalDirectories`): extra host dirs the FILE tools
+        // may access beyond the containment root. 🔒 GATED identically to cwd/shellEnv (single-user host lane only —
+        // these are the caller's own-machine paths; a cloud/multi-tenant lane must not let a caller widen the file-tool
+        // containment onto operator/other-tenant host paths). Unlike cwd/shellEnv (registered per-session for the host
+        // FACTORY to read at env construction), additionalDirectories is a plain TaskSpec field core reads directly, so
+        // it rides onto the spec below. Ignored (logged, never silent) off the host lane. Re-applies on resume (from body).
         const rawAddDirs = body.additionalDirectories;
         const additionalDirectories = cwdHonored(config) ? parseAdditionalDirectories(rawAddDirs) : undefined;
         if (rawAddDirs !== undefined && !cwdHonored(config)) {
             logger.warn("task_additional_directories_ignored", { honored: false, sessionId: auth?.sessionId ?? null });
         }
+        // body.model (explicit /model picker or run --model) WINS over settings.model (the config default); both gate
+        // against the catalog allow-list via resolveTaskModel (a settings.model not in the catalog is ignored, never injected).
+        // 🔴 TOB 档位联跑曾 FAIL(坐标级):the gate must see the TIER-EXPANDED catalog — expandTiers
+        // runs inside core's Runner on a PRIVATE deps copy (runtask.ts), so gating on bare config.models silently
+        // degraded every tier word (pro/flash/@mention/CC alias) to default BEFORE the Runner could resolve it.
+        // Expand per request (cheap: empty tiers returns the same reference; non-empty = one small spread) so the
+        // gate's key set is exactly what a freshly-constructed Runner resolves — tier words, degrade chains, CC
+        // aliases, catalog-SHADOW all from core's ONE implementation. Window note: tiers are restart-to-apply at
+        // the Runner; a refresh-time tier change makes this gate briefly AHEAD of the old Runner snapshot (a new
+        // tier word then fails loud in core instead of silently degrading — honest during the restart window).
         const wireCatalog = expandTiers(config.models, config.tiers) ?? config.models;
         const picked = resolveTaskModel(body.model ?? parsedSettings.settings?.model, objective, wireCatalog);
+        // [865]② 降级永远可见:fresh submit 的未知 body.model 已在 HTTP 门 400(不会到这);走到这的未知 ref
+        // 只剩 RESUME 重放(模型事后被移出目录)与 settings.model(lenient 文档面)——落 default 可跑,但必须
+        // 有声(session 中途换模型是最恶性的上下文污染路径,静默=病灶本体)。
         if (picked.unknownExplicit !== undefined) {
             metrics.inc("task_model_unknown_fallback_total");
             logger.warn("task_model_unknown_fallback", { requested: picked.unknownExplicit.slice(0, 120), fallback: picked.model, sessionId: auth?.sessionId ?? null });
         }
+        // no-vision images = PLACEHOLDER, not 422(会话可继续的 CC 心智). The old
+        // fail-loud 422 here BLOCKED core's own degradation: since core 1.233.1 a serving model whose `input`
+        // has no "image" gets image parts degraded to a bounded text placeholder ("[image omitted: …]"), per
+        // CURRENT model (degrade chains stay correct) and re-applied on every history replay — so a previously
+        // poisoned session self-heals. We pin ≥1.240.1, so pass the images through and let core do exactly that.
+        // The GET /v1/models vision flag stays advertised (the shell's composer-warning half). A model
+        // that never declared `input` keeps sending images verbatim (deliberate default — never wrongly strip
+        // for a vision-capable deployment that skipped the metadata; same posture).
+        // S6 (SILENT-FALLBACK P0-c): images headed for an EXPLICITLY text-only model — core (>=1.233.1) degrades
+        // them to bounded text placeholders per current model (the pass-through posture above). That modality drop
+        // was invisible fleet-side; count + warn at submit. modelSupportsImages is false-safe (undeclared input →
+        // true → no signal), matching core's "never wrongly strip" posture — no false positives for verbatim
+        // pass-through models. ⚠️ sema-registry lane caveat (review LOW-2): the roster maps `vision?: boolean` to
+        // an EXPLICIT input list (sema-registry.ts) — a vision-capable roster model that FORGOT the flag becomes
+        // declared text-only, so this signal fires AND core really does degrade its images (signal matches
+        // behavior; the fix for that footgun is the roster entry, not this counter). The per-run durable event rides core's vision.placeholder trace kind once we
+        // consume >=1.245 (the authoritative replacement-time signal), not this submit-time predictor.
         if (Array.isArray(body.images) && body.images.length > 0 && !modelSupportsImages(wireCatalog[picked.model])) {
             metrics.inc("images_omitted_total", { model: picked.model });
             logger.warn("images_omitted_no_vision_model", { model: picked.model, count: body.images.length });
         }
+        // E18 resume-at: the shell sends body.resumeAt as the E2 message eventId; core's TaskSpec.resumeAt takes the
+        // PERSISTED SessionTreeEntry.id, NOT the eventId ("a deployment that holds eventIds owns the eventId→entryId
+        // map" — core never persists eventIds). Resolve eventId→entryId via the anchor store HERE, 4xx-ing BEFORE the
+        // run on an UNKNOWN anchor (never hand core an unresolvable id). A KNOWN anchor whose entry was later compacted
+        // away surfaces as a failed run RESULT (resume_at.not_found) — 4xx on the sync path, the run result on async (the
+        // async contract is poll-the-result). RESUME re-runs resolveSpec from the stored body — the resume paths strip
+        // resumeAt before re-resolving (else core would reject resumeAt + a durable resume), so this branch only fires on
+        // a fresh submit. NEVER silent-drop (mirrors the body.model silent-drop bug class).
         let resumeAtEntryId;
         if (typeof body.resumeAt === "string" && body.resumeAt.length > 0) {
             if (!auth?.sessionId)
                 throw new HttpError(422, "resumeAt requires a session to branch (resume_at.no_session)");
+            // 501 gated on the SAME pair the `resumeAt` capability advertises (anchor store AND getLeafId) — capture is a
+            // no-op without getLeafId, so a getLeafId-less backend has a permanently-empty map; report "not available"
+            // (honest 501) rather than a misleading 404. Keeps "capability says yes ⟺ the route resolves" by construction.
             if (!resumeAnchorStore || !ownerAware.getLeafId)
                 throw new HttpError(501, "resume-at is not available on this worker (no session-store backend for the anchor map)");
             resumeAtEntryId = await resumeAnchorStore.resolve(auth.sessionId, body.resumeAt, auth.principal ?? null);
             if (resumeAtEntryId === undefined)
                 throw new HttpError(404, "resumeAt: no such message in this session (resume_at.unknown_event)");
         }
+        // R8 code-only rewind (CC "Restore code" mode, core 1.166 `rewindFilesTo`): restore the working tree to a prior
+        // USER message's snapshot WITHOUT forking the conversation. Resolve the SAME handle (the prompt's taskId) → entryId
+        // via the SAME anchor store. Honored ONLY when resumeAt is ABSENT (core's contract: the two are mutually exclusive —
+        // with resumeAt set, that branch's own rewindFiles governs); so we only resolve it on the code-only path. Same
+        // fail-loud discipline as resumeAt (501 no-store / 404 unknown anchor — never silent-drop).
         let rewindFilesToEntryId;
         if (resumeAtEntryId === undefined && typeof body.rewindFilesTo === "string" && body.rewindFilesTo.length > 0) {
             if (!auth?.sessionId)
@@ -2069,51 +3649,204 @@ async function main() {
             if (rewindFilesToEntryId === undefined)
                 throw new HttpError(404, "rewindFilesTo: no such message in this session (rewind_files_to.unknown_event)");
         }
+        // 142-S4 defaultScopes 种子:projectId → center 项目登记簿(config.projects,registry 喂)→ 该项目
+        // 声明的默认记忆 scope 词表(memory.scopes 额外 READ 层;写路由仍钉在派生 scope — memorySpecForRequest)。
+        // projectId 优先取 auth.resolvedProjectId(authorizer 的 PROJECT_ID_REGEX 422 门通过后回传);RESUME 腿
+        // 的 auth 从 checkpoint 重建、无此字段 → 回落持久化 body.projectId(原始提交已过形状门,与 memoryWrite
+        // 的 rides-the-persisted-body 姿势一致),让种子在 resume 腿等价重放。查表 miss(未登记/已下架)= 无种子,
+        // 不 fail(登记簿是加性配置面,不是准入门)。
         const s4ProjectId = auth?.resolvedProjectId ?? (typeof body.projectId === "string" && body.projectId ? body.projectId : undefined);
         const s4DefaultScopes = s4ProjectId ? config.projects[s4ProjectId]?.defaultScopes : undefined;
         const spec = {
+            // D-1:附件告知随 objective 进 durable 流(只有名字/mime/尺寸——**内容永不进流**,这正是
+            // 「拼进 objective 是伪方案」的账要划清的线;文件名已消毒为安全字符集,无注入面)。
             objective: attachmentNotice ? `${picked.cleanedObjective}\n\n${attachmentNotice}` : picked.cleanedObjective,
+            // Decoupling seam: a trusted client (token-holder) injects its OWN business/UX system prompt
+            // (persona, UI markers like ::ISSUE_FORM::, workflow rules). The service stays business-agnostic
+            // — integrators evolve their UX here, not by changing scenario prompts in this repo. core's
+            // stableSystem appends it after the scenario base, before <user_memory>.
             systemPrompt: typeof body.systemPrompt === "string" ? body.systemPrompt : undefined,
+            // [1476] R1 / [1478] R2: top-level append rider → core TaskSpec.appendSystemPrompt (stable block after the
+            // scenario base + systemPrompt, before the volatile tail). settings.outputStyle composes AFTER this via
+            // applyTaskSettings (`append\n\nstyle`) — byte-stable order: knowledge block always first, style always
+            // second (pinned by test; order flapping would shred the prefix cache). Resume re-enters here off the
+            // persisted body, so the rider re-applies on resumed legs like systemPrompt does — DEFENSIVELY (codex F2):
+            // the resume families skip prepareSpec's 400 gate and a pre-1.243 store kept unknown keys verbatim, so an
+            // over-cap legacy value is dropped+warned here instead of becoming active prompt content.
             appendSystemPrompt: acceptedAppend,
+            // sessionId comes from `auth` (ownership-checked / principal-derived), NEVER the body — the
+            // authorizer always resolves one. (No `?? body.sessionId` fallback: that would re-open the
+            // body-as-capability hole S6 closed if a deployment ran without an authorizer.)
             sessionId: auth?.sessionId,
+            // The authenticated end-user principal (design/62, core 1.78). Read-only on the TaskSpec — core injects
+            // it into a consumer MCP's `principalHeader` per-task so the MCP can enforce per-user RBAC (oa-mcp). It
+            // comes from the auth channel (never the body/model), so the model can't substitute another identity.
             principal: auth?.principal,
             images: body.images,
+            // design/112 C1: pass the client/gateway-supplied user context through to core (localizes the env block's date
+            // to the user's zone + surfaces who the agent acts for). HTTP-validated + capped at submit (prepareSpec); on a
+            // resume the body was already validated at its original submit. core re-validates timeZone (invalid → UTC) and
+            // SANITIZES userEmail (inlineUntrusted: folds newlines, neutralizes <system-reminder>, caps 160cp — no injection;
+            // double-review-confirmed). PICK only the two fields core reads — don't passthrough stray keys (a caller could
+            // otherwise bloat the persisted run body with an uncapped junk field; core ignores them but the body stays tight).
             ...(body.clientContext ? { clientContext: { timeZone: body.clientContext.timeZone, userEmail: body.clientContext.userEmail } } : {}),
+            // Structured output (CC --json-schema): a JSON Schema constraining the model's FINAL
+            // answer. core injects a built-in `submit_output` tool from it + surfaces the validated object as
+            // TaskResult.structuredOutput. HTTP layer shape+size-validated it (prepareSpec); core does deep validation.
+            // RESUME re-runs resolveSpec ⇒ the structured-output constraint re-applies on resumed legs too.
+            // 历史复审轴B #5(1.254):compactionModel 已接([1479]①)而 design/145 配套旋钮 clampTolerance
+            // 够不着=不对称。窄收单键(0..1 数值;其余 compaction 键仍是操作方轴,有意不开)。
             ...(() => {
                 const ct = body.compaction?.clampTolerance;
                 return typeof ct === "number" && Number.isFinite(ct) && ct >= 0 && ct <= 1 ? { compaction: { clampTolerance: ct } } : {};
             })(),
             outputSchema: body.outputSchema,
+            // 历史复审轴A #2(1.254):outputRetries 与 outputSchema 是成对的 caller 面旋钮(retry-on-invalid
+            // 轮数),此前只接了 schema 半边。窄校验:1..10 整数,schema 在场才有意义(core 无 schema 时忽略)。
             ...(typeof body.outputRetries === "number" && Number.isFinite(body.outputRetries) && body.outputRetries >= 1
                 ? { outputRetries: Math.min(10, Math.floor(body.outputRetries)) }
                 : {}),
+            // E18 resume-at: the resolved persistent SessionTreeEntry.id (from the eventId the shell sent). core branches
+            // the session at this prior entry before running the new objective ("rewind to this message, ask differently").
             resumeAt: resumeAtEntryId,
+            // [833] rewind exclusive mode (core 1.292): "before" branches at the target's PARENT (excludes the target —
+            // "remove this prompt and everything after it"); absent/"at" = core default, zero regression. Defensive
+            // normalize (RESUME re-enters resolveSpec without the HTTP 400 gate): only the two enum values ride, and only
+            // WITH a resolved resumeAt (core ignores the field otherwise; keep the persisted spec tight). core's "before"
+            // edge rejections (resume_at.before_target_not_user / resume_at.before_root_unsupported /
+            // rewind_snapshot.unresolvable) surface as failed-result errorCodes mapped to 4xx by resumeAtHttpStatus,
+            // errorCode passed through UNCHANGED for the shell to render.
             resumeAtMode: normalizeResumeAtMode(body.resumeAtMode, resumeAtEntryId !== undefined),
+            // design/114 Phase3 (reuse-path warm-resume): require the session to already exist — core's acquire fails loud
+            // (`resume.session_not_found`) on a genuinely-missing/purged session instead of silently starting a fresh one.
+            // The service authorizer ALSO stops pre-registering a missing id under this flag (security.ts), so the store's
+            // fail-loud actually fires (else the authorizer's claim-create would materialize the session first). Rides onto
+            // resume legs (resolveSpec re-runs); a resumed session exists, so it's satisfied there.
             requireExistingSession: body.requireExistingSession === true ? true : undefined,
+            // §4 (Fork): CC `/fork` — core 1.257 (design/136 BREAKING) retired the standalone Fork tool; a fork is now
+            // Agent(subagent_type:"fork") gated by `enableFork`. 🔴 core FLIPPED enableFork to opt-OUT (undefined = available),
+            // so enableForkFromBody now returns an EXPLICIT boolean (never undefined) — false where the service denies, else
+            // fail-OPEN. DEFAULT ON single-user turnkey (clay 2026-07-01); per-task opt-OUT via body.enableFork:false;
+            // multi-tenant honored ONLY with a per-principal entitlement resolver wired (core enforces `allowFork`), else
+            // explicit false (fail-closed). core still requires a fork-capable store (`hasSessionFork`; TOC file backend
+            // satisfies it via LocalSessionStore.fork), else inert.
+            // NB: `centerRuntimeCapsResolver`(非合成后的 runtimeCapsResolver)—— env observer 基线不是
+            // center 背书的 entitlement 源,多租户 fail-close 判别只认 center caps client。
             enableFork: enableForkFromBody(body, config, Boolean(centerRuntimeCapsResolver)),
+            // E12 (shell-host contract): opt-in post-completion prompt suggestions. core runs ONE extra fire-and-forget LLM pass
+            // after the task completes; the service surfaces the strings (redacted, UNTRUSTED UI-only) as a `suggestions`
+            // event. Defensive normalize (RESUME re-runs resolveSpec without the HTTP 400 validation). OFF ⇒ zero extra LLM.
             suggestNextPrompts: normalizeSuggestNextPrompts(body.suggestNextPrompts),
+            // E19 (shell-host contract): opt-in working-tree rewind. core snapshots each completed turn + restores the files on a
+            // resumeAt branch, for any env when fileSnapshotStore is wired (gate-split 1.134.0). OFF ⇒ no snapshot.
             rewindFiles: body.rewindFiles === true ? true : undefined,
+            // R8 code-only (core 1.166): the resolved target entry id for "Restore code" — core restores the working tree to
+            // its snapshot WITHOUT branching the session. Mutually exclusive with resumeAt (only set on the code-only path).
             rewindFilesTo: rewindFilesToEntryId,
+            // design/119 (CC --add-dir): extra host dirs the FILE tools may access (core canonicalizes each into the
+            // containment allowlist + lists them in the `# Environment` block). Single-user host lane only (gated above).
             additionalDirectories,
+            // EnterPlanMode (core 1.167): MODEL-DRIVEN plan — `enablePlanMode:true` alone (writable
+            // start, NO handsReadOnly) auto-mounts `enter_plan_mode`/`present_plan` so the model can self-enter read-only
+            // plan AT ANY TIME it judges a task needs planning. 🆕 DEFAULT ON (clay: resident; PLAN_MODE_ENABLED=false opts
+            // out). USER-driven plan (permissionMode=plan) ADDS handsReadOnly on top via applyTaskSettings (which also sets
+            // enablePlanMode, idempotent). Additive — widens nothing; the model self-selects when to use it.
             enablePlanMode: config.planModeEnabled ? true : undefined,
+            // Workflow super-set unlock (same shape as the rank-1 roster gap): per-task activation of the
+            // LLM-authored workflow engine (core `run_workflow` + the workflow.ts agent/parallel/pipeline orchestration).
+            // The engine is BUILT but the HTTP API never mapped a body field to `spec.selfOrchestration`, so run_workflow
+            // was per-task unreachable (capabilities advertised `workflows:true` but the LLM could never call it). Gated on
+            // the DEPLOYMENT enabling it (`selfOrchestrationEnabled` → workflowScriptRunner/stores wired; else a set flag is
+            // a harmless no-op core fail-closes). 🔒 Multi-tenant entitlement is NOT blanket-closed here (unlike mcp, which
+            // has no engine entitlement) — core's `runtimeCapsResolver` enforces `allowWorkflows` (the third-stage
+            // per-principal cap) ON THE ENGINE, so a multi-tenant principal WITHOUT the entitlement gets run_workflow
+            // fail-closed by core (no resolver ⇒ fail-closed). Single-user honors directly. Three-gate: engine-can ∧
+            // center-may(allowWorkflows) ∧ shell-show. (Logic + gates documented in `selfOrchestrationFromBody`.) 🔒 The
+            // multi-tenant floor: pass whether an entitlement RESOLVER is wired — core's allowWorkflows is TIGHTEN-ONLY
+            // (no resolver ⇒ fail-OPEN per-principal), so the helper fail-closes multi-tenant when none is present.
+            // L2 ultracode (design/111): OR the preset's selfOrchestration:true into the body intent, passed THROUGH the
+            // existing gate — it grants nothing a raw body.selfOrchestration:true couldn't (multi-tenant still fail-closes
+            // without an entitlement resolver). The preset never bypasses the闸.
             selfOrchestration: selfOrchestrationFromBody({ selfOrchestration: body.selfOrchestration === true || parsedSettings.settings?.ultracode === true }, config, Boolean(centerRuntimeCapsResolver)),
+            // C1 (core 1.219, subagent viewing pane): opt-in widening of the forward sink from
+            // task_progress-only to a delegated child's live CONTENT events (text_delta/reasoning_delta/tool_start/
+            // tool_end, each carrying `parentToolCallId` attribution). Purely a RENDER channel — core never merges the
+            // child stream into the parent's model context. The service's forward-sink consumers redact per §E1 (shared
+            // builders); default OFF = prior progress-only behavior. Strict `=== true` (never a truthy coercion).
             forwardSubagentEvents: body.forwardSubagentEvents === true ? true : undefined,
+            // design/122 (core 1.225): opt-in retention of SETTLED sub-agent sessions so the operator/
+            // shell can REVIVE them (POST /v1/runs/:id/subagents/:target/resume). Defensive normalize + clamp
+            // (RESUME re-runs resolveSpec without HTTP validation): boolean passes; an object's ttlMs/max are clamped
+            // to sane ceilings (retention pins live sessions in memory — a caller must not turn the knob into a
+            // resource hold; core's own defaults are 30min/16, the run-scoped ledger releases everything at parent
+            // end either way). Malformed values fall to undefined = OFF (core default), never a throw.
             retainSubagentSessions: normalizeRetainSubagentSessions(body.retainSubagentSessions),
+            // [876] per-task custom subagents (core 1.295 TaskSpec.agents — CC `.claude/agents/` parity): the shell's
+            // resolved AgentDefinition[] rides the spec verbatim (model already a real name/Model object — no alias
+            // translation here). 🔒 TOB tenant gate + defensive per-item normalize live in taskAgentsFromBody
+            // (spec-fields.ts): multi-tenant is fail-closed (warn task_agents_ignored — no per-tenant caps face yet,
+            // capabilities.taskAgents advertises false); RESUME replays skip the HTTP whitelist 400 → illegal items
+            // DROP+warn per entry (task_agent_dropped), never a bricked resume. Absent/empty ⇒ no key (byte-compat).
+            // [1.211 codex L] 内联闭包换 spec-fields 真出口(taskAgentsSpecFragment)——测试直接 import 调真
+            // fold,SOURCE PIN 收敛为「resolveSpec 内恰一次调用点」单锚(文本重写同构表达式的假绿面就此关)。
             ...taskAgentsSpecFragment(body.agents, config.requirePrincipal, (event, fields) => logger.warn(event, { ...fields, sessionId: auth?.sessionId ?? null })),
+            // [854]② (core 1.295): opt-out of task-end session-background reaping ("keep my dev server running").
+            // Resource-residency grant on the host lane → single-user gate like backgroundShell/hooks (multi-tenant
+            // warns task_retain_bg_ignored + ignores; capability advertises false). Only literal `true` rides (false =
+            // core default, key omitted); non-boolean is 400 at submit, defensively dropped on a resume replay.
             ...(retainBackgroundProcessesFromBody(body.retainBackgroundProcesses, config.requirePrincipal, (event, fields) => logger.warn(event, { ...fields, sessionId: auth?.sessionId ?? null })) === true
                 ? { retainBackgroundProcesses: true }
                 : {}),
+            // [1052]② (core 1.314): per-run 工具面收窄两位——excludeTools=roster 真卸载,deferTools=延迟披露
+            // (cli「Workflow 默认开不暴露」承载位)。tighten-only(core 继承 union 不变量),无租户门;defensive
+            // normalize(resume 重放),提交面 400 在 HTTP 门。
             ...(() => { const v = toolNameListFromBody(body.excludeTools); return v ? { excludeTools: v } : {}; })(),
             ...(() => { const v = toolNameListFromBody(body.deferTools); return v ? { deferTools: v } : {}; })(),
+            // [1144]/[1146] (core 1.328 R2): promptProfile 双形轴直通——纯呈现轴无租户门(deferTools 姿势);
+            // 缺省不挂键(引擎缺省 simple);非法值由 HTTP 门 400,resume 重放 defensive DROP。
             ...(() => { const v = promptProfileFromBody(body.promptProfile); return v ? { promptProfile: v } : {}; })(),
+            // [922]①/[915]② (core 1.296): interactiveTools 三态旋钮直通——boolean 上 spec(壳 -p 恒 stamp false=
+            // A3 类「headless 提问 park」根治腿;plan 显式 true 恒赢),undefined=core 自动判据(送达面探测)。
+            // per-run 工具面选择无跨租户面 ⇒ 无租户门;非 boolean 由 HTTP 门 400,resume 重放 typeof 检查天然 DROP。
             ...(typeof body.interactiveTools === "boolean"
                 ? { interactiveTools: body.interactiveTools }
                 : {}),
+            // design/131 (core 1.246): per-task resilience INTENT flags. allowDegrade/allowFailover are
+            // caller-facing (a bench/eval run wants true failure shapes); bypassBreaker is operator-only (normalizer
+            // drops it for non-operators — it punches through a SHARED breaker). All-absent = byte-compat.
             resilience: normalizeResilience(body.resilience, explicitOperator(auth?.principal, config.operatorPrincipals)),
+            // design/132 (core 1.249): one-shot end-game verification nudge ("re-run the final artifact through
+            // its real entrypoint before finishing"). OPT-IN by core's own judgment (default ON lost the evidence case:
+            // +1 turn on every interactive write task) — the AUTONOMY caller declares it (harness/scheduler lanes).
+            // [849] scenario-declared leg: the `autonomous` scenario pins it in its bundle (cap.finalVerification —
+            // picking that scenario IS the autonomy declaration, so this is not "inferring from scenario"); OR-folded
+            // with the caller's explicit flag — a scenario can only ADD the closing verification turn, never strip a
+            // caller's request. Children do not inherit (core semantics).
             finalVerification: cap.finalVerification === true || body.finalVerification === true ? true : undefined,
+            // design/133 (core 1.251): turn-boundary attachment reminders (todo/changed-files/plan-mode),
+            // literal-true unions — the normalizer drops `false`/garbage keys instead of forwarding them (core contract:
+            // "off = delete the key, never send false"). Resume-safe by construction: the persisted body is full JSON
+            // and this is the single translation point, so this line IS the whitelist inclusion.
             attachments: normalizeAttachments(body.attachments),
+            // hooks(阶段一,gate 见上面 taskHooks 装配):core 是整槽覆盖(`spec.hooks ?? deps.hooks`,
+            // runtask gateBaseline 注释点名),task hooks 一挂会 shadow deps.hooks 上的 TOOL_TRACE 观测 → composeHooks
+            // 把部署基线折进来(部署槽先跑=观测看到真实执行)。无 task hooks 时不挂字段,deps 路径原样。
             ...(taskHooks ? { hooks: composeHooks(deploymentHooks, taskHooks) } : {}),
             model: picked.model,
+            // [1479]① compactionModel (design/145 cheap compaction gear): catalog-gated to the SAME expanded view as
+            // body.model (canonical name form). resolveSpec is the AUTHORITY (codex R5 — the prepareSpec 400 is only
+            // a fast-fail UX layer; the catalog hot-refreshes in place, so a ref valid at the HTTP gate can be gone
+            // after the authorize/resolve awaits): unknown on a FRESH leg → 400 fail-loud (the documented guarantee —
+            // never a silent price change); unknown on a RESUME replay → drop + warn (core's resolveModel THROWS on
+            // an unknown compactionModel, which would brick the resume; the fallback is the summarize role / main
+            // model, the pre-field behavior).
+            // Window note (codex R6, requalified): the resolveSpec→Runner handoff shares spec.model's DOCUMENTED
+            // restart-window class ([865] / the wireCatalog note above) — the Runner resolves the canonical string
+            // against ITS OWN constructor-time expanded snapshot, so a hot refresh between here and prepare can
+            // desync the two views. Inside that window the failure mode is core's resolveModel TYPED THROW
+            // ("Unknown model ref", roles.js dist-read) = a fail-loud task error, never a silent price change —
+            // the same honest posture the sibling field ships with. Binding a Model OBJECT here instead would
+            // diverge from spec.model's string-intent contract and freeze catalog bytes into the persisted body.
             ...((() => {
                 if (typeof body.compactionModel !== "string" || body.compactionModel.length === 0)
                     return {};
@@ -2128,10 +3861,28 @@ async function main() {
                 }
                 return { compactionModel: cm };
             })()),
+            // E7 (shell-host contract): reasoning-effort selection threaded to core's ThinkingLevel. Defensive
+            // isThinkingLevel guard — RESUME re-runs resolveSpec WITHOUT the HTTP-layer 400 validation, so an invalid/
+            // absent value falls through to the resolved role's default thinking (core's RoleSpec.thinking), never throws.
+            // L2 ultracode (design/111): the preset FLOORS thinking at the ultra tier (= max, via core resolveReasoningProfile);
+            // awareness rides for free (core composes it from thinking∈{xhigh,max}). Else the explicit reasoningEffort.
             thinking: effectiveThinking(body.reasoningEffort, parsedSettings.settings?.ultracode === true),
+            // Per-model auth (sema-registry apiKeyEnv): core calls this per brain call / cascade rung so each
+            // model uses its own upstream key; a model without one falls back to the gateway key. undefined
+            // when no per-model keys are configured → unchanged single-key behavior.
             getApiKeyAndHeaders: keyResolver,
+            // [854]④ per-request 配速:body.limits.{timeoutSec,maxOutputTokens,maxTurns} 现在被收下(核对上游
+            // TB2.0 实测诉求;旧姿势「body limits 一律忽略」作废)。合成规则在 resolveTaskLimits(spec-fields.ts):
+            //  - body.timeoutSec 给了就用 body(caller 显式配速,可低于内建墙;已被可选 TASK_TIMEOUT_MAX_SEC 封顶);
+            //  - body 缺席保持既有姿势 = tenancy 墙钟(单用户 turnkey 无墙 / 多租 2400s、大任务 3600s,
+            //    clay 2026-07-04 make-real 教训①)+ env TASK_TIMEOUT_SEC 只抬不降(taskWallClockSec 内 Math.max);
+            //  - maxOutputTokens/maxTurns 直透传(可选 TASK_MAX_OUTPUT_TOKENS_MAX / TASK_MAX_TURNS_MAX 同款封顶)。
+            // resume 重放持久化 body 不过 HTTP 400 门 → normalizeLimits defensive(0/负/垃圾按键 DROP,不 throw)。
             ...(() => {
                 const limits = resolveTaskLimits(body.limits, taskLimitCaps, taskTimeoutSec, config.requirePrincipal, body.council === true || body.debate === true || scenarioName === "team");
+                // [1301]③ config catalog server 半场:env 封顶不再是「五层五值互不知情」的暗手——每个真在场
+                // 的运营方旋钮以 configOverrides 声明进 spec(advisory,core 折进 config.assembled 的
+                // overrideReasons;「谁设的顶」变成读帧不考古)。只声明 SET 了的键(缺省不设=不污染帧)。
                 const declarations = [];
                 if (taskLimitCaps.timeoutSec !== undefined)
                     declarations.push({ key: "server.limits.timeoutSecCap", value: String(taskLimitCaps.timeoutSec), reason: "env TASK_TIMEOUT_MAX_SEC (operator ceiling on caller limits.timeoutSec)" });
@@ -2139,39 +3890,101 @@ async function main() {
                     declarations.push({ key: "server.limits.maxOutputTokensCap", value: String(taskLimitCaps.maxOutputTokens), reason: "env TASK_MAX_OUTPUT_TOKENS_MAX (operator ceiling)" });
                 if (taskLimitCaps.maxTurns !== undefined)
                     declarations.push({ key: "server.limits.maxTurnsCap", value: String(taskLimitCaps.maxTurns), reason: "env TASK_MAX_TURNS_MAX (operator ceiling)" });
+                // PAIR-REVIEW F-4:budget 族与墙钟基值的声明补齐——[1301]③ 首批只做了 limits 三键,而
+                // MAX_TASK_COST_USD/MAX_TASK_TOKENS 在 caller 缺席时**直接成为** spec 值(cappedCeiling),core
+                // 便记 provenance:"spec"=归因谎报(「谁设的 5 刀」重回考古)。同姿势:只声明 SET 了的键,
+                // server 命名空间,绝不重复 core 目录键。
                 if (config.maxTaskCostUsd > 0)
                     declarations.push({ key: "server.budget.maxCostUsdCap", value: String(config.maxTaskCostUsd), reason: "env MAX_TASK_COST_USD (operator ceiling; becomes the effective value when the caller sends none)" });
                 if (config.maxTaskTokens > 0)
                     declarations.push({ key: "server.budget.maxTokensCap", value: String(config.maxTaskTokens), reason: "env MAX_TASK_TOKENS_MAX (operator ceiling; becomes the effective value when the caller sends none)" });
+                // F-4 附:tenancy 墙钟基值(taskWallClockSec 在 multi-tenant 时注入 2400/3600 基值——同为
+                // 「server 设的顶」,声明其来源;single-user 无墙=不声明)。
                 if (config.requirePrincipal === true)
                     declarations.push({ key: "server.limits.wallClockBaseSec", value: "2400/3600", reason: "tenancy wall-clock base (multi-tenant; big tasks 3600) — TASK_TIMEOUT_SEC raises, never shrinks" });
+                // codex F1:core 目录自有键(limits.timeoutSec 等)**绝不重复声明**——core 已按真 provenance 发
+                // 该字段,叠一条 host-declared 字符串值=同键双条矛盾帧(by-key 投影抹掉权威来源)。server 只
+                // 声明自己命名空间的键;来源语义(caller vs 墙钟)由 timeoutSec 的 spec provenance + 上面的
+                // Cap 声明组合可读。
                 return { ...(limits !== undefined ? { limits } : {}), ...(declarations.length > 0 ? { configOverrides: declarations } : {}) };
             })(),
+            // design/129: the TOC/interactive posture (single-user turnkey — the shell's
+            // session lane) defaults background children to SESSION scope = CC Backgrounded semantics (a bg Agent/
+            // Fork outlives the turn; completion arrives via the durable-inbox push). Multi-tenant / CI / workflow
+            // deployments keep core's "task" default (no orphans burning tokens). Caller-trusted spec field
+            // (systemPrompt tier), NEVER read from the request body. Same tenancy predicate as the wall clock above.
             ...(config.requirePrincipal !== true ? { backgroundScope: "session" } : {}),
+            // ⑤ Per-task budget gate (1.37): honor a caller's requested ceiling but CAP it to the operator
+            // ceiling (a request can ask for less, never more). core fails the task with errorCode budget.*
+            // when crossed. budgetStreamCancel defaults true when maxCostUsd is set.
             maxCostUsd: cappedCeiling(body.maxCostUsd, config.maxTaskCostUsd),
             maxTokens: cappedCeiling(body.maxTokens, config.maxTaskTokens),
+            // 1.40 near-budget degradation: only meaningful with a cost ceiling (the fraction is of it).
+            // When this task has one, switch to the cheaper model at atCostFraction instead of hard-failing.
+            // vision precheck (adversarial-review finding): DROP degrade for an image-carrying task when the
+            // degrade TARGET can't read images (toSupportsImages=false). The precheck only sees the picked model, not the
+            // external degrade target — so without this a runtime degrade would send the images to a text-only gateway (the
+            // opaque 400 the precheck prevents). The task keeps its vision-capable main model; near-budget it hard-fails on
+            // cost instead of image-failing. MODEL_DEGRADE_TO_VISION=true opts back in.
             degrade: (() => {
                 if (!config.degrade || cappedCeiling(body.maxCostUsd, config.maxTaskCostUsd) === undefined)
                     return undefined;
                 if (Array.isArray(body.images) && body.images.length > 0 && !config.degrade.toSupportsImages) {
+                    // S14 (SILENT-FALLBACK P0-f): this drop was undetectable — the task keeps its vision-capable main
+                    // model and near-budget it hard-fails on cost instead of degrading (rationale above). Surface it.
                     metrics.inc("degrade_dropped_total", { reason: "vision_target" });
                     logger.warn("degrade_dropped", { reason: "vision_target", model: picked.model, images: body.images.length });
                     return undefined;
                 }
                 return { to: config.degrade.to, atCostFraction: config.degrade.atCostFraction };
             })(),
+            // Long-term memory (design/138 S1): enabled when the memory ENGINE is wired AND a scope was derived
+            // (single-user only — multi-tenant derives none, memory dark). MF-30 PAUSE (option B, per-request —
+            // clay 2026-06-27 confirmed with core): `body.memoryWrite:false` makes THIS run read-only over memory
+            // (`writeScope:null` — the engine materializes/reads but harvest commits nothing). Per-request (not a
+            // stored flag) → no new per-session state; the shell carries the toggle. RESUME re-runs resolveSpec
+            // from the persisted body, so a paused run stays paused across resume legs.
             memory: memoryEngine ? memorySpecForRequest(auth?.memoryScope, body.memoryWrite, s4DefaultScopes) : undefined,
+            // Scenario-provided capabilities (e.g. code-review = repo tools + reviewer subagents + prompt).
+            // RFC A2: the SelectEnvironment tool rides after the scenario's tools (spec.tools is ADDITIVE to core's
+            // built-in roster — prepare-task mounts first-party tools separately). Only when the image chain is live.
             tools: ((base) => {
                 const extra = [...(selectEnvTool ? [selectEnvTool] : []), ...(sendUserFileToolSpec ? [sendUserFileToolSpec] : [])];
                 const merged = extra.length > 0 ? [...(base ?? []), ...extra] : base;
+                // [803]④ defer face (EXPERIMENTAL, default OFF): long-tail first-party tools get per-tool defer:true
+                // (assessment + why NOT deferMode:"auto"/SendUserFile: src/capabilities/tool-defer.ts header).
                 return merged && config.toolDeferLongtail ? applyLongtailDefer(merged, true) : merged;
             })(cap.tools),
+            // Personalization: the caller's own skills ride after the scenario's; scenario
+            // wins on a name clash (mergeUserSkills — the security baseline can't be shadowed). HTTP layer
+            // already validated shape + caps (validateUserSkills).
             skills: mergeUserSkills(cap.skills, body.skills, logger),
+            // Sema-registry MCP servers (B1) filtered to this scenario (env-NAME refs already resolved at startup),
+            // PLUS the caller's gated per-request MCP (R3 — TOC local `.mcp.json`). resolveRequestMcp honors body.mcpServers
+            // on any SINGLE-USER deployment (`requirePrincipal!==true` — the requester is the super-admin of their own
+            // worker; the stdio MCP runs on the worker, not the exec env, so the lane is irrelevant → seamless TOC↔cloud);
+            // a multi-tenant deployment returns the baseline unchanged (gate closed → ignored, advertised via
+            // capabilities.mcpInjection). Baseline wins on a name clash (a caller can ADD a server, never SHADOW a configured one).
             mcp: resolveRequestMcp(mcpForScenario(config.mcpServers, scenarioName), body.mcpServers, config, logger),
+            // center prompts 投影([1057]①f):center 下发的场景终形(overrides[s] ?? 基线)赢过内置 provider
+            // (center-wins,scenario overlay 同先例);无 pack/该场景空声明 ⇒ 内置照旧。声明数组逐字喂 typed
+            // 钩子(contentHash 透传,core 1.315 校验入 manifest);packId 归因在采用日志(center_prompts_adopted)。
+            // codex R4:读请求级快照 centerDecls(与 append-less 门同一份),不再回读活 ref——刷新竞态下门与
+            // provider 才不会各看一版(TOCTOU:门判安全、pick 到已组装包=core 侧静默丢 rider 复活)。
             promptProvider: centerDecls ? centerPromptProvider(centerDecls, scenarioName) : cap.promptProvider,
+            // F4: high-risk write approval gate. DURABLE (design/45, opt-in): the gated `ask` SUSPENDS the task
+            // (durable checkpoint, resumable on any replica). Else the legacy POLL gate: the call waits on a
+            // durable pending row any instance can decide via /v1/approvals, releasing at the task deadline.
+            // Durable ask (TC-5.4, core 1.95): in durable mode an AskUserQuestion call suspends like an F4 gate —
+            // the question policy adjudicates it `ask`, the operator answers out-of-band, and the resume carries
+            // the QuestionAnswer (server.ts `body.answer` → onQuestion closure). Suspend side mounts the tool with
+            // QUESTION_AWAITS_RESUME (it must never run pre-suspend; reaching it = wiring bug, typed throw).
             toolPolicy: durableEnabled
                 ? combinePolicies(createDurableQuestionPolicy(), createDurableAskPolicy({
                     requireApproval: config.approvalRequire, deny: config.approvalDeny, autoBudget: config.approvalAutoBudget, neverAuto: config.approvalNeverAuto,
+                    // The probe key is the CONTINUED session (auth.sessionId — the same id that keys the
+                    // durable checkpoint /decide route). A fresh session (no body.sessionId) has no exemptions by
+                    // construction; fail-closed inside the policy on a store error.
                     ...(approvalExemptionStore && auth?.sessionId
                         ? {
                             exempt: (toolName) => approvalExemptionStore.has(auth.sessionId, toolName),
@@ -2186,7 +3999,8 @@ async function main() {
                         deny: config.approvalDeny,
                         pollMs: config.approvalPollMs,
                         context: () => ({ sessionId: auth?.sessionId ?? null, owner: auth?.principal ?? null }),
-                        neverAuto: config.approvalNeverAuto,
+                        neverAuto: config.approvalNeverAuto, // workflow audit 2026-07-13: the ordering lock must hold on the OA leg too
+                        // Same probe on the legacy poll gate (sessionId threaded via ctx here).
                         ...(approvalExemptionStore
                             ? {
                                 exempt: (sessionId, toolName) => approvalExemptionStore.has(sessionId, toolName),
@@ -2195,8 +4009,21 @@ async function main() {
                             : {}),
                     })
                     : singleUserAutoAcceptBaseline
+                        // 🔴 (live finding: single-user host-lane Bash ran UNGATED, no adjudication): a
+                        // single-user turnkey worker with NO expressed gate intent previously left `toolPolicy` UNDEFINED →
+                        // core's write-capable hand tools mount UNADJUDICATED (core error-logs it every task; host lane has NO
+                        // sandbox to fall back on). CC's trust model is auto-accept, but the GATE MECHANISM must be PRESENT
+                        // (core 原则: "机制留、默认可更宽 auto-accept"). So wire an adjudicated auto-accept BASELINE
+                        // (`createAllowDenyPolicy({})` = a present, effect-aware policy that allows all): satisfies core's
+                        // `hasEffectAwareGate`, restores observability + a hook/tighten point, and the operator STILL tightens
+                        // irreversible ops via `AUTONOMY` / `commandPolicy` (layered TIGHTEN-ONLY by applyRuntimeGovernance).
+                        // Interactive approval routed to the shell HITL = follow-on. 🔴 `singleUserAutoAcceptBaseline` requires
+                        // ZERO gate intent — a single-user op who SET approval flags but wired no store falls to `undefined`
+                        // (core warns = real misconfig, not masked); multi-tenant likewise stays `undefined` (approval required).
                         ? createAllowDenyPolicy({})
                         : undefined,
+            // Durable suspend needs both the store (here, per-task) and the opt-in scope key (multi-tenant =
+            // principal; "_" when auth is off). core suspends on a policy `ask` only when these are present.
             ...(durableEnabled
                 ? {
                     checkpointStore,
@@ -2204,6 +4031,11 @@ async function main() {
                         scope: auth?.principal ?? "_",
                         ...(config.approvalTimeoutSec > 0 ? { ttlMs: config.approvalTimeoutSec * 1000 } : {}),
                     },
+                    // design/80 seam #2: opt this task into resource/preempt durable-suspend (design/74 third state)
+                    // when RESOURCE_SUSPEND=true — a budget/turns/walltime limit OR a scheduler preempt durably SUSPENDS
+                    // (resumable) instead of failing. SAME scope key as durableApproval (the principal). The decision
+                    // (incl. the 🔴 verify/cascade EXCLUSION that keeps eligibility aligned with the preemptSignal wiring,
+                    // so an inner suspend can't orphan a VM+checkpoint) lives in the pure, unit-tested `resourceSuspendOptIn`.
                     ...((rs) => (rs ? { resourceSuspend: rs } : {}))(resourceSuspendOptIn({
                         enabled: config.resourceSuspend,
                         ttlSec: config.resourceSuspendTtlSec,
@@ -2215,21 +4047,58 @@ async function main() {
                 }
                 : {}),
         };
+        // Runtime governance "second baton" (center §10): compile the operator's autonomy + commandPolicy onto the
+        // spec TIGHTEN-ONLY. commandPolicy layers via combinePolicies onto the approval/durable baseline above (NOT a
+        // bare overwrite — TRAP #1), autonomy expands to handsReadOnly/shellGate (TRAP #2). Applied here so it also
+        // re-applies identically on the resume paths (which rebuild via resolveSpec) — core requires shellGate/
+        // toolPolicy be re-supplied on resume (omitting shellGate would leave a resumed run's bash UNGATED).
+        // tightenTaskSpec THROWS on a loosening misconfig (fail-loud).
+        //
+        // 🔴 RESUME uses LIVE config (not a per-task frozen snapshot), IDENTICAL to how the approval baseline above
+        // reads live `config.approvalRequire`. So if an operator LOOSENS the fleet governance while a task is
+        // suspended, the resumed task picks up the looser policy (governance stays per-call tighten-only, so a
+        // mid-suspend TIGHTENING is honored; a loosening is an explicit operator action). Freezing deployment policy
+        // per-task across suspend is a larger, separate decision that must cover the approval baseline too — tracked
+        // for center (adversarial-review HIGH-1), deliberately NOT a governance-only partial freeze here (that would
+        // be an inconsistent false-safety: approval would still be live).
         const governedBase = applyRuntimeGovernance(spec, { autonomy: config.autonomy, commandPolicy: config.commandPolicy });
+        // Fold the client's per-request settings stamp onto the governed spec, TIGHTEN-ONLY (deny-wins) — AFTER
+        // the approval baseline + operator governance, so the order is deployment ⊇ operator ⊇ client (each can only
+        // narrow). tightenTaskSpec THROWS if the client settings would LOOSEN a stricter baseline → a 422 client error
+        // (a settings stamp is tighten-only by contract; never a silent weakening). Re-applies idempotently on resume.
         let governed = governedBase;
+        // R4: fold a LIGHT top-level `body.permissionMode` onto the parsed settings (the explicit
+        // per-turn intent WINS over a bundle `defaultMode`) → the SAME tighten-only governance path. Post-[816] all
+        // five CC modes are honored as gate-SHAPE choices (see coercePermissionMode/deriveSettingsPolicy): `plan` ⇒
+        // read-only hands + present_plan; `default`/`auto` ⇒ the fs-write ask gate; `acceptEdits` ⇒ the cwd-domain
+        // variant; `bypassPermissions` ⇒ no mode gate (the deployment baseline is composed above and untouchable).
         const bodyMode = coercePermissionMode(body.permissionMode);
         let effectiveSettings = bodyMode ? withPermissionMode(parsedSettings.settings, bodyMode) : parsedSettings.settings;
+        // codex R3 second bypass: settings.outputStyle ALSO lands in spec.appendSystemPrompt (applyTaskSettings
+        // fold) — on an append-less pack core would discard it silently, exactly like the top-level rider. Same
+        // disposition: fresh submits 400 at the HTTP gate; here (the resume mirror + any leg the gate didn't see)
+        // strip + warn. Spread-copy, never mutate parsedSettings (it may be consulted elsewhere).
         if (appendLessPack && effectiveSettings?.outputStyle) {
             logger.warn("output_style_dropped", { detail: "the effective prompt pack cannot mount the append slot (already-assembled systemPrompt or center assembled-identity declaration)", sessionId: auth?.sessionId ?? null });
             const { outputStyle: _dropped, ...rest } = effectiveSettings;
             effectiveSettings = Object.keys(rest).length > 0 ? rest : undefined;
         }
+        // codex R14 resume mirror of the aggregate cap: both carriers fold into ONE spec field — a pre-cap stored
+        // body can be individually valid but combined over the bound (fresh submits 400'd this in prepareSpec).
+        // Drop the STYLE (it composes second; the knowledge rider keeps priority) + warn, never silently oversize.
         if (effectiveSettings?.outputStyle && acceptedAppend && acceptedAppend.length + 2 + effectiveSettings.outputStyle.length > MAX_SETTINGS_OUTPUT_STYLE_CHARS) {
             logger.warn("output_style_dropped", { detail: `combined append carriers exceed the ${MAX_SETTINGS_OUTPUT_STYLE_CHARS} cap (rider ${acceptedAppend.length} + style ${effectiveSettings.outputStyle.length}) — style dropped (pre-cap stored body on a resume leg?)`, sessionId: auth?.sessionId ?? null });
             const { outputStyle: _dropped2, ...rest2 } = effectiveSettings;
             effectiveSettings = Object.keys(rest2).length > 0 ? rest2 : undefined;
         }
+        // [820]③ scratchpadDir, hoisted from the envFacts block below so the SAME per-session dir feeds BOTH the
+        // `# Environment` fact and the fs-write gate's exemptDirs (single-source path via scratchpadDirFor inside
+        // ensureScratchpadDir). HOST-semantics lanes only + session required — rationale at the envFacts consumer.
         const hostSemanticsLane = config.remoteExec === undefined || config.remoteExec.provider === "host";
+        // G3([816]③/[820]③,[1840]§四):壳供 body.scratchpadDir 优先——壳(CC 形)有自己的 per-session
+        // scratchpad 约定路径,接受后事实/豁免/根围栏三处同源指向壳的目录(壳侧提示词与 server 写门不再
+        // 两个 scratchpad)。验收门 fail-closed(多租户/远程 lane/浅路径全拒收,warn 后回落自算)——
+        // 规则与理由集中在 acceptShellScratchpadDir。
         const shellScratchpad = await acceptShellScratchpadDir(body.scratchpadDir, {
             requirePrincipal: config.requirePrincipal,
             hostSemanticsLane,
@@ -2238,19 +4107,47 @@ async function main() {
         const scratchpadDir = shellScratchpad ??
             (hostSemanticsLane && auth?.sessionId ? await ensureScratchpadDir(config.localDataRoot ?? localRoot, auth.sessionId) : undefined);
         if (effectiveSettings) {
+            // [816]/[820]① fs-write gate wiring — HOST-semantics lanes only: core's createFsWriteGatePolicy
+            // canonicalizes每一个 target/dir 走给定 env 的真实 fs(exists/canonicalPath/readLink,dist 亲读),所以
+            // env 必须就是 hand 工具真正写的那块盘。e2b/k8s/ssh/adb/local-docker 的沙箱 env 由 core 在 spec 之后
+            // 才铸(executionEnvFactory),这里给 worker 本机 env 会拿错误的 fs 裁决(symlink/exists 全答错)——
+            // 沙箱 lane 诚实不挂(gate=undefined ⇒ derive 回落 base 规则,pre-[816] 行为)。
+            // NodeExecutionEnv 构造是纯字段赋值(不 spawn)。
+            //
+            // 修5(三路复审 W4,cwd 基准漂移):gate 的 cwd 基准=与 hands 真跑处同源,分三形:
+            //  · session 注册过 cwd(cwdHonored 已在注册处把关)⇒ 用它——与 host factory 的 effectiveHostWorkspace
+            //    第一优先级同源(顶层 HTTP 任务无 parentCwd,resolver 即 session cwd)。
+            //  · `host` factory lane 且未注册 ⇒ hands 落在 factory 才铸的 EPHEMERAL per-task 目录(spec 期不可知)。
+            //    此前回退 process.cwd()(服务自身启动目录)——acceptEdits 会把服务目录当 auto-allow 域、多任务共享
+            //    进程时判定漂移(W4)。改为 fail-safe 哨兵:一个从不创建的目录 ⇒ acceptDirs/相对路径 canonicalize
+            //    失败即 ask(fs-write-gate-policy dist 亲读:dir.ok=false 跳过、target 解析失败=ask);绝对路径裁决
+            //    (hand 工具的书面契约形)与 scratchpad exempt 均不受影响。
+            //  · provider 未设(in-process host / run-local)⇒ hands 就在本进程 cwd 跑(无 factory),process.cwd()
+            //    正是真工作目录,保留。
             const fsWriteGate = hostSemanticsLane
                 ? (() => {
                     const sessionCwd = auth?.sessionId ? effectiveHostWorkspace(perSessionCwd.get(auth.sessionId), {}) : undefined;
                     const gateCwd = sessionCwd ??
                         (config.remoteExec === undefined
                             ? process.cwd()
-                            : join(config.localDataRoot ?? localRoot, "fs-write-gate-unrooted"));
+                            : join(config.localDataRoot ?? localRoot, "fs-write-gate-unrooted")); // never created — see above
                     return {
                         env: new NodeExecutionEnv({ cwd: gateCwd }),
                         cwd: gateCwd,
                         ...(scratchpadDir ? { scratchpadDir } : {}),
+                        // ③ (core 1.295) sensitive-path write deny set:组合进 gate 腿的同一 combinePolicies 折叠
+                        // (deny 恒赢 —— 豁免/acceptDirs 越不过;集合取舍 core 成文,server 只透传 config 旋钮:
+                        // 缺省 = core RECOMMENDED_SENSITIVE_PATTERNS,SENSITIVE_WRITE_PATTERNS 显式替换/off 关闭)。
                         ...(config.sensitiveWritePatterns.length > 0 ? { sensitivePatterns: config.sensitiveWritePatterns } : {}),
+                        // [1557]§四 opt-in(cli[1555]②「Bash echo > file 绕写门」缺口的部署侧补丁):MANUAL_MODE_SHELL_GATE
+                        // 未设置时 config.manualModeShellGate 缺席,本行不传字段——deriveSettingsPolicy 的 default/
+                        // auto/acceptEdits 分支照旧不碰 TaskSpec.shellGate,零行为变化。
                         ...(config.manualModeShellGate ? { shellGate: config.manualModeShellGate } : {}),
+                        // [841]① / core 1.294 exemption seam:gate 产 ask 前查同一只 approval_exemption 店(与 decide
+                        // remember="session" 的授予、ask 政策层探针同店同 canonical toolName 键空间)——「本会话不再询问」
+                        // 对 fs-write 门同 turn 即时生效(父+继承子任务,ask 路径不再重入)。has() reject ⇒ core 按
+                        // 未豁免处理(fail-closed 照 ask),与店契约的调用方纪律一致;命中打 info 审计(对齐
+                        // approval_exempted 的短路留痕,不记路径,路径留在 core 的 allow message 里)。
                         ...(approvalExemptionStore && auth?.sessionId
                             ? {
                                 isExempt: async (toolName) => {
@@ -2264,6 +4161,10 @@ async function main() {
                     };
                 })()
                 : undefined;
+            // [1248]②/codex F2 — the workflow ask leg's session-exemption probe, on EVERY lane (unlike fsWriteGate:
+            // the workflow gate is name-keyed, not fs-adjudicated). Same store + canonical toolName key space as the
+            // fs-gate probe — one remember="session" grant serves both; without it the durable lane re-parks every
+            // later run_workflow call after an operator already granted "don't ask again this session".
             const workflowGate = approvalExemptionStore && auth?.sessionId
                 ? {
                     isExempt: async (toolName) => {
@@ -2281,12 +4182,36 @@ async function main() {
                 throw new HttpError(422, `settings are tighten-only and cannot loosen the deployment policy: ${e.message}`);
             }
         }
+        // subagent-hands follow-on (adversarial-review finding): core does NOT propagate
+        // handsReadOnly/shellGate to a delegated subagent (SubagentToolOptions has NO read-only knob; subagent.js's child
+        // runTask omits it). So a read-only (permissionMode=plan) parent that mounts the Task tool would let the CHILD get
+        // WRITABLE hands — now reachable because subRunner has an executionEnvFactory (the hands fix). That defeats plan
+        // mode's read-only contract (a within-tenant gap, not a cross-tenant breach). Until core propagates it (relayed),
+        // strip the delegation tools when this task is hands-read-only — a read-only run delegates nothing writable.
+        // `stripDelegationTools` (runtime-governance.ts, tested there) matches the subagent tool ("Agent", core 1.202
+        // canonical; legacy alias "Task") + Fork in CANONICAL space — the pre-1.202 raw `!== "Task"` filter here
+        // silently stopped matching when core renamed the tool (fail-open: a plan-mode parent could delegate a
+        // WRITABLE-hands child).
         if (governed.handsReadOnly === true && Array.isArray(governed.tools)) {
             governed = { ...governed, tools: stripDelegationTools(governed.tools) };
         }
+        // §7 P0.5 per-task sandbox image(用户按需选像): the caller sends a PROFILE
+        // (intent) — NEVER a digest (a sha256 is enumerable + caller-unbound → trusting a caller digest is fail-OPEN;
+        // a user could pass another tenant's digest). The TRUSTED control plane resolves profile→digest with the
+        // caller's principal, FAIL-CLOSED (same visibility the /v1/images/select admission uses), and registers it by
+        // sessionId for the k8s factory to apply per-pod. RESUME re-runs resolveSpec ⇒ re-resolves LIVE (no stale
+        // frozen digest), consistent with the governance live-config discipline above.
+        // RFC A2: a session-level SelectEnvironment binding (PROFILE intent, tool-written) is the fallback when the
+        // request body carries no explicit profile. Body wins (an explicit caller choice for THIS task); either way
+        // the profile is re-resolved FAIL-CLOSED right here — a session binding never skips re-admission, and the
+        // F3 boundary contract holds structurally (binding is only read at task boundaries, children inherit
+        // the registered ref at spawn).
         const bodyProfile = typeof body.sandboxImageProfile === "string" && body.sandboxImageProfile.length > 0 ? body.sandboxImageProfile : undefined;
+        // cascade/verify mirror the HTTP-layer v1 reject (server.ts): those flows strip/replace the session, so a
+        // session-level binding would not reach the rungs/verifier sub-run — silently mixed environments. A body
+        // profile on cascade/verify is already 400-rejected up front; the session fallback simply does not apply.
         const taskImageProfile = bodyProfile ?? (body.cascade === true || body.verify === true ? undefined : sessionEnvSelection.get(auth?.sessionId));
-        let resolvedImageCaps;
+        let resolvedImageCaps; // RFC A1: rides into envFacts
         if (taskImageProfile !== undefined) {
             if (config.remoteExec?.provider !== "k8s") {
                 throw new HttpError(400, "sandboxImageProfile is only supported on the k8s sandbox backend");
@@ -2303,16 +4228,54 @@ async function main() {
             const resolved = await resolveSandboxImageRef({
                 profile: taskImageProfile,
                 ...(capsNeeded && capsNeeded.length > 0 ? { capabilitiesNeeded: capsNeeded } : {}),
+                // principal comes from the auth channel (trusted header / verified JWT), NEVER the body — so a caller
+                // cannot widen its own visibility. explicitOperator (NOT isOperator): an empty OPERATOR_PRINCIPALS must
+                // yield operator=false here — isOperator([],p)=true-for-all would let any caller resolve tenant-scoped
+                // images on an operator-less deployment (adversarial-review HIGH-1; the bake/direct-door boot guards do
+                // NOT cover per-task image selection).
                 viewer: { operator: explicitOperator(auth.principal, config.operatorPrincipals), tenantId: auth.principal ?? null },
                 index: imageIndex,
             });
             if (!resolved.ok)
                 throw new HttpError(resolved.status, resolved.message);
+            // Register by sessionId — the factory reads it by ctx.sessionId (stable on every path; see the factory
+            // wrapper). RESUME re-runs resolveSpec ⇒ re-resolves LIVE + re-registers (no stale frozen digest).
+            // ⚠️ KNOWN narrow edge (NOT a security breach): two CONCURRENT requests for the SAME session (same owner —
+            // session ownership is enforced) race this set(); a request the run-claim later rejects (409) can leave its
+            // image bound for the active run. Both images are the SAME principal's own admitted images, so the worst
+            // case is the user's run using the user's other selected image (a correctness glitch, not cross-tenant).
+            // Hardening (register-after-claim, keyed by the durable run id) needs the registry threaded into the server
+            // claim path — tracked as a follow-up; cascade/verify are rejected with a profile (see prepareSpec) because
+            // they strip/replace the session and would silently fall back to the default image.
             perTaskImage.set(auth.sessionId, resolved.ref);
             resolvedImageCaps = resolved.capabilities;
         }
+        // RFC A1 (core 1.240.0 `TaskSpec.envFacts`): compose the deployment-trusted sandbox facts
+        // (profile/capabilities from the fail-closed resolution above, region pkgSource, exec-lane egress posture)
+        // and ride them on the spec — core renders the `# Environment` block (sanitized+bounded, egress=none gets
+        // the "downloads will fail" caveat). Facts only ride when known; nothing known ⇒ no field ⇒ block unchanged.
         if (config.envFactsEnabled) {
+            // pkgSource is a FACT only where the derivePkgSourceEnv injection actually lands (the e2b/k8s sandbox
+            // lanes — main.ts wiring above). host/ssh/adb/run-local get NO injection, so with the global default
+            // (1.180.0) an unconditional read would tell the model "official sources" about an environment we never
+            // touched (workflow audit 2026-07-13: honest-facts posture, same as egress's "don't declare what you
+            // don't know").
             const pkgSourceLane = config.remoteExec?.provider === "e2b" || config.remoteExec?.provider === "k8s";
+            // [820]③ scratchpadDir (core field + prompt chain in since 1.257.3; this fill was the missing half).
+            // HOST-semantics lanes only (provider unset = in-process host, or explicit "host"): the advertised path
+            // must be REAL to the executing hands — on e2b/k8s/ssh/adb/local-docker the tools run off this box, so a
+            // worker-local path would be a lie (same honest-facts axis as pkgSource above; the remote lanes get their
+            // IN-SANDBOX path via the [848] branch below instead). Session-scoped dir under
+            // localDataRoot, mkdir'd at the HOISTED compute above the settings fold (fail → fact omitted) — the SAME
+            // dir now feeds createFsWriteGatePolicy's exemptDirs ([820]① landed at core 1.290, wired in the
+            // applyTaskSettings gate above). No sessionId (adhoc no-session task) ⇒ no per-session home ⇒ fact
+            // omitted. Lifecycle/reaping: see ensureScratchpadDir docs (deferred).
+            // [848] remote lanes' counterpart: on e2b/k8s/local-docker/ssh the withRemoteScratchpad-decorated
+            // factory `mkdir -p`s exactly this path on the env's first exec, so advertising it is honest — with
+            // the one best-effort caveat (a failed mkdir leaves the advertised path absent; see the decorator
+            // header). Mutually exclusive with the host-lane fact above by construction (hostSemanticsLane owns
+            // scratchpadDir; this branch is remote lanes only), and it applies the decorator's OWN validity rule
+            // (remoteScratchpadDirFor: absent/unsafe sessionId ⇒ no decoration ⇒ no fact). adb stays factless.
             const remoteScratchpadDir = !hostSemanticsLane && isRemoteScratchpadLane(config.remoteExec?.provider)
                 ? remoteScratchpadDirFor(auth?.sessionId)
                 : undefined;
@@ -2323,17 +4286,36 @@ async function main() {
                 ...(pkgSourceLane ? { pkgSource: config.sandboxPkgSource } : {}),
                 egress: egressForRemoteExec(config.remoteExec),
                 ...(factScratchpadDir ? { scratchpadDir: factScratchpadDir } : {}),
+                // [1467]②(core 1.360)durable resume 铸句真值:按车道能力面,单真源 resumeFactsForLane
+                // (e2b=双 preserved/k8s=按 s3Snapshot 有效能力分叉/ssh·adb·host=scratch preserved/
+                // local-docker=不声明)。
                 resumeFacts: resumeFactsForLane(config.remoteExec?.provider, config.remoteExec?.provider === "k8s" ? { k8sSnapshot: Boolean(config.remoteExec.s3Snapshot) } : undefined),
             });
             if (facts)
                 governed = { ...governed, envFacts: facts };
         }
+        // [1339] scratchpad 写门失效真因:提示词(envFacts.scratchpadDir)和 policy 层豁免(exemptDirs)都
+        // 接了,但 core fs 工具的**根围栏**(resolveKey:taskRootPath+additionalDirectories)在 policy 之前
+        // 短路——Write/Edit 到 scratchpad 直接 path_not_in_root,exemptDirs 根本没被问到(Bash 无根围栏,
+        // 反而能写=口径矛盾还教模型绕门)。修:host 车道把同一 scratchpadDir 折进 spec.additionalDirectories
+        // (server 自算的 per-session 路径,非租户输入,不走 cwdHonored 门限;compute 时已 mkdir,core 的
+        // canonicalPath 必过)。remote 车道暂不折:in-sandbox 路径由 [848] 装饰器首 exec 才 mkdir,prepare 期
+        // canonicalize 会失败被 core 静默跳过——那半场随 core 排序案另行。
+        // codex R3(M2):**独立于 envFactsEnabled 门**——SANDBOX_ENV_FACTS=false 只关事实展示,写门围栏
+        // 豁免是行为契约,关展示不得顺带关围栏(否则该配置下 [1339] 原病复发)。
         if (scratchpadDir !== undefined) {
             const dirs = governed.additionalDirectories ?? [];
             if (!dirs.includes(scratchpadDir))
                 governed = { ...governed, additionalDirectories: [...dirs, scratchpadDir] };
         }
+        // A value router (S1 verdict §6.3 cash-out, src/router/route-orchestration.ts): auto-decide this task's
+        // orchestration. CONSERVATIVE + DETERMINISTIC — default single; escalate to the SUP prevention posture only
+        // on a capability-danger signal (write/exec on a NON-isolated env — an isolated sandbox CONTAINS the harm,
+        // so isolated tasks stay single, matching the verdict's default). caller-explicit team (council/debate/team)
+        // is honored, never auto-produced. Flag-gated (ROUTER_ENABLED) — ships dark, enable after live validation.
         if (config.routerEnabled) {
+            // Resolve isolation from provider AND runtimeClass — a k8s worker on plain runc is NOT VM-isolated
+            // (review HIGH); fail-closed for runc/empty/unknown.
             const isolatedExecEnv = isIsolatedExecEnv(config.remoteExec?.provider, config.remoteExec?.provider === "k8s" ? config.remoteExec.runtimeClass : undefined);
             const decision = routeServiceTask({
                 isolatedExecEnv,
@@ -2343,13 +4325,20 @@ async function main() {
             });
             logger.info("orchestration_routed", { mode: decision.mode, reason: decision.reason, sessionId: auth?.sessionId ?? null });
             if (decision.mode === "supervisor") {
+                // SUP prevention posture: gate every bash (shellGate:"always") AND the direct write hand tools
+                // (edit_file/write_file via toolPolicy) — the verdict's gate-deny on capability-danger. tighten-only
+                // (composes with the governance/approval baseline; never loosens). The worker's existing approval
+                // machinery (durable/poll) enforces the suspend — same precondition as autonomy "ask".
                 return tightenTaskSpec(governed, supPostureOverrides());
             }
         }
         return governed;
     };
     const server = createHttpServer({ runner, config, resolveSpec, stores, coordinators, seams, observability, governance, deployment, knobs });
+    // D-D SLA-timer: wire the server's deny-sweep into the reaper holder declared above (the reaper is defined
+    // before the server, so it calls through this late-bound reference).
     runDenySweep = server.denyExpiredApprovals;
+    // [1934]:绑址旋钮 + 无鉴权自收窄(理由见 resolveBindHost 顶注)。undefined = Node 默认全接口。
     const bindHost = resolveBindHost(config);
     await new Promise((resolve) => (bindHost ? server.listen(config.port, bindHost, resolve) : server.listen(config.port, resolve)));
     logger.info("listening", {
@@ -2359,6 +4348,9 @@ async function main() {
             ? { note: "auto-narrowed to loopback: write face is unauthenticated (ALLOW_UNAUTHED_WRITES with no service token). Set BIND_HOST explicitly to override." }
             : {}),
     });
+    // fleet worker 接线(announce/heartbeat + usage 批报;lease 消费后一拍):boot 完成后
+    // 注册(=首次心跳)。门 = center lane 配置 ∧ FLEET_ADVERTISE_ADDRESS 显式声明(不自猜可达地址);任一缺 → undefined
+    // = 非 fleet 部署零行为。draining 翻转的即刻 announce 在 drainThenShutdown;退出 DELETE 在 hardShutdown。
     const fleetClient = startFleetClientFromEnv(config, {
         instanceId,
         version: serviceVersion(),
@@ -2372,27 +4364,39 @@ async function main() {
         port: config.port,
         model: config.model.id,
         brain: brainSummary(config),
-        breakerState: config.resilience.circuitBreaker ? (breakerState ? `shared(${backend.kind})` : "in-process") : "off",
+        // shared = cross-replica TiDB breaker state; in-process = core's per-replica Map; off = breaker disabled
+        breakerState: config.resilience.circuitBreaker ? (breakerState ? `shared(${backend.kind})` : "in-process") : "off", // 1.108: was hard-coded "shared(tidb)" — lied under DB_BACKEND=pg
+        // On DB_BACKEND=local the wiring coerces sessionBackend to the LABEL "tidb" (meaning "the
+        // backend's durable store, generically") — printing it verbatim read as a SQL deployment on a file-everything
+        // box. Print the effective store instead (same honesty fix as breakerState above).
         session: config.sessionBackend === "tidb" && backend ? `durable(${backend.kind})` : config.sessionBackend,
+        // design/138 S1: the file-based memory engine (single-user only); "off" = MEMORY_ENGINE=off or multi-tenant.
         memory: memoryEngine ? `engine(${memoryEngine.root})` : "off",
         instanceId,
         rateLimitPerMin: config.rateLimitPerMin,
         rateLimit: config.rateLimitPerMin > 0 ? (backend ? `shared()` : "in-process") : "off",
         maxPrincipalCostUsd: config.maxPrincipalCostUsd || null,
         costQuota: config.maxPrincipalCostUsd > 0 ? (backend ? `shared()` : "in-process") : "off",
+        // durable offload store for large tool results (cross-replica wake); else core's in-process default
         toolResultStore: toolResultStore ? (backend?.kind === "local" ? "file(local)" : "shared(sql)") : "in-process",
         otel: config.otel ? config.otel.endpoint : null,
-        perModelKeys: Object.keys(config.modelApiKeyEnv).length,
+        perModelKeys: Object.keys(config.modelApiKeyEnv).length, // models with their own upstream key (else gateway)
         sealedModelKeys: Object.values(config.modelApiKeys).filter((v) => typeof v === "string").length,
-        sealedPoisonedModels: Object.values(config.modelApiKeys).filter((v) => typeof v !== "string").length,
+        sealedPoisonedModels: Object.values(config.modelApiKeys).filter((v) => typeof v !== "string").length, // sealed-box custody keys unsealed (count only — values never log)
+        // SVC-1: durable workflow record + at-least-once notify backend (file = crash-safe ledger; memory = ephemeral)
         workflowRunStore: config.selfOrchestrationEnabled
             ? config.workflowRunStoreBackend === "memory"
                 ? "in-process"
                 : sqlWorkflowRunStore
-                    ? `db(${backend.kind})`
+                    ? `db(${backend.kind})` // P1: cross-replica twin active
                     : "file"
             : "off",
     });
+    // SVC-1 at-least-once notify — CRASH-RECOVERY sweep: once at boot, re-derive every un-acked (started-but-not-
+    // delivered) workflow's terminal state from the durable run store and re-deliver the completion notify that a
+    // prior replica crash dropped (idempotent on the receiver). Fire-and-forget AFTER listen so startup isn't
+    // blocked on it (recovery only re-fires completion notifications — independent of serving new requests). A
+    // sweep throw is logged, never fatal.
     if (workflowNotifyGate) {
         void workflowNotifyGate
             .recover({ orphanGraceMs: config.workflowOrphanGraceMs })
@@ -2408,13 +4412,20 @@ async function main() {
         otelExporter?.stop();
         breakerState?.stop();
         if (costQuota && "stop" in costQuota)
-            costQuota.stop();
+            costQuota.stop(); // the DB-backed quota/limiter (TiDB|PG) have a refresh loop to stop; the in-memory ones don't
         if (rateLimiter && "stop" in rateLimiter)
             rateLimiter.stop();
         runner.sessions.dispose();
         subRunner.sessions.dispose();
+        // TOC local LSP: NodeLspManager holds LOCAL child-process language servers — kill them on shutdown so a
+        // restart doesn't orphan a fleet of stdio servers. dispose() isn't on the LspServerManager interface (only the
+        // concrete managers have it), so probe it; the e2b/k8s bridge manager is a harmless no-op if it lacks one.
         void lspManager?.dispose?.();
+        // SVC-1: release the File journal's append handle; the SQL twins hold no fd (probe — close isn't on the seam).
         void workflowNotifyJournal?.close?.();
+        // core 1.270.1:hardShutdown 终点(drain 已完,in-flight 不再被破坏)全量收割 session 驻留
+        // bg bash(detached 进程组,引擎死后 reparent PID 1 残留=实测;retain-declared 例外在原语内)。
+        // TOB 容器形态同样调=无害且显式;SIGKILL 路径无钩=已知不可救记档。
         try {
             const reaped = defaultTaskRegistry.reapAllSessionBackground();
             if (reaped > 0)
@@ -2423,16 +4434,30 @@ async function main() {
         catch (err) {
             logger.warn("shutdown_background_reap_failed", { err: String(err) });
         }
-        void fleetClient?.stop();
+        void fleetClient?.stop(); // stop heartbeat + flush final usage window + best-effort DELETE deregistration
         server.close(() => {
             void (backend ? backend.close() : Promise.resolve()).finally(() => process.exit(0));
         });
+        // 对抗复查 B-4(HIGH):the exit above only fires after backend.close() SETTLES — a wedged pool teardown
+        // (dead DB, hung socket) kept the "force-terminated" process alive indefinitely (the 10s closeAllConnections
+        // below unblocks server.close(), but nothing bounded backend.close). FINAL deadline: whatever is still
+        // holding after 15s, exit anyway (durable state is already flushed by then — checkpoint/terminal writes
+        // happen before hardShutdown; the pool teardown is best-effort cleanup, not correctness).
         const finalExit = setTimeout(() => { logger.warn("hard_shutdown_final_deadline", { afterMs: 15_000 }); process.exit(0); }, 15_000);
         finalExit.unref?.();
+        // `server.close()` waits for every connection to end — an open SSE stream (/v1/tasks/stream, /events) would
+        // otherwise block it forever, so pool.end()/exit never run and the process hangs until SIGKILL. Drop idle
+        // keep-alives now, then force-terminate any lingering connections after a grace period so `close()` can
+        // resolve and shutdown completes. The timer is unref'd but still fires while the server holds connections.
         server.closeIdleConnections?.();
         const forceClose = setTimeout(() => server.closeAllConnections?.(), 10_000);
         forceClose.unref?.();
     };
+    // SIGTERM = graceful DRAIN — flip `draining` (new billable submits 503+Retry-After, /health carries
+    // draining:true for readiness摘流), then wait for this instance's in-flight legs (live streams + bg/resume) to
+    // finish before the hard shutdown. Bounded by DRAIN_GRACE_MS (default 10min — an interactive turn is minutes;
+    // the previous behavior was a 10s hard-cut that killed long turns). A SECOND SIGTERM or SIGINT (dev Ctrl-C)
+    // skips the wait — k8s sends SIGKILL after terminationGracePeriodSeconds regardless, so the escape hatch is free.
     let draining = false;
     const drainThenShutdown = () => {
         if (closing)
@@ -2445,14 +4470,17 @@ async function main() {
         draining = true;
         drainState.draining = true;
         drainState.since = Date.now();
-        void fleetClient?.announceNow();
+        void fleetClient?.announceNow(); // draining 翻转即刻再 announce — 第一时间自摘流,比任何观测都快
         const inflight = drainState.inflight?.() ?? 0;
         logger.info("draining_started", { inflight, graceMs: config.drainGraceMs });
         if (inflight === 0) {
             hardShutdown();
             return;
         }
+        // 修3(三路复审 B3-2 时钟):drain elapsed/截止计算走 performance.now() 单调域(挂钟跳变不得吞掉/拉长
+        // drainGraceMs 窗);对外报告的 drainState.since(/health drainingSince)保留 epoch(Date.now)。
         const t0 = performance.now();
+        // NOT unref'd on purpose — this timer IS the shutdown driver (the open connections keep the loop alive anyway).
         const tick = setInterval(() => {
             const n = drainState.inflight?.() ?? 0;
             const elapsed = Math.round(performance.now() - t0);
@@ -2465,8 +4493,16 @@ async function main() {
     };
     process.on("SIGTERM", drainThenShutdown);
     process.on("SIGINT", hardShutdown);
+    // SIGHUP(壳窗口关闭把信号打到整个进程组)≠「没人在用这只引擎」:共享引擎形态(同 config 多壳会话,
+    // 引擎按 T11 防孤儿拍骑在首壳进程组里)下 peer 会话还活着——无条件 drain 会把 peer mid-turn 斩掉(499)
+    // 且窗内新提交 503(B3,壳侧 [771]② 取证)。改 hup-pending 空闲窗:不翻 draining(peer 零感知),
+    // inflight()(bg/resume legs + live streams)连续 sighupIdleGraceMs 为 0 才 hardShutdown,任何在飞 leg
+    // 重置窗口。真孤儿(最后一窗关掉)有界自灭=T11 保留;第二个 SIGHUP 升级走既有 drain 路径(硬梯子)。
+    // session 驻留 bash 的全量收割仍挂 hardShutdown 终点(reapAllSessionBackground)。
     process.on("SIGHUP", createSighupIdleHandler({
         inflight: () => drainState.inflight?.() ?? 0,
+        // ⚠️ 时基契约(三路复审修3):lastActivityAt 由 server.ts 以 performance.now() 单调域打点,与
+        // sighup-idle.ts 内部的 `now` seam(缺省 performance.now)同域——不得混入 Date.now 值。
         lastActivityAt: () => drainState.lastActivityAt?.() ?? 0,
         isStopped: () => closing || draining,
         escalate: drainThenShutdown,