@sema-agent/server 1.322.0 → 2.0.0

package/dist/runtime-caps-resolver.d.ts

@@ -1,3 +1,31 @@
+/**
+ * Entitlements resolver — the SERVICE-side wiring of core 1.157's `RunnerDeps.runtimeCapsResolver` (design/99 §K).
+ * (design/158 N11: this module's own exports were renamed `*Caps*` → `*Entitlements*` to stop sharing a word
+ * root with the UNRELATED `capabilities` face (deployment route discovery, `src/capabilities/`) and
+ * `ScenarioBundle` assembly — "caps" meant three different things across those three faces. `RuntimeCaps` /
+ * `EntitlementRuntimeCaps` themselves stay as-is below: they are core's / registry-core's own contract type
+ * names, not ours to rename.)
+ * It is the ENFORCE last-link of the three-stage workflows gate
+ * (engine-can ∧ center-may ∧ shell-show): core calls it ONCE per task at prepare time with `spec.principal`,
+ * and the engine enforces the two caps it CAN enforce — `allowWorkflows` (deny self-orchestration) and
+ * `forceDurableGate` (force a policy `ask` onto the durable-approval wire).
+ *
+ * It pulls the PER-PRINCIPAL entitlement from center's `GET /api/config/effective?principal=` (via
+ * {@link fetchPrincipalCaps}). center has ALREADY pre-resolved the tighten-only intersection (fleet defaults ∩
+ * tier ⊕ roles + time-bounded overrides); the service passes the resolved value through VERBATIM (per center
+ * ruling: "service 只透传 resolved 值、无需再 tighten"). The resolver adds only the data-plane concerns center can't:
+ * a per-principal TTL+ETag CACHE (so per-task prepare-time lookups don't hammer center) and FAIL-CLOSED degrade.
+ *
+ * 🔐 FAIL-CLOSED (core security mandate, prepare-task.ts): an entitlement-resolver outage must NEVER silently
+ * GRANT a capability center may have denied. On a hard fetch error we return `{ allowWorkflows: false }` (deny the
+ * OPTIONAL workflows privilege) and do NOT force the durable gate (that could strand an autonomous run on an
+ * absent operator — the same minimal degrade core applies when the resolver throws). We never serve a STALE
+ * cached GRANT past its TTL on a fresh-fetch failure (a revoked cap must not linger because center blipped).
+ *
+ * The resolver maps center's `EntitlementRuntimeCaps` → the SUBSET core enforces ({@link RuntimeCaps}): center
+ * also carries `allowUltracode` (a shell/UX reasoning-tier cap the engine has no primitive for), which we DROP —
+ * this seam feeds the ENGINE, and `allowUltracode` is enforced at the service settings-resolution layer, not here.
+ */
 import type { RuntimeCaps } from "@sema-agent/core";
 import type { EntitlementRuntimeCaps } from "@sema-agent/registry-core";
 import { fetchPrincipalCaps, type ExecutionRuling } from "./sema-registry.js";
@@ -5,25 +33,103 @@ import type { ScenarioRuling } from "./capabilities/scenarios.js";
 export interface EntitlementsResolverOpts {
     baseUrl: string;
     token: string;
+    /** This worker's name (`SEMA_REGISTRY_WORKER`), passed as `?worker=` so a worker-scoped `wpt_<self>` token can
+     *  resolve its OWN worker's principal caps (caps-only); harmless on a full token (the caps value
+     *  is worker-independent). Omitted ⇒ no `?worker=` (a full-token, non-fleet deployment). */
     worker?: string;
+    /** Per-principal cache TTL (ms). A resolved entitlement is reused for this long before an ETag-conditional
+     *  re-pull, collapsing per-task prepare-time lookups to ~1 center call/principal/TTL. Default 60s. */
     ttlMs?: number;
+    /** Short window (ms) a FAIL-CLOSED deny is cached to avoid hammering center (8s timeout each) on a sustained
+     *  outage, without pinning a deny long past a transient blip. Default min(ttlMs, 10s). */
     denyTtlMs?: number;
+    /** Injected for tests. */
     fetchImpl?: typeof fetch;
     fetchCaps?: typeof fetchPrincipalCaps;
     now?: () => number;
+    /** Observability hook for a resolve failure (defaults to a `runtime_caps_resolve_failed` warn). */
     onError?: (err: Error, principal: string) => void;
 }
+/** Map center's `EntitlementRuntimeCaps` → the subset core's engine enforces. `allowUltracode` (shell/UX) is
+ *  dropped on purpose (not a core primitive); `allowWorkflows` / `forceDurableGate` / `allowFork` are the three the
+ *  engine enforces. Returns undefined when no enforceable cap is set (= no restriction). FAIL-CLOSED defense-in-depth:
+ *  do NOT trust the wire to be boolean. center serializes these as zod-validated booleans, but a schema drift / proxy
+ *  mangling that sent a TRUTHY non-boolean (e.g. the STRING "false") would slip past core's strict `=== false` deny
+ *  check and silently GRANT. So a cap that is PRESENT but not a real boolean is a contract breach → THROW (the
+ *  resolver's catch then fail-closes to deny). `allowFork` (registry-core 0.1.47): the per-principal Fork
+ *  ceiling — core mounts Fork only when `runtimeCaps.allowFork !== false` (prepare-task), tighten-only like allowWorkflows.
+ *
+ *  `allowObservers`(observer 开闸线,core 1.270.0/1.273.0):**极性与 allow* 相反** —
+ *  core 是 `=== true` 显式 opt-in(默认 OFF,undefined ships dark)。registry-core 0.10.3 起该键已收编进
+ *  `EntitlementRuntimeCaps` 类型(此前 0.10.2 走 unknown 宽读透传,现为类型直读,行为零变)。
+ *  **缺键=不写键**(绝不把缺键补成显式 false —— core 是唯一默认源,补 false 语义上等价但会伪造「center
+ *  说过话」的显式判决,污染 env-baseline 合成序,见 applyObserverEnvOptIn)。非 boolean 虽然骗不过 core
+ *  的 `=== true`(不会误 GRANT),但 PRESENT-非-boolean 与 allow* 同属同一 body 的契约破损信号 → 同款 THROW。
+ *
+ *  `autoMode`(core 1.276.0 `RuntimeCaps.autoMode`):auto-mode 分类器 per-principal
+ *  开闸线,极性同 allowObservers(`=== true` 显式 opt-in,默认 OFF;真执行还要 deployment 装配
+ *  `RunnerDeps.autoMode` 分类器面=信任门,center 键只是 entitlement 半场)。registry-core 类型未收编
+ *  → unknown 宽读透传(allowObservers 0.10.2 期同款先例);center 发键即活。 */
 export declare function toCoreRuntimeCaps(ent: EntitlementRuntimeCaps | null | undefined): RuntimeCaps | undefined;
+/** A MISCONFIG diagnostic (review MEDIUM): a worker-scoped `wpt_<self>` pull token REQUIRES `?worker=<self>` to
+ *  resolve per-principal caps — so a `wpt_` token with NO `SEMA_REGISTRY_WORKER` set will 403
+ *  on every caps fetch → fail-closed DENY ALL workflows for ALL principals (correct degrade, but otherwise silent
+ *  bar per-task warns). True ⇒ the caller should log a one-shot BOOT warning so the misconfig is diagnosable.
+ *  (The orchestrator normally injects SEMA_REGISTRY_WORKER alongside a wpt_ token, so this is a hand-misconfig.) */
 export declare function scopedTokenNeedsWorker(token: string, worker: string | undefined): boolean;
+/** The two per-principal faces served off ONE caps fetch + cache. */
 export interface PrincipalEntitlementsClient {
+    /** core's `RunnerDeps.runtimeCapsResolver` seam — FAIL-CLOSED on error (deny workflows/fork). */
     resolveRuntimeCaps: (principal: string | undefined) => Promise<RuntimeCaps | undefined>;
+    /** The resolved per-principal scenario ruling for resolveSpec's gateScenarioRequest —
+     *  FAIL-OPEN on error / older center without scenario keys / no principal (undefined = no governance, legacy passthrough).
+     *  Scenario switching is not a privilege-amplifying face; a center blip must not pin users to `default`. */
     scenarioRuling: (principal: string | undefined) => Promise<ScenarioRuling | undefined>;
+    /** (stage7 P5) The resolved per-principal execution-lane ruling for resolveSpec's
+     *  gateExecutionLane. FAIL-OPEN + audit on error (this phase is "honest-but-bypassable";
+     *  tightening to fail-closed is a future, separate decision) / older center without the execution key / no principal. */
     executionRuling: (principal: string | undefined) => Promise<ExecutionRuling | undefined>;
 }
+/**
+ * Task-admission enforcement of the per-principal execution policy(stage7 P5 的「真强制」
+ * service 半场——壳侧锁定是易用性强制可绕,这里是引擎闸)。The lane is a WORKER-PROCESS identity
+ * (REMOTE_EXEC is boot wiring; there is no per-task lane switch), so the gate is "this worker's lane is not
+ * permitted for this principal ⇒ reject the task": typed 403 `execution_lane_not_allowed` carrying the
+ * allowlist + this worker's lane (machine code on the wire, prose stays with the shell/web).
+ * No ruling / required=false / caps blip ⇒ pass (fail-open + audit). `allowedLanes` is an
+ * OPEN domain — unknown names simply never match this worker's lane.
+ */
 export declare function gateExecutionLane(ruling: ExecutionRuling | undefined, ownLane: string): void;
+/**
+ * Build the per-principal caps client: `resolveRuntimeCaps` matches core's seam signature
+ * `(principal) => Promise<RuntimeCaps | undefined>`; `scenarioRuling` rides the SAME fetch/cache/in-flight
+ * (zero extra center RTT — center attaches the ruling to the caps body). Wire ONLY when a center is
+ * configured (and not in dry-run) — absent ⇒ core sees `undefined` ⇒ NO per-principal restriction, and the
+ * scenario gate sees `undefined` ⇒ legacy body-or-default chain.
+ */
 export declare function createPrincipalEntitlementsClient(opts: EntitlementsResolverOpts): PrincipalEntitlementsClient;
+/** Back-compat face for core's seam-only consumers: the caps half of {@link createPrincipalEntitlementsClient}. */
 export declare function createEntitlementsResolver(opts: EntitlementsResolverOpts): (principal: string | undefined) => Promise<RuntimeCaps | undefined>;
+/** core's `RunnerDeps.runtimeCapsResolver` seam signature (types.d.ts): sync or async, undefined = no caps. */
 export type EntitlementsResolverFn = (principal: string | undefined) => RuntimeCaps | undefined | Promise<RuntimeCaps | undefined>;
+/**
+ * observer 开闸线的 env 半场:`EXPERIMENTAL_OBSERVER_AGENTS=true` 时把
+ * `RuntimeCaps.allowObservers: true` 作为**部署基线**合成进 caps resolver(core 1.270.0/1.273.0 的
+ * observer 面是 `=== true` 显式 opt-in、默认 OFF —— 命名先例=CC 的 `CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS`
+ * env 对儿)。租户姿势(与 FORK_ENABLED/SELF_ORCHESTRATION 同款判别):
+ *  - **单用户部署**(`requirePrincipal !== true`,operator 即用户):env=true 直开 —— 无 center 时静态
+ *    `{allowObservers:true}`;有 center 时作 BASELINE,**center caps 带键则 center 赢**(含显式 false;
+ *    缺键=center 没说话 → env 基线生效。这依赖 toCoreRuntimeCaps 缺键不补 false 的纪律 —— core 是唯一
+ *    默认源,center 只有真说了话才覆盖)。fail-closed 错误 entry(deny)不带 allowObservers 键 → 单用户
+ *    env 基线在 center blip 期间维持(operator 在自己盒子上显式 opt-in 过;observers 非 workflows/fork
+ *    级的放大面,且 deny entry 的两把闸不受影响)。
+ *  - **多租户**(`requirePrincipal === true`):env **不认**,只认 center caps(半配置 fail-loud:置了
+ *    env 却多租户 → 一次 boot warn,行为零变——与 MEMORY_ENGINE_BACKEND 半配置同款姿势)。
+ * 返回合成后的 resolver;两边都无源(无 center、env 无效)⇒ undefined(RunnerDeps 不接线,零行为差)。
+ * ⚠️ 调用方注意:`Boolean(centerResolver)` 才是「entitlement resolver wired」语义(enableForkFromBody /
+ * selfOrchestrationFromBody 的多租户 fail-close 判别),不要改用本函数的返回值判 —— env-only lane 不是
+ * center 背书的 entitlement 源。
+ */
 export declare function applyObserverEnvOptIn(centerResolver: EntitlementsResolverFn | undefined, opts: {
     experimentalObserverAgents: boolean;
     requirePrincipal: boolean;

package/dist/runtime-caps-resolver.js

@@ -2,9 +2,30 @@ import { fetchPrincipalCaps } from "./sema-registry.js";
 import { HttpError } from "./security.js";
 import { createLogger } from "./observability/logger.js";
 const defaultLogger = createLogger();
+/** Map center's `EntitlementRuntimeCaps` → the subset core's engine enforces. `allowUltracode` (shell/UX) is
+ *  dropped on purpose (not a core primitive); `allowWorkflows` / `forceDurableGate` / `allowFork` are the three the
+ *  engine enforces. Returns undefined when no enforceable cap is set (= no restriction). FAIL-CLOSED defense-in-depth:
+ *  do NOT trust the wire to be boolean. center serializes these as zod-validated booleans, but a schema drift / proxy
+ *  mangling that sent a TRUTHY non-boolean (e.g. the STRING "false") would slip past core's strict `=== false` deny
+ *  check and silently GRANT. So a cap that is PRESENT but not a real boolean is a contract breach → THROW (the
+ *  resolver's catch then fail-closes to deny). `allowFork` (registry-core 0.1.47): the per-principal Fork
+ *  ceiling — core mounts Fork only when `runtimeCaps.allowFork !== false` (prepare-task), tighten-only like allowWorkflows.
+ *
+ *  `allowObservers`(observer 开闸线,core 1.270.0/1.273.0):**极性与 allow* 相反** —
+ *  core 是 `=== true` 显式 opt-in(默认 OFF,undefined ships dark)。registry-core 0.10.3 起该键已收编进
+ *  `EntitlementRuntimeCaps` 类型(此前 0.10.2 走 unknown 宽读透传,现为类型直读,行为零变)。
+ *  **缺键=不写键**(绝不把缺键补成显式 false —— core 是唯一默认源,补 false 语义上等价但会伪造「center
+ *  说过话」的显式判决,污染 env-baseline 合成序,见 applyObserverEnvOptIn)。非 boolean 虽然骗不过 core
+ *  的 `=== true`(不会误 GRANT),但 PRESENT-非-boolean 与 allow* 同属同一 body 的契约破损信号 → 同款 THROW。
+ *
+ *  `autoMode`(core 1.276.0 `RuntimeCaps.autoMode`):auto-mode 分类器 per-principal
+ *  开闸线,极性同 allowObservers(`=== true` 显式 opt-in,默认 OFF;真执行还要 deployment 装配
+ *  `RunnerDeps.autoMode` 分类器面=信任门,center 键只是 entitlement 半场)。registry-core 类型未收编
+ *  → unknown 宽读透传(allowObservers 0.10.2 期同款先例);center 发键即活。 */
 export function toCoreRuntimeCaps(ent) {
     if (!ent)
         return undefined;
+    // 宽读(additive wide-read):registry-core 0.10.3 类型未含 autoMode,center 下发先行时走 unknown 读。
     const autoMode = ent.autoMode;
     const badCap = (v) => v !== undefined && typeof v !== "boolean";
     if (badCap(ent.allowWorkflows) || badCap(ent.forceDurableGate) || badCap(ent.allowFork) || badCap(ent.allowObservers) || badCap(autoMode)) {
@@ -23,9 +44,23 @@ export function toCoreRuntimeCaps(ent) {
         caps.autoMode = autoMode;
     return Object.keys(caps).length ? caps : undefined;
 }
+/** A MISCONFIG diagnostic (review MEDIUM): a worker-scoped `wpt_<self>` pull token REQUIRES `?worker=<self>` to
+ *  resolve per-principal caps — so a `wpt_` token with NO `SEMA_REGISTRY_WORKER` set will 403
+ *  on every caps fetch → fail-closed DENY ALL workflows for ALL principals (correct degrade, but otherwise silent
+ *  bar per-task warns). True ⇒ the caller should log a one-shot BOOT warning so the misconfig is diagnosable.
+ *  (The orchestrator normally injects SEMA_REGISTRY_WORKER alongside a wpt_ token, so this is a hand-misconfig.) */
 export function scopedTokenNeedsWorker(token, worker) {
     return token.startsWith("wpt_") && !worker;
 }
+/**
+ * Task-admission enforcement of the per-principal execution policy(stage7 P5 的「真强制」
+ * service 半场——壳侧锁定是易用性强制可绕,这里是引擎闸)。The lane is a WORKER-PROCESS identity
+ * (REMOTE_EXEC is boot wiring; there is no per-task lane switch), so the gate is "this worker's lane is not
+ * permitted for this principal ⇒ reject the task": typed 403 `execution_lane_not_allowed` carrying the
+ * allowlist + this worker's lane (machine code on the wire, prose stays with the shell/web).
+ * No ruling / required=false / caps blip ⇒ pass (fail-open + audit). `allowedLanes` is an
+ * OPEN domain — unknown names simply never match this worker's lane.
+ */
 export function gateExecutionLane(ruling, ownLane) {
     if (!ruling?.required)
         return;
@@ -36,6 +71,13 @@ export function gateExecutionLane(ruling, ownLane) {
         });
     }
 }
+/**
+ * Build the per-principal caps client: `resolveRuntimeCaps` matches core's seam signature
+ * `(principal) => Promise<RuntimeCaps | undefined>`; `scenarioRuling` rides the SAME fetch/cache/in-flight
+ * (zero extra center RTT — center attaches the ruling to the caps body). Wire ONLY when a center is
+ * configured (and not in dry-run) — absent ⇒ core sees `undefined` ⇒ NO per-principal restriction, and the
+ * scenario gate sees `undefined` ⇒ legacy body-or-default chain.
+ */
 export function createPrincipalEntitlementsClient(opts) {
     const ttlMs = opts.ttlMs ?? 60_000;
     const denyTtlMs = opts.denyTtlMs ?? Math.min(ttlMs, 10_000);
@@ -45,6 +87,9 @@ export function createPrincipalEntitlementsClient(opts) {
     const onError = opts.onError ?? ((err, principal) => defaultLogger.warn("runtime_caps_resolve_failed", { principal, err: String(err) }));
     const cache = new Map();
     const inflight = new Map();
+    // Bound cache growth (review L1-1): `principal` is a per-user identity, so a long-lived worker — or a direct-door
+    // caller spoofing many principals — would accumulate one entry forever. On write, when the map crosses a soft cap,
+    // sweep logically-expired entries (TTL is a freshness gate, not eviction). Caps retention to ~the active set.
     const MAX_CACHE = 10_000;
     const putCache = (key, entry) => {
         if (cache.size >= MAX_CACHE) {
@@ -55,17 +100,25 @@ export function createPrincipalEntitlementsClient(opts) {
         }
         cache.set(key, entry);
     };
+    // ONE loader behind both faces: fresh-cached entry → as-is; else fetch (in-flight-deduped) → cache → entry.
     async function load(principal) {
         const cached = cache.get(principal);
         if (cached && cached.expiresAt > now())
             return cached;
+        // Collapse concurrent prepare-time lookups for the SAME principal onto one in-flight fetch.
         const dup = inflight.get(principal);
         if (dup)
             return dup;
         const p = (async () => {
             try {
+                // `cached?.etag` is set only on a real prior entry (an error entry clears it) → an `if-none-match` here can
+                // only 304-confirm a REAL value, never resurrect a stale deny. Pass `opts.worker` as `?worker=<self>` so a
+                // worker-scoped `wpt_<self>` token can resolve its OWN worker's principal caps; harmless
+                // on a full token (caps are worker-independent — the worker only scopes the config view we ignore).
                 const r = await fetchCaps(opts.baseUrl, opts.token, principal, cached?.etag, fetchImpl, opts.worker);
                 if (r === null) {
+                    // 304 — unchanged. We only sent if-none-match because `cached` was a real entry → reuse caps AND the
+                    // rulings (same body, same generation), refresh TTL.
                     const entry = {
                         caps: cached?.caps,
                         ...(cached?.scenario ? { scenario: cached.scenario } : {}),
@@ -76,11 +129,14 @@ export function createPrincipalEntitlementsClient(opts) {
                     putCache(principal, entry);
                     return entry;
                 }
+                // execution ruling shape drift = ruling dropped (fail-open) + THIS audit
+                // line — the "fail-open + audit" posture now covers the wire-drift direction too (previously a
+                // drifted allowedLanes coerced to [] = silent fleet-wide deny-all). Routed through onError (never throws).
                 if (r.executionDrift) {
                     try {
                         onError(new Error(`execution ruling wire drift: ${r.executionDrift}`), principal);
                     }
-                    catch { }
+                    catch { /* observability never breaks the resolver */ }
                 }
                 const entry = {
                     caps: toCoreRuntimeCaps(r.runtimeCaps),
@@ -94,12 +150,18 @@ export function createPrincipalEntitlementsClient(opts) {
             }
             catch (err) {
                 const e = err instanceof Error ? err : new Error(String(err));
+                // Caps face FAIL CLOSED: deny the OPTIONAL amplification caps (workflows + fork); never force the durable
+                // gate on error. Scenario face FAIL OPEN: `scenario` stays undefined (no governance — never pin users to
+                // the default scenario on a center blip; deliberate posture split, see PrincipalEntitlementsClient). Cache the
+                // deny for a SHORT window (bound center hammering on a sustained outage) WITHOUT an etag — so the next
+                // fetch is a full 200 pull that re-reads the real caps the moment center recovers (a 304 can't resurrect
+                // this deny). Write the deny BEFORE onError so a throwing observability hook can't escape before recording.
                 const entry = { caps: { allowWorkflows: false, allowFork: false }, expiresAt: now() + denyTtlMs };
                 putCache(principal, entry);
                 try {
                     onError(e, principal);
                 }
-                catch { }
+                catch { /* an observability hook must never break the resolver */ }
                 return entry;
             }
             finally {
@@ -110,25 +172,48 @@ export function createPrincipalEntitlementsClient(opts) {
         return p;
     }
     return {
+        // No principal = an anonymous/system run with no per-principal identity → no per-principal restriction
+        // (tighten-only: absence falls back to the deployment-level default; core treats undefined as "no caps").
         resolveRuntimeCaps: async (principal) => (principal ? (await load(principal)).caps : undefined),
         scenarioRuling: async (principal) => (principal ? (await load(principal)).scenario : undefined),
         executionRuling: async (principal) => (principal ? (await load(principal)).execution : undefined),
     };
 }
+/** Back-compat face for core's seam-only consumers: the caps half of {@link createPrincipalEntitlementsClient}. */
 export function createEntitlementsResolver(opts) {
     return createPrincipalEntitlementsClient(opts).resolveRuntimeCaps;
 }
+/**
+ * observer 开闸线的 env 半场:`EXPERIMENTAL_OBSERVER_AGENTS=true` 时把
+ * `RuntimeCaps.allowObservers: true` 作为**部署基线**合成进 caps resolver(core 1.270.0/1.273.0 的
+ * observer 面是 `=== true` 显式 opt-in、默认 OFF —— 命名先例=CC 的 `CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS`
+ * env 对儿)。租户姿势(与 FORK_ENABLED/SELF_ORCHESTRATION 同款判别):
+ *  - **单用户部署**(`requirePrincipal !== true`,operator 即用户):env=true 直开 —— 无 center 时静态
+ *    `{allowObservers:true}`;有 center 时作 BASELINE,**center caps 带键则 center 赢**(含显式 false;
+ *    缺键=center 没说话 → env 基线生效。这依赖 toCoreRuntimeCaps 缺键不补 false 的纪律 —— core 是唯一
+ *    默认源,center 只有真说了话才覆盖)。fail-closed 错误 entry(deny)不带 allowObservers 键 → 单用户
+ *    env 基线在 center blip 期间维持(operator 在自己盒子上显式 opt-in 过;observers 非 workflows/fork
+ *    级的放大面,且 deny entry 的两把闸不受影响)。
+ *  - **多租户**(`requirePrincipal === true`):env **不认**,只认 center caps(半配置 fail-loud:置了
+ *    env 却多租户 → 一次 boot warn,行为零变——与 MEMORY_ENGINE_BACKEND 半配置同款姿势)。
+ * 返回合成后的 resolver;两边都无源(无 center、env 无效)⇒ undefined(RunnerDeps 不接线,零行为差)。
+ * ⚠️ 调用方注意:`Boolean(centerResolver)` 才是「entitlement resolver wired」语义(enableForkFromBody /
+ * selfOrchestrationFromBody 的多租户 fail-close 判别),不要改用本函数的返回值判 —— env-only lane 不是
+ * center 背书的 entitlement 源。
+ */
 export function applyObserverEnvOptIn(centerResolver, opts) {
     if (!opts.experimentalObserverAgents)
-        return centerResolver;
+        return centerResolver; // env 未置 = 纯透传(多数部署路径,零成本)
     if (opts.requirePrincipal) {
+        // 多租户不认 env(observer 是 per-principal 治理面,只认 center caps)——半配置 fail-loud 一次。
         opts.warn?.("observer_env_opt_in_ignored", {
             reason: "EXPERIMENTAL_OBSERVER_AGENTS=true is single-user only; a multi-tenant deployment (REQUIRE_PRINCIPAL=true) honors ONLY center caps allowObservers — env ignored, behavior unchanged",
         });
         return centerResolver;
     }
     if (!centerResolver)
-        return () => ({ allowObservers: true });
+        return () => ({ allowObservers: true }); // 单用户无 center:env 即静态开闸
+    // 单用户 + center:env 作 baseline,center 带键(true/false 皆)覆盖;缺键 → baseline 生效。
     return async (principal) => ({ allowObservers: true, ...(await centerResolver(principal)) });
 }
 //# sourceMappingURL=runtime-caps-resolver.js.map

package/dist/runtime-governance.d.ts

@@ -1,17 +1,101 @@
+/**
+ * Runtime governance compiler — the "second baton" (center §10, core 1.114.0): turn the
+ * operator's declarative `runtime.autonomy` + `runtime.commandPolicy` (`@sema-agent/registry-core`,
+ * carried to the service via sema-registry `EffectiveConfig.runtime`) into TIGHTEN-ONLY overrides on the
+ * per-task `TaskSpec`. Pure so it is unit-testable in isolation (the spec is otherwise assembled inside
+ * main.ts's `resolveSpec`).
+ *
+ * 🪤 TWO TRAPS this module exists to NOT fall into (see core
+ * `tool-policy.ts` / `tighten-task-spec.ts` JSDoc):
+ *
+ *   TRAP #1 — `TaskSpec.toolPolicy` OVERRIDES (not merges) `RunnerDeps.toolPolicy` (the runner does
+ *   `spec.toolPolicy ?? deps.toolPolicy`). A bare `spec.toolPolicy = createCoarseCommandNamePolicy(…)` would
+ *   SILENTLY DISCARD the deployment's approval/durable baseline. We compose via {@link tightenTaskSpec}, whose
+ *   toolPolicy rule is `combinePolicies(base, override)` (deny-wins) — the command gate can only ADD denies/asks
+ *   on top of the baseline, never clear it.
+ *
+ *   TRAP #2 — `autonomy` must EXPAND INTO the three core primitives (`handsReadOnly` / `shellGate` / a
+ *   `toolPolicy`), NOT become a parallel enum on the spec (design-research §10: a parallel `autonomy` field +
+ *   `handsReadOnly:true` would conflict). The expansion is tighten-only and routed through `tightenTaskSpec`, so
+ *   `auto` (the loosest mode) can never LOOSEN a stricter base — `tightenTaskSpec` THROWS instead.
+ *
+ * ⚠️ `commandPolicy` is a COARSE name-level filter, NOT a sandbox. `sh -c …` / `$(…)` / pipes / `env X=…` /
+ * path-prefixed commands all bypass the argv[0] match (they route to `ask`, fail-closed, but are not blocked by
+ * name). Real isolation is the `executionEnv` sandbox. Same caveat core documents on `createCoarseCommandNamePolicy`.
+ */
 import { type TaskSpec, type ToolPolicy } from "@sema-agent/core";
+/** A per-command governance rule (registry `runtime.commandPolicy[]`). */
 export type CommandRule = {
     command: string;
     decision: "allow" | "ask" | "deny";
 };
+/** True when `name` names a DELEGATION tool — the subagent tool (CC-187 canonical `"Agent"`, core 1.202
+ *  `DEFAULT_SUBAGENT_TOOL_NAME`; legacy alias `"Task"`). CANONICAL-space compare (`canonicalToolName`) so both
+ *  spellings match — the pre-1.202 raw `!== "Task"` compare in the read-only strip (main.ts) silently stopped
+ *  matching when core renamed the tool (fail-open: a plan-mode / hands-read-only parent could delegate to a
+ *  WRITABLE-hands child, because core does not propagate handsReadOnly to a delegated child).
+ *  core 1.257 (design/136 BREAKING): the standalone `Fork` tool is retired — a fork is now
+ *  `Agent(subagent_type:"fork")`, i.e. an Agent call, already matched by DEFAULT_SUBAGENT_TOOL_NAME. */
 export declare function isDelegationToolName(name: string): boolean;
+/** The hands-read-only DELEGATION STRIP (the main.ts governed-spec site, extracted here so the actual filter —
+ *  not just the name predicate — is pinned by tests): core does not propagate `handsReadOnly` to a delegated
+ *  child, so a read-only (plan-mode) run must not mount a delegation tool at all — the child would get WRITABLE
+ *  hands, defeating the read-only contract. Identity (the same array) when nothing matches, so the caller's
+ *  spec-object churn stays minimal. */
 export declare function stripDelegationTools<T extends {
     name: string;
 }>(tools: readonly T[]): T[];
+/** The operator autonomy mode (registry `runtime.autonomy`). */
 export type Autonomy = "read-only" | "ask" | "plan" | "auto";
+/** 导出给  的枚举式行为钉用(见那里的顶注:从 core 行为反推再比对)。 */
 export declare const COARSE_SHELL_TOOLS_MIRROR: readonly string[];
+/** Validate `commandPolicy` rules — the shape (array of {command, decision}), the `command` (a bare argv[0] name,
+ *  see {@link VALID_COMMAND_NAME}), AND the `decision` enum. Returns the list of human-readable errors (empty =
+ *  OK). Called at config-apply (sema-registry.ts `applyRuntimeHot`) so a malformed rule that BYPASSED the
+ *  registry schema (a hand-edited config.d / a non-conformant publish) is rejected LOUDLY rather than
+ *  silently mis-compiling — review MEDIUM: an out-of-enum `decision` (e.g. "DENY") would otherwise fall through
+ *  {@link compileCommandPolicy}'s `decision==="deny"?…:"ask"` to ASK, silently WEAKENING an intended deny. */
 export declare function validateCommandRules(rules: CommandRule[]): string[];
+/**
+ * Compile `runtime.commandPolicy` (per-command 3-way rules) into a single ToolPolicy, or `undefined` when there
+ * is nothing to govern. The registry model (per-command `allow`/`ask`/`deny`) and core's helper model
+ * (`allow[]` + `deny[]` + `defaultAction`) don't map 1:1, so the compilation picks a mode by the rules present:
+ *
+ *  - **Allowlist mode** — triggered when ANY rule resolves to `allow`. Only `allow` commands pass; `deny` wins;
+ *    EVERY other command — `ask`-decision AND unlisted — falls to `defaultAction:"ask"`.
+ *    🔴 OPERATOR FOOTGUN (documented contract): adding even one `allow` rule flips the whole policy to a strict
+ *    allowlist — previously-passing unlisted commands now ASK.
+ *  - **Blocklist mode** — no `allow` rules. Only `deny` commands are blocked; the rest pass THROUGH to the
+ *    deployment baseline. Per-command `ask` is carried by {@link createCommandAskListPolicy} (the coarse helper
+ *    can't express it). Un-parseable bypass commands fail toward `ask` in both the deny gate and the ask-list.
+ *
+ * Duplicate rules for the SAME command collapse to the STRICTEST decision (`deny > ask > allow`) BEFORE the mode
+ * split, so e.g. a command listed both `allow` and `ask` resolves to `ask` — honoring `combinePolicies`'
+ * strictest-wins (without this, the `allow` rule would shadow the `ask` for that command in allowlist mode).
+ *
+ * Either way the result only ever ADDS asks/denies — composed onto the baseline via `combinePolicies`
+ * (deny-wins) by {@link applyRuntimeGovernance}, so it is tighten-only. (Assumes commands are pre-validated by
+ * {@link validateCommandRules}; an un-matchable command here is simply inert, never a parse error.)
+ */
 export declare function compileCommandPolicy(rules: CommandRule[] | undefined): ToolPolicy | undefined;
+/**
+ * Expand an autonomy mode into TIGHTEN-ONLY `TaskSpec` safety overrides (the three primitives — TRAP #2):
+ *  - `read-only` / `plan` → `handsReadOnly: true` (read + propose, never mutate; the §6 verifier read-only
+ *    boundary). `plan` shares the SAME safety boundary as `read-only`; the "present a plan for approval" intent
+ *    is higher up (UX), not a distinct TaskSpec safety field, so both map to read-only hands.
+ *  - `ask` → `shellGate: "always"` (every `Bash` command tightens to an `irreversible_ask` durable suspend —
+ *    the fail-closed default for an unattended deployment with no parsed classifier).
+ *  - `auto` / `undefined` → `{}` (no extra tightening; still subject to the deployment baseline + commandPolicy).
+ */
 export declare function autonomyOverrides(autonomy: Autonomy | undefined): Partial<TaskSpec>;
+/**
+ * Apply the operator's runtime governance (autonomy + commandPolicy) onto a base `TaskSpec`, TIGHTEN-ONLY, in a
+ * SINGLE {@link tightenTaskSpec} call: commandPolicy compiles to a `toolPolicy` override (combined onto the
+ * baseline by `tightenTaskSpec` — TRAP #1), and autonomy expands to `handsReadOnly` / `shellGate` overrides
+ * (TRAP #2). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any override would LOOSEN a stricter base safety
+ * field — surfacing a misconfiguration loudly instead of silently weakening the gate. Returns `base` untouched
+ * when there is nothing to apply (no autonomy override and no commandPolicy).
+ */
 export declare function applyRuntimeGovernance(base: TaskSpec, governance: {
     autonomy?: Autonomy;
     commandPolicy?: CommandRule[];

package/dist/runtime-governance.js

@@ -1,34 +1,117 @@
+/**
+ * Runtime governance compiler — the "second baton" (center §10, core 1.114.0): turn the
+ * operator's declarative `runtime.autonomy` + `runtime.commandPolicy` (`@sema-agent/registry-core`,
+ * carried to the service via sema-registry `EffectiveConfig.runtime`) into TIGHTEN-ONLY overrides on the
+ * per-task `TaskSpec`. Pure so it is unit-testable in isolation (the spec is otherwise assembled inside
+ * main.ts's `resolveSpec`).
+ *
+ * 🪤 TWO TRAPS this module exists to NOT fall into (see core
+ * `tool-policy.ts` / `tighten-task-spec.ts` JSDoc):
+ *
+ *   TRAP #1 — `TaskSpec.toolPolicy` OVERRIDES (not merges) `RunnerDeps.toolPolicy` (the runner does
+ *   `spec.toolPolicy ?? deps.toolPolicy`). A bare `spec.toolPolicy = createCoarseCommandNamePolicy(…)` would
+ *   SILENTLY DISCARD the deployment's approval/durable baseline. We compose via {@link tightenTaskSpec}, whose
+ *   toolPolicy rule is `combinePolicies(base, override)` (deny-wins) — the command gate can only ADD denies/asks
+ *   on top of the baseline, never clear it.
+ *
+ *   TRAP #2 — `autonomy` must EXPAND INTO the three core primitives (`handsReadOnly` / `shellGate` / a
+ *   `toolPolicy`), NOT become a parallel enum on the spec (design-research §10: a parallel `autonomy` field +
+ *   `handsReadOnly:true` would conflict). The expansion is tighten-only and routed through `tightenTaskSpec`, so
+ *   `auto` (the loosest mode) can never LOOSEN a stricter base — `tightenTaskSpec` THROWS instead.
+ *
+ * ⚠️ `commandPolicy` is a COARSE name-level filter, NOT a sandbox. `sh -c …` / `$(…)` / pipes / `env X=…` /
+ * path-prefixed commands all bypass the argv[0] match (they route to `ask`, fail-closed, but are not blocked by
+ * name). Real isolation is the `executionEnv` sandbox. Same caveat core documents on `createCoarseCommandNamePolicy`.
+ */
 import { canonicalToolName, combinePolicies, createCoarseCommandNamePolicy, DEFAULT_SUBAGENT_TOOL_NAME, parseLeadingCommandName, tightenTaskSpec, } from "@sema-agent/core";
+/** True when `name` names a DELEGATION tool — the subagent tool (CC-187 canonical `"Agent"`, core 1.202
+ *  `DEFAULT_SUBAGENT_TOOL_NAME`; legacy alias `"Task"`). CANONICAL-space compare (`canonicalToolName`) so both
+ *  spellings match — the pre-1.202 raw `!== "Task"` compare in the read-only strip (main.ts) silently stopped
+ *  matching when core renamed the tool (fail-open: a plan-mode / hands-read-only parent could delegate to a
+ *  WRITABLE-hands child, because core does not propagate handsReadOnly to a delegated child).
+ *  core 1.257 (design/136 BREAKING): the standalone `Fork` tool is retired — a fork is now
+ *  `Agent(subagent_type:"fork")`, i.e. an Agent call, already matched by DEFAULT_SUBAGENT_TOOL_NAME. */
 export function isDelegationToolName(name) {
     const c = canonicalToolName(name);
     return c === DEFAULT_SUBAGENT_TOOL_NAME;
 }
+/** The hands-read-only DELEGATION STRIP (the main.ts governed-spec site, extracted here so the actual filter —
+ *  not just the name predicate — is pinned by tests): core does not propagate `handsReadOnly` to a delegated
+ *  child, so a read-only (plan-mode) run must not mount a delegation tool at all — the child would get WRITABLE
+ *  hands, defeating the read-only contract. Identity (the same array) when nothing matches, so the caller's
+ *  spec-object churn stays minimal. */
 export function stripDelegationTools(tools) {
     const kept = tools.filter((t) => !isDelegationToolName(t.name));
     return kept.length === tools.length ? tools : kept;
 }
+/** The shell tool names a command-name gate parses. Mirrors core's (un-exported) `COARSE_SHELL_TOOLS` default so
+ *  the ask-list policy below gates the SAME tools `createCoarseCommandNamePolicy` does. A unit test pins behavior
+ *  (a `Bash` ask-command asks) so a core rename surfaces as a red test, not silent drift.
+ *  Q6 (core 1.161): tool names align to CC — `bash`→`Bash`; the old `bash_readonly` MERGED into `Bash` (read-only is
+ *  now a toolEffect, not a separate tool).
+ *
+ *  🔴 2026-07-26:core 1.414 把默认从 `["Bash"]` 改成 `["Bash","Monitor"]`(Monitor 走同一条执行 seam,此前是
+ *  两条 always-on 门的旁门;core 的端到端实证:同一条 `rm -rf $(cat targets)`,Bash 被拒、**Monitor 零门执行**)。
+ *  我这份镜像因此漂了,后果是 **blocklist 模式下我的 ask-list 不覆盖 Monitor 而 core 的 deny 覆盖**。
+ *  ⚠️ 更要紧的是**旧的钉抓不到这次加名** —— 它只钉了「一条 Bash 的 ask-command 会 ask」,加一个新名字它照样绿
+ *  (core [1707]③ 明确点了这条)。现在的钉改成**枚举式且从 core 的行为反推**:
+ *  `test/coarse-shell-tools-mirror.test.ts` 拿 core 导出的 `createCoarseCommandNamePolicy()`(默认参)去逐个探
+ *  候选工具名,把「core 真的门了哪些」测出来,再断言本常量**等于**那个集合。
+ *  这样做的理由:core 的 `COARSE_SHELL_TOOLS` **未导出**,而扫它的 dist 源码只能挡写法不挡行为
+ *  (core RB-149 的教训:一个变异靠换写法就穿过了源码扫描)。 */
 const COARSE_SHELL_TOOLS = ["Bash", "Monitor"];
+/** 导出给  的枚举式行为钉用(见那里的顶注:从 core 行为反推再比对)。 */
 export const COARSE_SHELL_TOOLS_MIRROR = COARSE_SHELL_TOOLS;
+/**
+ * A per-command ask-list ToolPolicy: a parsed shell command whose `argv[0]` is in `askCommands` tightens to
+ * `ask`; everything else passes (`allow`). core's `createCoarseCommandNamePolicy` has NO per-command ask list
+ * (only `allow[]` / `deny[]` / `defaultAction`), so blocklist-mode "ask before THIS command, pass the rest"
+ * cannot be expressed by it — this thin policy carries the `ask` decisions. It reuses core's
+ * `parseLeadingCommandName` (the SINGLE source-of-truth simple-command parser used by the `Bash` tool and
+ * `createCoarseCommandNamePolicy`), so the argv[0]-bypass surface (operators / pipes / `env=` / path-prefix)
+ * routes to `ask` (fail toward the gate), never silent-allow.
+ */
 function createCommandAskListPolicy(askCommands, tools = COARSE_SHELL_TOOLS) {
     const askSet = new Set(askCommands);
     const shellTools = new Set(tools);
     const ask = (message) => ({ action: "ask", message, decisionReason: "rule" });
     return {
         check(req) {
+            // Out of scope for non-shell tools: this gate only speaks about shell command names. Canonical-space
+            // lookup ("Bash" has no alias today — identity; uniform with every other service policy face, so a
+            // future core alias or a pre-rename durable replay can't slip the gate).
             if (!shellTools.has(canonicalToolName(req.toolName)))
                 return { action: "allow" };
             const command = req.args?.command;
             if (typeof command !== "string")
                 return ask(`tool "${req.toolName}" call has no parseable command string`);
             const parsed = parseLeadingCommandName(command);
+            // Un-parseable (operators / path-prefix / env-assignment) = exactly the argv[0]-bypass surface → gate it.
             if ("reject" in parsed)
                 return ask(`command is not a single simple command (${parsed.reject})`);
             return askSet.has(parsed.name) ? ask(`command "${parsed.name}" requires approval by policy`) : { action: "allow" };
         },
     };
 }
+/** A valid `commandPolicy` rule targets a bare argv[0] command NAME. core's `createCoarseCommandNamePolicy` does
+ *  EXACT `Set` matching (NOT glob, NOT last-match-wins — the §10 verdict deliberately downgraded the original
+ *  `createCommandGlobPolicy` idea), so a glob like `git*` or a path `/usr/bin/rm` or `npm i`
+ *  would SILENTLY never match a parsed argv[0] → the command would slip the gate. We accept only bare-name tokens
+ *  (letters/digits and `. _ - +`, covering `python3.11`/`docker-compose`/`g++`) and reject the rest FAIL-LOUD at
+ *  config-apply. 🔴 Kept ALIGNED with the `@sema-agent/registry-core` contract-layer regex (center fixed the
+ *  glob→exact contract bug in 0.1.26 + publish-validates with this SAME pattern) so the contract gate and this
+ *  defense-in-depth gate agree. The dep is
+ *  `^0.1.26` (additive-compatible), so an additive contract bump stays aligned; a contract regex CHANGE would
+ *  need this updated in lockstep (the two layers are coupled by design, not by a frozen byte-equality guarantee). */
 const VALID_COMMAND_NAME = /^[A-Za-z0-9._+-]+$/;
+/** The three legal per-command decisions (mirrors the registry `runtime.commandPolicy[].decision` enum). */
 const VALID_DECISIONS = new Set(["allow", "ask", "deny"]);
+/** Validate `commandPolicy` rules — the shape (array of {command, decision}), the `command` (a bare argv[0] name,
+ *  see {@link VALID_COMMAND_NAME}), AND the `decision` enum. Returns the list of human-readable errors (empty =
+ *  OK). Called at config-apply (sema-registry.ts `applyRuntimeHot`) so a malformed rule that BYPASSED the
+ *  registry schema (a hand-edited config.d / a non-conformant publish) is rejected LOUDLY rather than
+ *  silently mis-compiling — review MEDIUM: an out-of-enum `decision` (e.g. "DENY") would otherwise fall through
+ *  {@link compileCommandPolicy}'s `decision==="deny"?…:"ask"` to ASK, silently WEAKENING an intended deny. */
 export function validateCommandRules(rules) {
     const errors = [];
     if (!Array.isArray(rules))
@@ -49,9 +132,31 @@ export function validateCommandRules(rules) {
     }
     return errors;
 }
+/**
+ * Compile `runtime.commandPolicy` (per-command 3-way rules) into a single ToolPolicy, or `undefined` when there
+ * is nothing to govern. The registry model (per-command `allow`/`ask`/`deny`) and core's helper model
+ * (`allow[]` + `deny[]` + `defaultAction`) don't map 1:1, so the compilation picks a mode by the rules present:
+ *
+ *  - **Allowlist mode** — triggered when ANY rule resolves to `allow`. Only `allow` commands pass; `deny` wins;
+ *    EVERY other command — `ask`-decision AND unlisted — falls to `defaultAction:"ask"`.
+ *    🔴 OPERATOR FOOTGUN (documented contract): adding even one `allow` rule flips the whole policy to a strict
+ *    allowlist — previously-passing unlisted commands now ASK.
+ *  - **Blocklist mode** — no `allow` rules. Only `deny` commands are blocked; the rest pass THROUGH to the
+ *    deployment baseline. Per-command `ask` is carried by {@link createCommandAskListPolicy} (the coarse helper
+ *    can't express it). Un-parseable bypass commands fail toward `ask` in both the deny gate and the ask-list.
+ *
+ * Duplicate rules for the SAME command collapse to the STRICTEST decision (`deny > ask > allow`) BEFORE the mode
+ * split, so e.g. a command listed both `allow` and `ask` resolves to `ask` — honoring `combinePolicies`'
+ * strictest-wins (without this, the `allow` rule would shadow the `ask` for that command in allowlist mode).
+ *
+ * Either way the result only ever ADDS asks/denies — composed onto the baseline via `combinePolicies`
+ * (deny-wins) by {@link applyRuntimeGovernance}, so it is tighten-only. (Assumes commands are pre-validated by
+ * {@link validateCommandRules}; an un-matchable command here is simply inert, never a parse error.)
+ */
 export function compileCommandPolicy(rules) {
     if (!rules || rules.length === 0)
         return undefined;
+    // Collapse per command to the strictest decision (deny > ask > allow) so a duplicate can't shadow a stricter one.
     const RANK = { deny: 3, ask: 2, allow: 1 };
     const strictest = new Map();
     for (const r of rules) {
@@ -67,9 +172,13 @@ export function compileCommandPolicy(rules) {
     }
     const policies = [];
     if (allow.length > 0) {
+        // Allowlist mode: `allow` passes, `deny` wins, `ask`-decision + unlisted fall to defaultAction "ask".
         policies.push(createCoarseCommandNamePolicy({ allow, deny, defaultAction: "ask" }));
     }
     else {
+        // Blocklist mode: only `deny` blocks; per-command `ask` via the ask-list; unlisted pass through.
+        // (NOTE: never pass `allow: []` to the coarse helper — an empty array is truthy there and would turn it
+        //  into an allowlist that asks on EVERYTHING. Omit allow entirely instead.)
         if (deny.length > 0)
             policies.push(createCoarseCommandNamePolicy({ deny }));
         if (ask.length > 0)
@@ -79,6 +188,15 @@ export function compileCommandPolicy(rules) {
         return undefined;
     return policies.length === 1 ? policies[0] : combinePolicies(...policies);
 }
+/**
+ * Expand an autonomy mode into TIGHTEN-ONLY `TaskSpec` safety overrides (the three primitives — TRAP #2):
+ *  - `read-only` / `plan` → `handsReadOnly: true` (read + propose, never mutate; the §6 verifier read-only
+ *    boundary). `plan` shares the SAME safety boundary as `read-only`; the "present a plan for approval" intent
+ *    is higher up (UX), not a distinct TaskSpec safety field, so both map to read-only hands.
+ *  - `ask` → `shellGate: "always"` (every `Bash` command tightens to an `irreversible_ask` durable suspend —
+ *    the fail-closed default for an unattended deployment with no parsed classifier).
+ *  - `auto` / `undefined` → `{}` (no extra tightening; still subject to the deployment baseline + commandPolicy).
+ */
 export function autonomyOverrides(autonomy) {
     switch (autonomy) {
         case "read-only":
@@ -91,13 +209,21 @@ export function autonomyOverrides(autonomy) {
             return {};
     }
 }
+/**
+ * Apply the operator's runtime governance (autonomy + commandPolicy) onto a base `TaskSpec`, TIGHTEN-ONLY, in a
+ * SINGLE {@link tightenTaskSpec} call: commandPolicy compiles to a `toolPolicy` override (combined onto the
+ * baseline by `tightenTaskSpec` — TRAP #1), and autonomy expands to `handsReadOnly` / `shellGate` overrides
+ * (TRAP #2). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any override would LOOSEN a stricter base safety
+ * field — surfacing a misconfiguration loudly instead of silently weakening the gate. Returns `base` untouched
+ * when there is nothing to apply (no autonomy override and no commandPolicy).
+ */
 export function applyRuntimeGovernance(base, governance) {
     const overrides = { ...autonomyOverrides(governance.autonomy) };
     const coarse = compileCommandPolicy(governance.commandPolicy);
     if (coarse)
         overrides.toolPolicy = coarse;
     if (overrides.toolPolicy === undefined && overrides.handsReadOnly === undefined && overrides.shellGate === undefined) {
-        return base;
+        return base; // nothing to govern → avoid a needless tightenTaskSpec pass
     }
     return tightenTaskSpec(base, overrides);
 }